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

# Coordinate benefits across payers

> Asks a payer you already know the patient has what other coverage they have, and which coverage pays first. **Answered inline** — there is nothing to poll.

The organization comes from your access token's organization claim; there is no body field or query parameter for it. A token carrying no claim is a 401.

The response carries the payer's own verdict. There is no verdict field of ours, no `coverages` array and no recommendation: read `coordination_of_benefits.classification` and `coordination_details`.

**A payer rejection is a 200.** The patient could not be matched, and the rejection is reported as `status` and `status_reason` — a completed check, not a failed request.

**A payer that does not answer coordination checks is a 400**, refused before any payer is contacted. Original Medicare and the Part B MACs are in that group. Nothing is stored for a refused check, so you may ask again as soon as the payer becomes supported.

**Repeat submissions are absorbed for five minutes.** An identical check inside that window returns the stored answer with `deduplicated: true` and makes no payer call. Two identical requests sent at the same moment are two checks.

This endpoint takes no state.

**Not yet enabled on the production edge.** This path appears in the reference but answers 404 against the production server, and there is no committed enablement date. Do not sequence a launch behind it — confirm status with your OLH implementation contact before designing against it.

**Permissions:** `eligibility:write`



## OpenAPI

````yaml /openapi.json post /benefit-coordinations
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /benefit-coordinations:
    post:
      tags:
        - Eligibility
      summary: Coordinate benefits across payers
      description: >-
        Asks a payer you already know the patient has what other coverage they
        have, and which coverage pays first. **Answered inline** — there is
        nothing to poll.


        The organization comes from your access token's organization claim;
        there is no body field or query parameter for it. A token carrying no
        claim is a 401.


        The response carries the payer's own verdict. There is no verdict field
        of ours, no `coverages` array and no recommendation: read
        `coordination_of_benefits.classification` and `coordination_details`.


        **A payer rejection is a 200.** The patient could not be matched, and
        the rejection is reported as `status` and `status_reason` — a completed
        check, not a failed request.


        **A payer that does not answer coordination checks is a 400**, refused
        before any payer is contacted. Original Medicare and the Part B MACs are
        in that group. Nothing is stored for a refused check, so you may ask
        again as soon as the payer becomes supported.


        **Repeat submissions are absorbed for five minutes.** An identical check
        inside that window returns the stored answer with `deduplicated: true`
        and makes no payer call. Two identical requests sent at the same moment
        are two checks.


        This endpoint takes no state.


        **Not yet enabled on the production edge.** This path appears in the
        reference but answers 404 against the production server, and there is no
        committed enablement date. Do not sequence a launch behind it — confirm
        status with your OLH implementation contact before designing against it.


        **Permissions:** `eligibility:write`
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BenefitCoordinationRequest'
      responses:
        '200':
          description: >-
            The check completed. A payer rejection is also a completed check and
            answers 200, not a 4xx.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BenefitCoordination'
                  request_id:
                    type: string
                    example: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
                required:
                  - data
                  - request_id
        '400':
          description: >-
            Your request failed validation, or it was refused upstream — a payer
            that does not answer coordination checks lands here. Nothing is
            stored for a refused check, so a retry is a fresh check. Read
            `error.message` for the cause.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: 'Invalid request: subscriber.date_of_birth'
                  error_code: BAD_REQUEST
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing the `eligibility:write` permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: insufficient_permissions
                  error_code: FORBIDDEN
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '429':
          description: >-
            Too many requests: a poll inside the interval the previous read
            reported, a throttled request, or exhausted shared real-time
            capacity. The message is the same on every eligibility endpoint and
            names no duration, because the window behind each of those differs.
            Back off and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: Too many requests. Retry later.
                  error_code: TOO_MANY_REQUESTS
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
        '500':
          description: >-
            Something failed that names no cause. `error_code` is always
            `UNHANDLED_EXCEPTION` and the message is fixed prose — quote
            `request_id` to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  message: Internal server error
                  error_code: UNHANDLED_EXCEPTION
                request_id: c1a7f3e2-5b9d-4a68-9f21-7d3c4b6e8a05
      security:
        - serviceToken:
            - eligibility:write
