> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Referral

> Queues a referral for creation in the provider's EMR system.

Referrals are created in the provider's EMR using an asynchronous processing model. Creating a referral this way is not instantaneous.

Instead of leaving your POST request hanging until completion, we immediately return a success response if the request is properly formed. We then notify you via a webhook when the referral has been created in the EMR.

This gives you flexibility around your user experience. For example, when you first make the `/referrals` call you can display a **Processing** status to your user, and when you receive the webhook notification you can update that to **Completed**.

<Note>
  Creating referrals is currently supported for **eClinicalWorks**.
</Note>

### Request Parameters

#### Required Fields

* **patient\_mrn** (string, required): The patient's medical record number. The patient must already be synced to Cobalt.
* **referring\_from\_provider\_ehr\_id** (string, required): EMR ID of the provider the referral is coming **from**.
* **referring\_to\_provider\_ehr\_id** (string, required): EMR ID of the provider the referral is going **to**.
* **direction** (string, required): Direction of the referral — `incoming` or `outgoing`.
* **priority** (string, required): Referral priority — `routine`, `urgent`, or `stat`.
* **reason** (string, required): Reason for the referral.

#### Optional Fields

* **diagnosis\_codes** (array of strings, optional): ICD-10 diagnosis codes associated with the referral.
* **documents** (array, optional): Documents to attach to the referral in the EMR. Each entry is an object with `filename` and `content_base64`. See [Attaching Documents](#attaching-documents) below.

### Direction and Provider Validation

The two provider IDs are validated against different directories depending on the referral's `direction`:

| Direction  | `referring_from_provider_ehr_id` validated against | `referring_to_provider_ehr_id` validated against |
| ---------- | -------------------------------------------------- | ------------------------------------------------ |
| `incoming` | Referring providers directory                      | Providers directory                              |
| `outgoing` | Providers directory                                | Referring providers directory                    |

Pass `0` for a provider ID when there is no provider on that side. Providers must already be synced — use `GET /v1/providers` and `GET /v1/referring-providers` to resolve IDs.

### Attaching Documents

Documents are optional and supplied inline as base64. Each document is an object:

```json theme={null}
{
  "filename": "consult-note.pdf",
  "content_base64": "JVBERi0xLjQKJ..."
}
```

* **filename** must include a file extension (e.g. `report.pdf`).
* **content\_base64** must be non-empty, valid base64.

Documents are attached to the referral in the EMR **after** the referral itself is created. Because the referral already exists at that point, attachment failures are non-fatal: the referral is still created and the webhook reports how many attachments succeeded and failed.

<Note>
  Requests carrying inline documents can be large. The `POST /v1/referrals` endpoint accepts request bodies up to 25 MB.
</Note>

### Example Request

```bash theme={null}
curl -X POST https://api.usecobalt.com/v1/referrals \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "patient_mrn": "1234567",
    "referring_from_provider_ehr_id": "PROV-001",
    "referring_to_provider_ehr_id": "PROV-002",
    "direction": "outgoing",
    "priority": "urgent",
    "reason": "Cardiology consultation",
    "diagnosis_codes": ["I10", "Z87.39"]
}'
```

#### Request with Documents

```bash theme={null}
curl -X POST https://api.usecobalt.com/v1/referrals \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "patient_mrn": "1234567",
    "referring_from_provider_ehr_id": "PROV-001",
    "referring_to_provider_ehr_id": "PROV-002",
    "direction": "outgoing",
    "priority": "routine",
    "reason": "Dermatology referral",
    "documents": [
        { "filename": "consult-note.pdf", "content_base64": "JVBERi0xLjQKJ..." }
    ]
}'
```

### Example Response

```json theme={null}
{
    "success": true,
    "message": "Referral queued for creation. A webhook event will be sent upon completion.",
    "referral_id": "123e4567e89b12d3a456426614174000",
    "job_id": 12345
}
```

The response includes:

* **referral\_id**: Cobalt referral ID (UUID without dashes). This is echoed back in the webhook payload so you can correlate the two.
* **job\_id**: Job execution identifier for tracking the async operation.

### Error Responses

#### Missing Required Field

```json theme={null}
{
    "success": false,
    "message": "Missing required fields: patient_mrn, reason."
}
```

#### Invalid Priority

```json theme={null}
{
    "success": false,
    "message": "Invalid priority. Must be one of: routine, urgent, stat."
}
```

#### Invalid Direction

```json theme={null}
{
    "success": false,
    "message": "Invalid direction. Must be one of: incoming, outgoing."
}
```

#### Invalid Document

```json theme={null}
{
    "success": false,
    "message": "documents[0].filename must include a file extension (e.g. \"report.pdf\")."
}
```

#### Patient Not Found

```json theme={null}
{
    "success": false,
    "message": "Patient with MRN '1234567' not found. Ensure the patient has been synced."
}
```

#### Unknown Provider

```json theme={null}
{
    "success": false,
    "message": "Unknown provider(s): referring_to_provider_ehr_id 'PROV-002' was not found in referring providers. Ensure the provider has been synced."
}
```

#### User Not Found

```json theme={null}
{
    "success": false,
    "message": "User not found."
}
```

This indicates an issue with your access token.

### Webhook Notifications

When the referral has finished processing, we send a webhook to your registered endpoint.

#### Success

```json theme={null}
{
    "id": "<id-of-webhook-response>",
    "access_token_reference_id": "<access-token-reference-id>",
    "object": "event",
    "created": "2026-03-10T10:30:00.000Z",
    "type": "referral.created",
    "job_id": "12345",
    "data": {
        "referral_id": "123e4567e89b12d3a456426614174000",
        "ehr_id": "REF-00123",
        "patient_mrn": "1234567",
        "from_provider_ehr_id": "PROV-001",
        "to_provider_ehr_id": "PROV-002",
        "direction": "outgoing",
        "documents_attached": 1,
        "documents_failed": 0
    }
}
```

Note: `documents_attached` and `documents_failed` are only included when the request contained documents.

#### Failure

```json theme={null}
{
    "id": "<id-of-webhook-response>",
    "access_token_reference_id": "<access-token-reference-id>",
    "object": "event",
    "created": "2026-03-10T10:35:00.000Z",
    "type": "referral.failed",
    "job_id": "12345",
    "data": {
        "referral_id": "123e4567e89b12d3a456426614174000",
        "patient_mrn": "1234567",
        "failure_reason": "Unable to create referral in eCW. ECW rejected the request or returned an unexpected response."
    }
}
```


## OpenAPI

````yaml POST /referrals
openapi: 3.0.0
info:
  title: Cobalt API
  version: 1.0.1
  description: API for interacting with Cobalt's EHR integration services
servers:
  - url: https://api.usecobalt.com/v1
security:
  - ClientCredentials: []
    ClientSecret: []
    AccessToken: []
paths:
  /referrals:
    post:
      summary: Create Referral
      description: >-
        Queues a referral for creation in the provider's EMR system. This is an
        asynchronous operation that returns immediately with a referral_id and
        job_id, and sends a webhook notification upon completion. Optional
        documents supplied inline as base64 are attached to the referral in the
        EMR after it is created.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - patient_mrn
                - referring_to_provider_ehr_id
                - referring_from_provider_ehr_id
                - priority
                - reason
                - direction
              properties:
                patient_mrn:
                  type: string
                  description: >-
                    The patient's medical record number. The patient must
                    already be synced to Cobalt.
                referring_from_provider_ehr_id:
                  type: string
                  description: >-
                    EMR ID of the provider the referral is coming from. For
                    `incoming` referrals this is validated against the referring
                    providers directory; for `outgoing` referrals it is
                    validated against the providers directory. Pass `0` if there
                    is no provider on this side.
                referring_to_provider_ehr_id:
                  type: string
                  description: >-
                    EMR ID of the provider the referral is going to. For
                    `incoming` referrals this is validated against the providers
                    directory; for `outgoing` referrals it is validated against
                    the referring providers directory. Pass `0` if there is no
                    provider on this side.
                direction:
                  type: string
                  enum:
                    - incoming
                    - outgoing
                  description: >-
                    Direction of the referral. `incoming` means the referral is
                    coming into your organization; `outgoing` means it is being
                    sent out.
                priority:
                  type: string
                  enum:
                    - routine
                    - urgent
                    - stat
                  description: Referral priority.
                reason:
                  type: string
                  description: Reason for the referral.
                diagnosis_codes:
                  type: array
                  items:
                    type: string
                  description: >-
                    Optional ICD-10 diagnosis codes associated with the
                    referral.
                documents:
                  type: array
                  description: >-
                    Optional documents to attach to the referral in the EMR.
                    Each entry is supplied inline as base64. Document attachment
                    happens after the referral is created and attachment
                    failures are non-fatal.
                  items:
                    type: object
                    required:
                      - filename
                      - content_base64
                    properties:
                      filename:
                        type: string
                        description: File name including extension (e.g. "report.pdf").
                      content_base64:
                        type: string
                        description: Base64-encoded file content.
      responses:
        '200':
          description: Referral queued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: >-
                      Referral queued for creation. A webhook event will be sent
                      upon completion.
                  referral_id:
                    type: string
                    description: >-
                      Cobalt referral ID (UUID without dashes). Echoed back in
                      the webhook payload.
                  job_id:
                    type: integer
                    description: Job execution identifier for tracking the async operation.
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: 'Invalid priority. Must be one of: routine, urgent, stat.'
        '404':
          description: Patient, provider, or user not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: >-
                      Patient with MRN '1234567' not found. Ensure the patient
                      has been synced.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Error creating referral.
                  referral_id:
                    type: string
                    nullable: true
components:
  securitySchemes:
    ClientCredentials:
      type: apiKey
      in: header
      name: client_id
    ClientSecret:
      type: apiKey
      in: header
      name: client_secret
    AccessToken:
      type: apiKey
      in: header
      name: access_token

````