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

# Create Claim

> Creating and submitting an out-of-network vision claim

The claim object contains all the information required to send a claim to an insurer:

* insurer
* patient details
* primary member details (can be same as patient details)
* list of services

During claim submission, the API validates the claim payload against known insurer requirements and will reject claims that we know will be rejected by the insurer. However, this does not guarantee the opposite; a claim accepted by the API can still be rejected by the insurer.

Insurers can change their claim requirements without notifying us. When this happens, as soon as we understand the new requirements, we will update the validation rules and inform you. It is advisable to be prepared to adopt the updated rules as quickly as possible.

## Request Parameters

The main fields of claim are:

* `patient`: JSON object, representing patient details
* `primary_member`: JSON object, representing primary patient member
* `services`: list of JSON objects, representing services that can be reimbursed

Both `patient` and `primary_member` must be provided even if the claim is created for a primary member. In this case, both the `patient` object and `primary_member` object must contain the same data.


## OpenAPI

````yaml POST /api/auth/v1/claims/
openapi: 3.0.2
info:
  title: Anagram backend
  version: 1.0.0
servers:
  - url: https://api.anagram.care
    description: Authenticated API
security:
  - ApiToken: []
tags:
  - name: public-auth_Eligibility Request
    x-displayName: Eligibility Request
    description: >-
      Requesting patient's eligibility uses the following parameters:


      - First name (required)

      - Last name (required)

      - Date of birth (required)

      - Last four digits from SSN (optional)

      - Zip code (required)

      - Insurer Member ID (optional)

      - Request UID (optional)


      This call is asynchronous, it initiates an eligibility search and returns
      a UID assigned to this request.

      The result will be returned in two ways:

      - Via active [webhooks](https://provider.anagram.care/webhooks) once
      available - preferred.

      Request UID will be included in payload.

      - By calling the "Eligibility Result" endpoint - only to be used as
      fallback. Request UID is required.


      If specifying a UID, ensure it is unique. If omitted one will be generated
      automatically

      and included in the response for this API call.


      Authentication is required for this endpoint. Access token can be obtained

      in [provider app](https://provider.anagram.care/). Access token must be
      sent in `Authorization` header,

      prefaced with `API `:


      `Authorization: Api <key generated in provider app>`


      The response will contain the request UID or a validation error.


      Error examples:

      ```

      {
          "errors": {"$": ["Wrong insurer code"]}
      }

      ```

      ```

      {
          "errors": {
              "patient": {
                  "first_name": {"$": ["This field cannot be blank."]}
              }
          }
      }

      ```


      For testing purposes, you can include cheat codes in the request. Cheat
      codes can be provided in the fields

      `first_name`, `last_name`, and `member_id`. Here are some examples of
      cheat codes:


      - `mark_used`: This cheat code marks all benefits as used.


      - `dt_exam_used`: This cheat code marks exam benefit as used.


      - `no_oon`: Removes all out-of-network benefits from the plan.


      - `no_inn`: Removes all in-network benefits from the plan. You can use
      both `no_oon` and `no_inn` codes together to

      generate a plan without any benefits.


      - `delay_10`, `delay_30`: These codes introduce a delay in the response,
      causing it to wait for either 10 or 30

      seconds before providing an answer.


      - `big_family`: This cheat code adds multiple persons to the result.


      - `not_found`: Using this cheat code will delete all results.


      - `in_err_int`: This cheat code simulates a problem and triggers the
      `unexpected_error`.
  - name: public-auth_Eligibility Result
    x-displayName: Eligibility Result
    description: >-
      Eligibility search result will be sent to all active webhooks once
      available.

      As a fallback, you may call this endpoint to check result status and
      obtain the result.


      ### Status


      The `status` field in the response can have one of the following values:


      `complete` - Indicates that the search has been completed.


      `processing` - Signifies that the search is currently in progress, and it
      is recommended to retry the request later.


      `error` - Suggests that the search dit not finished successfully, and you
      can find descriptions of error codes

      below.


      ### Error codes


      `insurer_problem` – Insurer not available, please try again later


      `unexpected_error` – Unknown error


      ### Webhooks


      Add webhooks to receive results in the [provider
      app](https://provider.anagram.care/webhooks).

      Webhook payload will be identical to the response of this endpoint.


      When configuring a webhook you can provide a secret to sign the webhook
      payload

      and check the signature on the server side.


      Signature will be sent in `X-Signature` header in request to webhook
      endpoint.


      Signature is a request raw data signed with secret by HMAC SHA256
      algorithm. Python example:


      ```

      import hashlib

      import hmac


      def get_signature(secret_key: str, payload: str) -> str:
          return hmac.new(secret_key.encode(), payload.encode(), hashlib.sha256).hexdigest()
      ```
  - name: public-auth_Eligibility Details Request
    x-displayName: Eligibility Details Request
    description: |-
      Requesting plan for patient's eligibility uses the following parameters:

      - Initial request uid (required)
      - Result id from initial request (required)
      - Person id from initial request (required)
      - Details request UID (optional)
  - name: public-auth_Patient
    x-displayName: Patient
  - name: public-auth_Patient eligibility link
    x-displayName: Patient eligibility link
paths:
  /api/auth/v1/claims/:
    post:
      summary: Submit a claim
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - paid_amount
                - services
                - primary_member
                - patient
              properties:
                paid_amount:
                  type: number
                  format: double
                  description: Amount paid by patient for services in claim
                is_aob_enabled:
                  type: boolean
                  description: >-
                    Whether to accept the assignment of the benefits. `false` by
                    default
                metadata:
                  type: object
                  description: >-
                    Allows to store arbitrary metadata within the claim. You
                    should use `patient.account_number` to link claims to your
                    system.
                services:
                  type: array
                  description: List of services in claim
                  minItems: 1
                  maxItems: 6
                  items:
                    type: object
                    required:
                      - codes
                      - quantity
                      - cost
                      - date
                    properties:
                      quantity:
                        type: integer
                        minimum: 1
                        example: 1
                      cost:
                        type: string
                        format: double
                        minimum: 0
                        exclusiveMinimum: true
                        example: '299.95'
                        description: Cost of one service
                      date:
                        type: string
                        format: date
                        example: '2025-04-15'
                        description: Date of service
                      codes:
                        type: array
                        description: List of CPT predefined codes
                        items:
                          type: string
                      diagnosis_codes:
                        type: array
                        description: >
                          HCPCS diagnosis codes (per service). Required in at
                          least one service per claim for VSP.
                        items:
                          type: string
                primary_member:
                  type: object
                  description: Information about primary member (primary subscriber)
                  required:
                    - first_name
                    - last_name
                    - dob
                    - address
                    - phone
                    - insurer_code
                    - member_id
                  properties:
                    member_id:
                      type: string
                      description: >-
                        Member ID or Subscriber ID. Optional for VSP and Cigna
                        Vision when `ssn_last_four` is provided
                      example: M1328422
                    ssn_last_four:
                      type: string
                      description: SSN Last Four
                      example: '0924'
                      pattern: \d\d\d\d
                    first_name:
                      type: string
                      description: First name
                    last_name:
                      type: string
                      description: Last name
                    dob:
                      type: string
                      format: date
                      description: Date of Birth
                      example: '1985-03-15'
                    sex:
                      type: string
                      enum:
                        - male
                        - female
                      description: Member sex. Required for VSP
                    email:
                      type: string
                      description: Member email
                      example: foo@gmail.com
                      format: email
                    address:
                      type: object
                      description: Member address
                      required:
                        - line1
                        - city
                        - zipcode
                        - state
                      properties:
                        line1:
                          type: string
                          example: Long st. 65
                        line2:
                          type: string
                          example: ap. 231
                        recipient:
                          type: string
                          example: Mr Smith
                        city:
                          type: string
                          example: Santa Monica
                        zipcode:
                          type: string
                          pattern: |
                            \d{5}|\d{5}-\d{4}
                          example: 99577
                        state:
                          type: string
                          pattern: '[A-X]{2}'
                          example: CA
                    phone:
                      type: string
                      description: Member phone
                      example: '1234567890'
                      pattern: \d{10}
                    insurer_code:
                      type: string
                      description: Insurer identifier
                      example: insurer:vision:vsp
                patient:
                  type: object
                  description: Information about patient
                  required:
                    - type
                    - first_name
                    - last_name
                    - dob
                    - address
                    - member_id
                  properties:
                    type:
                      type: string
                      enum:
                        - self
                        - spouse
                        - child
                        - other
                      description: Type of patient. `self` in case of primary member
                      example: spouse
                    member_id:
                      type: string
                      description: >-
                        Optional for VSP, Cigna Vision, Davis Vision, Spectera,
                        and Superior Vision
                    ssn_last_four:
                      type: string
                      description: SSN Last Four
                      example: '0924'
                      pattern: \d\d\d\d
                    first_name:
                      type: string
                      description: First name
                    last_name:
                      type: string
                      description: Last name
                    dob:
                      type: string
                      format: date
                      description: Date of Birth
                      example: '1985-03-15'
                    sex:
                      type: string
                      enum:
                        - male
                        - female
                      description: Member sex. Required for VSP
                    email:
                      type: string
                      description: Member email
                      example: foo@gmail.com
                      format: email
                    address:
                      type: object
                      description: Member address
                      required:
                        - line1
                        - city
                        - zipcode
                        - state
                      properties:
                        line1:
                          type: string
                          example: Long st. 65
                        line2:
                          type: string
                          example: ap. 231
                        recipient:
                          type: string
                          example: Mr Smith
                        city:
                          type: string
                          example: Santa Monica
                        zipcode:
                          type: string
                          pattern: |
                            \d{5}|\d{5}-\d{4}
                          example: '99577'
                        state:
                          type: string
                          pattern: '[A-X]{2}'
                          example: CA
                    phone:
                      type: string
                      description: Member phone
                      example: '1234567890'
                      pattern: \d{10}
                    account_number:
                      type: string
                      maxLength: 25
                      description: Patient account number in an external system
                location_code:
                  type: string
                  description: >-
                    Identifies the location that the claim will be linked to.
                    When this field is empty, the claim will be linked with the
                    default location. Example: LOC4242B
            examples:
              Create claim:
                value:
                  patient:
                    dob: '1998-02-11'
                    first_name: Max
                    last_name: Smith
                    type: child
                    address:
                      line1: String name
                      city: City
                      zipcode: '12332'
                      state: CA
                  primary_member:
                    address:
                      city: City
                      line1: String name
                      state: CA
                      zipcode: '12332'
                    dob: '1988-10-11'
                    first_name: John
                    insurer_code: insurer:demo:vision
                    last_name: Smith
                    member_id: A123455
                    phone: '0987654321'
                    ssn_last_four: '1242'
                  services:
                    - codes:
                        - S0504
                      cost: '12.22'
                      date: '2022-02-11'
                      quantity: 2
                      diagnosis_codes:
                        - H52.10
                    - codes:
                        - V2781
                      cost: '44.21'
                      date: '2022-02-11'
                      quantity: 1
                  paid_amount: '68.65'
                summary: Create a claim
      responses:
        '201':
          description: Claim created successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - paid_amount
                  - code
                  - services
                  - primary_member
                  - patient
                properties:
                  status:
                    type: string
                  paid_amount:
                    type: string
                    format: double
                  code:
                    type: string
                  is_aob_enabled:
                    type: boolean
                  metadata:
                    type: object
                  services:
                    type: array
                    items:
                      type: object
                      required:
                        - codes
                        - quantity
                        - cost
                        - date
                        - diagnosis_codes
                      properties:
                        quantity:
                          type: integer
                        cost:
                          type: string
                          format: double
                        date:
                          type: string
                          format: date
                        codes:
                          type: array
                          items:
                            type: string
                        diagnosis_codes:
                          type: array
                          items:
                            type: string
                  primary_member:
                    type: object
                    required:
                      - first_name
                      - last_name
                      - dob
                      - address
                      - phone
                      - insurer_code
                    properties:
                      member_id:
                        type: string
                      ssn_last_four:
                        type: string
                      first_name:
                        type: string
                      last_name:
                        type: string
                      dob:
                        type: string
                        format: date
                      sex:
                        type: string
                        enum:
                          - male
                          - female
                        nullable: true
                      email:
                        type: string
                        nullable: true
                      address:
                        type: object
                        required:
                          - line1
                          - city
                          - zipcode
                          - state
                        properties:
                          line1:
                            type: string
                          line2:
                            type: string
                            nullable: true
                          recipient:
                            type: string
                            nullable: true
                          city:
                            type: string
                          zipcode:
                            type: string
                          state:
                            type: string
                      phone:
                        type: string
                      insurer_code:
                        type: string
                  patient:
                    type: object
                    required:
                      - type
                      - first_name
                      - last_name
                      - dob
                      - address
                    properties:
                      type:
                        type: string
                      member_id:
                        type: string
                        nullable: true
                      ssn_last_four:
                        type: string
                        nullable: true
                      first_name:
                        type: string
                      last_name:
                        type: string
                      dob:
                        type: string
                        format: date
                      sex:
                        type: string
                        enum:
                          - male
                          - female
                        nullable: true
                      email:
                        type: string
                        nullable: true
                      address:
                        type: object
                        required:
                          - line1
                          - city
                          - zipcode
                          - state
                        properties:
                          line1:
                            type: string
                          line2:
                            type: string
                            nullable: true
                          recipient:
                            type: string
                            nullable: true
                          city:
                            type: string
                          zipcode:
                            type: string
                          state:
                            type: string
                      phone:
                        type: string
                        nullable: true
                      account_number:
                        type: string
              examples:
                Created claim:
                  value:
                    code: CLM21T
                    patient:
                      address:
                        city: City
                        line1: String name
                        line2: null
                        recipient: null
                        state: CA
                        zipcode: '12332'
                      dob: '1998-02-11'
                      email: null
                      first_name: Max
                      last_name: Smith
                      member_id: null
                      phone: null
                      sex: null
                      ssn_last_four: null
                      type: child
                    primary_member:
                      address:
                        city: City
                        line1: String name
                        line2: null
                        recipient: null
                        state: CA
                        zipcode: '12332'
                      dob: '1988-10-11'
                      email: null
                      first_name: John
                      insurer_code: insurer:demo:vision
                      last_name: Smith
                      member_id: A123455
                      phone: '0987654321'
                      sex: null
                      ssn_last_four: '1242'
                    services:
                      - codes:
                          - S0504
                        cost: '12.2200'
                        date: '2022-02-11'
                        quantity: 2
                        diagnosis_codes:
                          - H52.10
                      - codes:
                          - V2781
                        cost: '44.2100'
                        date: '2022-02-11'
                        quantity: 1
                        diagnosis_codes: []
                    status: ready
                    paid_amount: '68.6500'
                  summary: Claim created successfully
        '400':
          description: Claim validation failed
          content:
            application/json:
              schema:
                type: object
                required:
                  - errors
                properties:
                  errors:
                    type: object
              examples:
                Unknown insurer:
                  value:
                    errors:
                      primary_member:
                        insurer_code:
                          $:
                            - Unknown code
                  summary: Unknown insurer
                Unknown service type:
                  value:
                    errors:
                      services:
                        '0':
                          codes:
                            $:
                              - Unknown code
                  summary: Unknown service type
                Missing primary member details:
                  value:
                    errors:
                      primary_member:
                        $:
                          - Either member ID or SSN last four are required
                          - Member ID or SSN last four are required
                        dob:
                          $:
                            - This field cannot be null.
                        first_name:
                          $:
                            - This field cannot be null.
                        insurer_code:
                          $:
                            - This field cannot be null.
                        insurer_id:
                          $:
                            - This field cannot be null.
                        last_name:
                          $:
                            - This field cannot be null.
                  summary: Missing primary member details
components:
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Your API token prefaced with an "Api" prefix. Example value: "Api
        B3F4242424E3FDB4242424242A9C7642"

````