components:
  schemas:
    BenefitCoordinationRequest:
      type: object
      additionalProperties: false
      required:
        - subscriber
        - payer_id
      properties:
        subscriber:
          $ref: '#/components/schemas/BenefitCoordinationSubscriber'
        payer_id:
          type: string
          description: >-
            The payer you already know the patient has, and the payer that is
            asked. Find it with `GET /payers`. Aliases and mixed case both
            resolve; surrounding whitespace is trimmed before the id is sent.
          example: '60054'
        date_of_service:
          type: string
          description: >-
            Calendar date (`YYYY-MM-DD`) or a full ISO datetime; defaults to
            today. A future date is accepted, for a scheduled visit; a date more
            than two years old is a 400.
          example: '2026-08-10'
        dependent:
          $ref: '#/components/schemas/BenefitCoordinationDependent'
    BenefitCoordination:
      type: object
      additionalProperties: false
      required:
        - payer_id
        - deduplicated
      description: >-
        The payer's coordination verdict. There is no verdict field of ours, no
        `coverages` array and no recommendation: read
        `coordination_of_benefits.classification` and `coordination_details`.


        **A rejection and an answer are two shapes.** A rejection reports
        `status` and `status_reason` and nothing about coverage; an answer
        reports the verdict and its detail and carries no `status`.
      properties:
        payer_id:
          type: string
          description: >-
            The payer id you sent, under the spelling you sent it.
            `payer.identification` is not this value — send `60054` and it can
            come back as `AETNA-USH`.
          example: '60054'
        deduplicated:
          type: boolean
          description: >-
            `true` when the five-minute window answered from the stored result
            instead of asking the payer.
          example: false
        status:
          type: string
          description: >-
            Present only when the payer returned a rejection instead of an
            answer. Same vocabulary as a verification's `result.status`, so
            branch on the family before the first `.`. **A payer rejection is
            still a 200** — a completed check whose answer is that the patient
            could not be matched.
          example: error.member.name
        status_reason:
          type: string
          description: >-
            Finer than `status`, and drawn from the same closed set a
            verification's `status_reason` uses.
          example: error.member.not_found
        coordination_of_benefits:
          type: object
          description: The payer's verdict. Absent on a rejection.
          properties:
            classification:
              type: string
              description: The payer's own classification string, carried as sent.
              example: CobInstanceExistsPrimacyDetermined
            instance_exists:
              type: boolean
            primacy_determined:
              type:
                - boolean
                - 'null'
              description: >-
                `null` is the payer stating no primacy, which is not the same as
                stating `false`.
            coverage_overlap:
              type: boolean
            benefit_overlap:
              type: boolean
        coordination_details:
          type: array
          description: The payer's benefit statements. Absent on a rejection.
          items:
            $ref: '#/components/schemas/BenefitCoordinationDetail'
        payer:
          type: object
          properties:
            name:
              type: string
              example: CIGNA
            identification:
              type: string
              description: The payer's canonical alias for itself, not what you sent.
              example: CIGNA-HCIN
        subscriber:
          $ref: '#/components/schemas/BenefitCoordinationPerson'
        dependent:
          $ref: '#/components/schemas/BenefitCoordinationPerson'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            error_code:
              type: string
          required:
            - message
            - error_code
        request_id:
          type: string
      required:
        - error
        - request_id
    BenefitCoordinationSubscriber:
      type: object
      additionalProperties: false
      required:
        - first_name
        - last_name
        - date_of_birth
      description: >-
        The policyholder, or a dependent who holds their own member id. **At
        least one of `member_id` or `ssn` is required.**
      properties:
        first_name:
          type: string
          example: Phillip
        last_name:
          type: string
          example: Mozee
        date_of_birth:
          type: string
          description: Calendar date (`YYYY-MM-DD`) or a full ISO datetime.
          example: '1957-11-10'
        member_id:
          type: string
          description: Required unless `ssn` is supplied.
          example: H77465998
        ssn:
          type: string
          pattern: ^\d{9}$
          description: >-
            Nine digits, **no separators** — unlike the Medicare id lookup,
            which also accepts hyphens. An alternative to `member_id`, not an
            addition to it. Your request is not stored; where the payer echoes
            an SSN back, that value is returned to you and stored with the
            answer.
    BenefitCoordinationDependent:
      type: object
      additionalProperties: false
      required:
        - first_name
        - last_name
        - date_of_birth
      description: >-
        Send this **only** for a patient covered under someone else's policy who
        has no member identifier of their own — and then `subscriber` must carry
        the policyholder, not the patient.


        A dependent who does hold their own member identifier goes in
        `subscriber` instead and this object is omitted. Getting the two the
        wrong way round produces a payer rejection rather than a wrong answer.


        Two dependents on one policy are two different questions, and are never
        served one another's answer.
      properties:
        first_name:
          type: string
          example: Dana
        last_name:
          type: string
          example: Mozee
        date_of_birth:
          type: string
          description: Calendar date (`YYYY-MM-DD`) or a full ISO datetime.
          example: '2015-04-22'
        ssn:
          type: string
          pattern: ^\d{9}$
          description: Optional. Nine digits, no separators.
    BenefitCoordinationDetail:
      type: object
      description: >-
        One benefit statement from the payer. A coordination entry names another
        payer through `related_entities`. **Read `service_type_codes` before
        acting on a payer name** — a dental or vision entry is not a finding
        about medical care.
      properties:
        code:
          type: string
          example: R
        name:
          type: string
          example: Other or Additional Payor
        service_type_codes:
          type: array
          items:
            type: string
        service_types:
          type: array
          items:
            type: string
        dates:
          type: object
          properties:
            benefit_begin:
              type: string
            coordination_of_benefits:
              type: string
            period_start:
              type: string
        related_entities:
          type: array
          items:
            type: object
            properties:
              identifier:
                type: string
                description: What the entity is to this statement.
                example: Primary Payer
              name:
                type: string
              first_name:
                type: string
              middle_name:
                type: string
              last_name:
                type: string
              identification:
                type: string
              identification_value:
                type: string
        subscriber:
          type: object
          properties:
            date_of_birth:
              type: string
        dependent:
          type: object
          properties:
            first_name:
              type: string
            last_name:
              type: string
            member_id:
              type: string
            date_of_birth:
              type: string
            family_seq_num:
              type: string
            relation_to_subscriber:
              type: string
            relation_to_subscriber_code:
              type: string
    BenefitCoordinationPerson:
      type: object
      description: The person the payer matched, as the payer holds them.
      properties:
        first_name:
          type: string
        middle_name:
          type: string
        last_name:
          type: string
        date_of_birth:
          type: string
        gender:
          type: string
        member_id:
          type: string
        group_number:
          type: string
        relation_to_subscriber:
          type: string
        relation_to_subscriber_code:
          type: string
        address:
          $ref: '#/components/schemas/EligibilityAddress'
        ssn:
          type: string
          description: >-
            The payer returns one on some checks submitted without it. Carried
            because withholding it would hide what the payer holds.
    EligibilityAddress:
      type: object
      additionalProperties: false
      required:
        - state
      description: >-
        A postal address, nested under the person it belongs to. Only the
        insurance discovery request accepts more than `state`; the other three
        take the state alone and reject any other address field with a 400.
      properties:
        state:
          type: string
          minLength: 2
          maxLength: 2
          description: >-
            Two-letter US state code, case-insensitive. The state the care takes
            place in, not a mailing address: it selects the OpenLoop entity that
            submits the inquiry.
          example: WI
        line_1:
          type: string
        line_2:
          type: string
        city:
          type: string
        zip:
          type: string
          example: '53703'
  securitySchemes:
    serviceToken:
      type: oauth2
      description: >-
        Service (M2M) access token issued by POST /auth/token using the
        client_credentials grant. Required scopes, where known, are listed on
        each operation below.
      flows:
        clientCredentials:
          tokenUrl: https://api.openloophealth.com/v0.1/auth/token
          scopes: {}

````

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