> ## 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.

# Fetch Claims

> Refresh claims live from the EMR, for one service date or a list of claim numbers.

Queues an on-demand fetch of claims from the EMR. Use it to refresh claims that the
regular sync no longer pulls, such as older claims that are still open or claims that
were entered long after the date of service. This is asynchronous: the endpoint
returns a `job_id`, Cobalt fetches the claims and stores them, then sends a
`claim.live_fetch_completed` webhook. The refreshed claims are also returned by
[GET /claims](/api-reference/claims/get).

Send exactly one of:

* `service_date`: one date of service (`YYYY-MM-DD`). Every claim with that date is fetched.
* `claim_ids`: 1-25 EMR claim numbers (the `emr_claim_id` of a claim).

## Flow

1. `POST /claims/fetch` returns `202` and a `job_id`.
2. Cobalt fetches each claim from the EMR and stores it. `claim.created` and `claim.updated` webhooks are sent as usual.
3. A `claim.live_fetch_completed` webhook is sent with the fetched claims.

## Example Request

```bash theme={null}
curl -X POST "https://api.usecobalt.com/v1/claims/fetch" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token" \
  -H "Content-Type: application/json" \
  -d '{"claim_ids": ["16382", "16383"]}'
```

## Webhook

`data.claims` has one entry per fetched claim, with `change` set to `created`,
`updated` or `unchanged`. `not_found_claim_ids` lists requested claim numbers the
EMR did not return.

```json theme={null}
{
    "id": "evt_1J9X2q2eZvKYlo2Cmnopqr",
    "job_id": "job_1J9X2q2eZvKYlo2Cmnopqr",
    "object": "event",
    "created": "2026-10-20T22:54:50Z",
    "type": "claim.live_fetch_completed",
    "data": {
        "success": true,
        "claim_ids": ["16382", "16383"],
        "claims": [
            {
                "id": "a1b2c3d4e5f6789012345678abcdef90",
                "emr_claim_id": "16382",
                "service_date": "2026-05-02",
                "claim_status": "PD",
                "claim_status_description": "Paid",
                "total_charge": "161.00",
                "balance": "0.00",
                "change": "updated"
            }
        ],
        "not_found_claim_ids": ["16383"]
    }
}
```

## Status Codes

* **202**: Fetch accepted; results are delivered via webhook and stored claims are returned by `GET /claims`.
* **400**: Neither or both of `service_date` and `claim_ids`, an invalid `service_date`, invalid or more than 25 `claim_ids`, or the connected EMR is not supported.


## OpenAPI

````yaml POST /claims/fetch
openapi: 3.1.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
    description: Production
security:
  - ClientCredentials: []
    ClientSecret: []
    AccessToken: []
paths:
  /claims/fetch:
    post:
      tags:
        - Claims
      summary: Fetch claims
      description: >-
        Queues a live fetch of claims from the EMR for one service date or a
        list of claim numbers. Refreshed claims are stored and returned by GET
        /v1/claims; the result is delivered by webhook.
      operationId: liveFetchClaims
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                service_date:
                  type: string
                  x-supported-emrs:
                    - eClinicalWorks
                  description: >-
                    Service date to refresh (ISO 8601, YYYY-MM-DD). Every claim
                    with this date of service is fetched from the EMR. Send
                    either service_date or claim_ids.
                  example: '2026-03-15'
                claim_ids:
                  type: array
                  items:
                    type: string
                  x-supported-emrs:
                    - eClinicalWorks
                  description: >-
                    EMR claim numbers to refresh (1-25), the emr_claim_id of a
                    claim. Send either service_date or claim_ids.
                  example:
                    - '16382'
                    - '16383'
                callback_urls:
                  type: array
                  items:
                    type: string
                  x-supported-emrs:
                    - eClinicalWorks
                  description: >-
                    URLs to receive the completion webhook for this fetch, in
                    addition to the account webhook.
                  example:
                    - https://example.com/webhooks/cobalt
      responses:
        '202':
          description: Claims fetch accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Claims fetch accepted
                  job_id:
                    anyOf:
                      - type: string
                      - type: number
                    example: 12345
                required:
                  - success
                  - message
                  - job_id
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
                example: false
              message:
                type: string
                example: Request could not be completed.
            required:
              - success
              - message
          example:
            success: false
            message: Bad request — missing or invalid parameters
    Unauthorized:
      description: Unauthorized — missing or invalid credentials
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
                example: false
              message:
                type: string
                example: Request could not be completed.
            required:
              - success
              - message
          example:
            success: false
            message: Unauthorized — missing or invalid credentials
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                enum:
                  - false
                example: false
              message:
                type: string
                example: Request could not be completed.
            required:
              - success
              - message
          example:
            success: false
            message: Internal server error
  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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.