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

Creating a patient via this endpoint populates a patient record in the Anagram Web App and allows you to tie the eligibility request and result with that record. Only use this resource if you plan on interacting with the Anagram Web App.


## OpenAPI

````yaml POST /api/auth/v1/patients/
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/patients/:
    post:
      tags:
        - public-auth_Patient
      summary: Create a Patient
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - first_name
                - last_name
                - dob
              properties:
                first_name:
                  type: string
                middle_name:
                  type: string
                last_name:
                  type: string
                dob:
                  type: string
                  format: date
                sex:
                  type: string
                ssn_last_four:
                  type: string
                address:
                  type: object
                  required:
                    - line1
                    - city
                    - zipcode
                    - state
                  properties:
                    line1:
                      type: string
                    line2:
                      type: string
                    recipient:
                      type: string
                    city:
                      type: string
                    zipcode:
                      type: string
                    state:
                      type: string
                email:
                  type: string
                phone:
                  type: string
                account_number:
                  type: string
                force_similar:
                  type: boolean
                  description: Allow to save a new object which is similar to others
                location_code:
                  type: string
                  description: >-
                    Identifies the location that the patient will be linked to.
                    When this field is empty, the patient will be linked with
                    the default location. Example: LOC4242B
            examples:
              Example:
                value:
                  first_name: Michael
                  last_name: Enslin
                  dob: '1950-02-28'
                  ssn_last_four: '1234'
                  sex: male
                  email: mike@foo.bar
                  phone: '1234567890'
                  address:
                    line1: 61st Street, Dolphin Hotel
                    line2: Room 1408
                    city: New York
                    state: NY
                    zipcode: '10065'
                summary: Create success
              Example#1:
                value: {}
                summary: Bad request
      responses:
        '201':
          description: JSON object response
          content:
            application/json:
              schema:
                type: object
                required:
                  - created_at
                  - first_name
                  - last_name
                  - dob
                  - code
                  - location
                properties:
                  created_at:
                    type: string
                    format: date-time
                  first_name:
                    type: string
                  middle_name:
                    type: string
                    nullable: true
                  last_name:
                    type: string
                  dob:
                    type: string
                    format: date
                  sex:
                    type: string
                  ssn_last_four:
                    type: string
                  address:
                    type: object
                    required:
                      - line1
                      - city
                      - zipcode
                      - state
                    properties:
                      line1:
                        type: string
                      line2:
                        type: string
                      recipient:
                        type: string
                        nullable: true
                      city:
                        type: string
                      zipcode:
                        type: string
                      state:
                        type: string
                  email:
                    type: string
                  phone:
                    type: string
                  account_number:
                    type: string
                    nullable: true
                  code:
                    type: string
                    format: string
                  location:
                    type: object
                    required:
                      - status
                      - title
                      - code
                    properties:
                      status:
                        type: string
                      title:
                        type: string
                        description: Location title
                      code:
                        type: string
                        format: string
              examples:
                Patient created:
                  value:
                    created_at: '2025-03-18T13:51:16.926798+00:00'
                    first_name: michael
                    middle_name: null
                    last_name: enslin
                    dob: '1950-02-28'
                    sex: male
                    ssn_last_four: '1234'
                    address:
                      line1: 61st Street, Dolphin Hotel
                      line2: Room 1408
                      recipient: null
                      city: New York
                      zipcode: '10065'
                      state: NY
                    email: mike@foo.bar
                    phone: '1234567890'
                    account_number: null
                    code: PAT21T
                    location:
                      status: enabled
                      title: Main street branch
                      code: LOC57T
                  summary: Create success
        '400':
          description: Patient validation failed or similar patients were found
          content:
            application/json:
              schema:
                type: object
                required:
                  - errors
                properties:
                  errors:
                    type: object
                  has_similars:
                    type: boolean
                    description: Whether similar patients were found
                  has_more_similars:
                    type: boolean
                    description: Whether more similar patients exist beyond those returned
                  similars:
                    type: array
                    description: >-
                      Existing patients with the same first name, last name, and
                      date of birth. Returns up to 10 patients.
                    items:
                      type: object
                      required:
                        - created_at
                        - first_name
                        - last_name
                        - dob
                        - code
                        - location
                      properties:
                        created_at:
                          type: string
                          format: date-time
                        first_name:
                          type: string
                        middle_name:
                          type: string
                          nullable: true
                        last_name:
                          type: string
                        dob:
                          type: string
                          format: date
                        sex:
                          type: string
                          nullable: true
                        ssn_last_four:
                          type: string
                          nullable: true
                        address:
                          type: object
                          nullable: true
                        email:
                          type: string
                          nullable: true
                        phone:
                          type: string
                          nullable: true
                        account_number:
                          type: string
                          nullable: true
                        code:
                          type: string
                        location:
                          type: object
                          required:
                            - status
                            - title
                            - code
                          properties:
                            status:
                              type: string
                            title:
                              type: string
                            code:
                              type: string
              examples:
                Validation error:
                  value:
                    errors:
                      first_name:
                        $:
                          - This field cannot be null.
                      last_name:
                        $:
                          - This field cannot be null.
                      dob:
                        $:
                          - This field cannot be null.
                  summary: Bad request
                Similar patient found:
                  value:
                    errors:
                      $:
                        - Similar patient found
                    has_more_similars: false
                    has_similars: true
                    similars:
                      - created_at: '2025-03-18T13:51:16.926798+00:00'
                        first_name: Name
                        middle_name: null
                        last_name: Lname
                        dob: '1970-01-01'
                        sex: null
                        ssn_last_four: null
                        address: null
                        email: null
                        phone: null
                        account_number: null
                        code: PAT21T
                        location:
                          status: enabled
                          title: Main street branch
                          code: LOC57T
                  summary: Similar patient found
components:
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Your API token prefaced with an "Api" prefix. Example value: "Api
        B3F4242424E3FDB4242424242A9C7642"

````