Send a practitioner credentialing outreach email
POST/credentialing-outreaches
Sends a credentialing outreach email for a practitioner workflow via SendGrid and persists an outreach record in the DAL. Call this after a practitioner credentialing workflow is active and you need to contact one or more recipients; for facility credentialing outreach, use the facility-specific outreach endpoint instead. The request body must include at least one recipient in toEmails. For a single-workflow outreach, supply workflowId. For a multi-workflow (multi-tenant) outreach, supply workflowIds (two or more entries) and initiatingWorkflowId, which must be a member of workflowIds; attachments are not permitted on multi-workflow requests. Multi-tenant outreach must be enabled via the OUTREACH_MULTI_TENANT_ENABLED feature flag; when disabled, a multi-workflow request returns 503. This operation is not idempotent - each call dispatches a new email via SendGrid and persists a new outreach record. Shared credentialing send: when initiatingWorkflowId belongs to a shared credentialing workflow, workflowIds (one or more of its member workflows) selects the tenants the one email covers. Every selected workflow must be a member (400 SHARED_OUTREACH_WORKFLOW_NOT_IN_RUN), none may be locked (409 SHARED_OUTREACH_TENANT_LOCKED), the caller needs outreach permission in every selected tenant (403 TENANT_OUTREACH_NOT_PERMITTED), and reasons must come from the anchor group's outreach settings (400 SHARED_OUTREACH_REASON_NOT_CONFIGURED). Nothing is sent when a check fails. The outreach records participatingTenants; CC is sent as given; no workflow status changes.
Request
Responses
- 201
- 400
- 401
- 403
- 409
- 422
- 500
- 503
Outreach email sent successfully. The response body shape depends on the request type: a single-workflow request (workflowId supplied) returns a bare string containing the created outreach record ID; a multi-workflow request (workflowIds with more than one entry) returns a MultiTenantOutreachResult object with an outreachId and a sends array describing the per-workflow send status.
The request failed validation: toEmails is empty, both workflowId and workflowIds are missing, initiatingWorkflowId is missing or not a member of workflowIds for a multi-workflow request, or attachments were supplied on a multi-workflow request. The response body shape differs by cause: bean-validation failures (e.g. empty toEmails) return the ApiError shape; the workflowId/initiatingWorkflowId business-rule checks return a {code, message} object instead.
Unauthorized - Authentication required
Forbidden - User does not have required permissions
Shared credentialing send only: a selected tenant's member workflow is locked. Nothing was sent; each error names one locked tenant in rejectedValue.
Unprocessable request: either the initiating tenant's outreach-settings template is missing or incomplete for the outreach type and credentialing cycle being sent (OUTREACH_TEMPLATE_MISSING), or the request carries outreach reason/instruction UUIDs configured for the opposite credentialing cycle of the workflow (OUTREACH_REASON_CYCLE_MISMATCH). Fix the settings or send reason UUIDs belonging to the workflow's cycle, then retry.
Internal Server Error - An unexpected error occurred. The body is a plain string, not the ApiError shape.
A multi-workflow request was made but the OUTREACH_MULTI_TENANT_ENABLED feature flag is disabled in this environment.