Send a facility credentialing outreach email
POST/facility-credentialing-outreaches
Triggers a credentialing outreach email for a facility credentialing workflow by dispatching it through SendGrid and persisting a new outreach record. This operation is not idempotent - every call sends another email and creates another outreach record. Call it after the target facility credentialing workflow already exists. For a single-workflow outreach, supply workflowId. For a multi-tenant outreach that fans out to two or more recipient workflows, supply workflowIds (two or more entries) together with initiatingWorkflowId, which must be one of the entries in workflowIds; workflowId and workflowIds are mutually exclusive. Any file attachments must already be uploaded to Google Cloud Storage before calling this endpoint - the request only references them by metadata. For multi-workflow requests only, the initiating tenant (identified by the tenant-id header) must have a fully configured outreach-settings template (subject and body) for the relevant credentialing cycle, or the request is rejected with 422; single-workflow requests do not perform this template check. Multi-workflow requests also require the OUTREACH_MULTI_TENANT_ENABLED feature flag to be enabled, or they are rejected with 503; single-workflow requests are unaffected by this flag.
Request
Responses
- 201
- 400
- 401
- 403
- 422
- 500
- 503
The outreach email was sent and a new outreach record was created. A single-workflow request returns a bare JSON string containing the new outreach record ID. A multi-workflow request returns an object with outreachId (the single outreach record shared by all bundled workflows) and sends (one entry per workflow with workflowId, tenantId, emailId, status of SENT or FAILED, sendgridId, and errorMessage - the last three are null on whichever branch did not occur).
Three distinct 400 shapes are possible. (1) Bean Validation failed on the request body - toEmails, subject, or body was missing or blank; this returns the structured ApiError shape shown in the validationError example. (2) workflowId was omitted and workflowIds does not contain more than one entry, so neither the single-workflow nor multi-workflow path applies; this returns the missingWorkflowId example. (3) initiatingWorkflowId is missing or is not a member of workflowIds on a multi-workflow request; this returns the invalidInitiatingWorkflowId example.
The request has no valid authentication token.
The caller lacks the credentialing-outreach:create permission required to send facility outreach.
Unprocessable request. Multi-workflow requests return OUTREACH_TEMPLATE_MISSING when the initiating tenant's outreach-settings template has no configured subject/body for the outreach type and credentialing cycle being sent. Either path returns OUTREACH_REASON_CYCLE_MISMATCH when the request carries outreach reason/instruction UUIDs configured for the opposite credentialing cycle of the workflow; send reason UUIDs belonging to the workflow's cycle instead.
An unexpected error occurred while sending the outreach.
Two distinct causes return 503. (1) A multi-workflow request was made while the OUTREACH_MULTI_TENANT_ENABLED feature flag is disabled in this environment; see the multiTenantDisabled example. (2) The underlying data service was temporarily unavailable while sending the outreach on either path; see the serviceUnavailable example and retry the request.