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

# Create requisition

> Create a new requisition.

<Warning>Access to requisitioning is disabled by default. To enable it, talk to us and we'll get you set up</Warning>

After creating a new requisition, we will immediately respond with an approved or denied status code.

<ResponseExample>
  ```json Response theme={null}
  {
    "requisition_id": "f0e5a607-5b52-4d7c-a3f2-c40772d41482",
    "barcode": "19742938328",
    "account_number": "1234567890",
    "panels": ["PANEL-123"],
    "state_collected": "OH",
    "patient": {
      "first_name": "Alice",
      "last_name": "Smith",
      "email": "alice123@gmail.com",
      "phone": "1234567890",
      "sex": "F",
      "date_of_birth": "2023-02-01",
      "address": {
        "street1": "123 Main St",
        "street2": "Apt 1",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "zip": "94105"
      }
    },
    "tracking": {
      "tracking_number": "9400123456789999876500",
      "carrier": "usps"
    },
    "status": "approved",
    "events": [
      {
        "event": "created",
        "date": "2020-01-01T00:00:00Z"
      },
      {
        "event": "approved",
        "date": "2020-01-01T00:00:00Z"
      }
    ],
    "reports": [],
    "metadata": null
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /api/v2/requisitions/
openapi: 3.0.3
info:
  title: Spot API v2
  version: 2.0.0
  description: API Docs for Spot API
servers:
  - url: https://app.spotdx.com
    description: Production
security: []
paths:
  /api/v2/requisitions/:
    post:
      description: Create a new requisition.
      operationId: api_v2_create_requisition
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRequisition'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Requisition'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: ''
      security:
        - tokenAuth: []
components:
  schemas:
    CreateRequisition:
      type: object
      properties:
        barcode:
          type: string
          description: >-
            The barcode of the sample mailed to the lab. We use this to identify
            the sample from the lab report.
          example: '19742938328'
        panels:
          type: array
          description: >-
            The panel codes of the test being performed on the sample. We'll
            create these with you during onboarding.
          example:
            - PANEL-123
          items:
            type: string
        account_number:
          type: string
          description: The account number submitted to the lab.
          example: '1234567890'
        lab:
          type: string
          description: The name of the lab that will process the sample.
          example: CRL
        state_collected:
          type: string
          description: The two letter code of the state where the sample was collected.
          example: OH
        patient:
          type: object
          properties:
            first_name:
              type: string
              description: The first name of the patient.
              example: Alice
            last_name:
              type: string
              description: The last name of the patient to be created.
              example: Smith
            email:
              type: string
              format: email
              description: The email of the patient to be created.
              example: alice123@gmail.com
            phone:
              type: string
              description: Optional phone number of the patient.
              example: '1234567890'
            sex:
              type: string
              description: The biological sex of the patient to be created.
              enum:
                - M
                - F
              example: F
            date_of_birth:
              type: string
              format: date
              description: The date of birth of the patient to be created.
            address:
              $ref: '#/components/schemas/Address'
        tracking:
          type: object
          properties:
            tracking_number:
              type: string
              nullable: true
            carrier:
              type: string
              enum:
                - fedex
                - ups
                - usps
              nullable: true
          example:
            tracking_number: '9400123456789999876500'
            carrier: usps
        attributes:
          type: object
          nullable: true
          description: >-
            An optional set of values that can be passed through to specific
            labs.
          properties:
            crl_slip_id:
              type: string
              nullable: true
              description: >-
                The slip ID to be passed through with the requisition if placing
                a requisition at CRL. Must be alphanumeric and maximum 10
                characters.
              maxLength: 10
              example: '1234567890'
          example:
            crl_slip_id: '1234567890'
        metadata:
          type: object
          nullable: true
          description: >-
            An optional dictionary of key-value pairs stored with the
            requisition.
          example:
            some_key: some_value
      required:
        - barcode
        - panels
        - account_number
        - lab
        - state_collected
        - patient
    Requisition:
      type: object
      properties:
        requisition_id:
          type: string
          description: The ID of the requisition.
          example: f0e5a607-5b52-4d7c-a3f2-c40772d41482
        barcode:
          type: string
          description: >-
            The full barcode of the sample mailed to the lab. Must be globally
            unique.
          example: '19742938328'
        account_number:
          type: string
          description: The account number submitted to the lab.
          example: '1234567890'
        lab:
          type: string
          description: The name of the lab that will process the sample.
          example: CRL
        panels:
          type: array
          description: >-
            The panel codes of the test being performed on the sample. We'll
            create these with you during onboarding.
          example:
            - PANEL-123
          items:
            type: string
        state_collected:
          type: string
          description: The two letter code of the state where the sample was collected.
          example: OH
        patient:
          type: object
          properties:
            first_name:
              type: string
              description: The first name of the patient.
              example: Alice
            last_name:
              type: string
              description: The last name of the patient to be created.
              example: Smith
            email:
              type: string
              format: email
              description: The email of the patient to be created.
              example: alice123@gmail.com
            phone:
              type: string
              description: Optional phone number of the patient.
              example: '1234567890'
            sex:
              type: string
              description: The biological sex of the patient to be created.
              enum:
                - M
                - F
              example: F
            date_of_birth:
              type: string
              format: date
              description: The date of birth of the patient to be created.
            address:
              type: object
              properties:
                address:
                  $ref: '#/components/schemas/Address'
        tracking:
          type: object
          properties:
            tracking_number:
              type: string
              nullable: true
              example: '9400123456789999876500'
            carrier:
              type: string
              enum:
                - fedex
                - ups
                - usps
              example: usps
              nullable: true
        status:
          type: string
          enum:
            - created
            - approved
            - denied
            - delivered
            - received
            - extra_quality_checks
            - resulted
            - rejected
            - delivery_exception
          example: resulted
        events:
          type: array
          items:
            type: object
            properties:
              event:
                type: string
                enum:
                  - created
                  - approved
                  - denied
                  - delivered
                  - received
                  - extra_quality_checks
                  - resulted
                  - rejected
                  - delivery_exception
              date:
                type: string
                format: date-time
                example: '2020-01-01T00:00:00Z'
          example:
            - event: created
              date: '2020-01-01T00:00:00Z'
            - event: approved
              date: '2020-01-01T00:00:00Z'
            - event: delivered
              date: '2020-01-02T00:00:00Z'
            - event: received
              date: '2020-01-03T00:00:00Z'
            - event: extra_quality_checks
              date: '2020-01-04T00:00:00Z'
            - event: resulted
              date: '2020-01-05T00:00:00Z'
        reports:
          type: array
          items:
            $ref: '#/components/schemas/Report'
        attributes:
          type: object
          nullable: true
          description: >-
            An optional set of values that can be passed through to specific
            labs.
          properties:
            crl_slip_id:
              type: string
              nullable: true
              description: >-
                The slip ID to be passed through with the requisition if placing
                a requisition at CRL. Must be alphanumeric and maximum 10
                characters.
              maxLength: 10
              example: '1234567890'
            crl_tier3_account_number:
              type: string
              nullable: true
              description: >-
                The region ID to be passed through with the requisition if
                placing a requisition at CRL. Must be alphanumeric and exactly 8
                characters.
              maxLength: 8
              minLength: 8
              example: '12345678'
          example:
            crl_slip_id: '1234567890'
            crl_tier3_account_number: '12345678'
        metadata:
          type: object
          nullable: true
          description: >-
            An optional dictionary of key-value pairs stored with the
            requisition.
          example:
            some_key: some_value
        created:
          type: string
          format: date-time
          example: '2020-01-01T00:00:00Z'
        updated:
          type: string
          format: date-time
          example: '2020-01-01T00:00:00Z'
    BadRequest:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              example: 400
              enum:
                - 400
                - 401
                - 403
                - 404
                - 500
            type:
              type: string
              example: bad_request
              enum:
                - bad_request
                - not_found
                - unauthorized
                - forbidden
                - rate_limit_exceeded
                - internal_server_error
            detail:
              type: string
              example: The first_name field is required
      required:
        - error
    Address:
      type: object
      properties:
        street1:
          type: string
          description: Recipient's address.
          example: 123 Main St
        street2:
          description: Second line of recipient's address.
          type: string
          nullable: true
          example: Apt 1
        city:
          type: string
          description: Recipient's city of residence.
          example: San Francisco
        state:
          type: string
          description: Recipient's state of residence.
          example: CA
        country:
          type: string
          description: Recipient's country of residence.
          enum:
            - US
            - CA
          example: US
        zip:
          type: string
          description: Recipient's zip code.
          example: '94105'
      required:
        - street1
        - city
        - state
        - country
        - zip
    Report:
      nullable: true
      type: object
      properties:
        report_id:
          type: string
        results:
          description: ''
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/ResultQuantity'
              - $ref: '#/components/schemas/ResultReactivity'
              - $ref: '#/components/schemas/ResultGenotype'
          example:
            - result_type: quantity
              name: HDL Cholesterol
              time_collected: '2023-01-14T04:30:11.222Z'
              result: 123
              unit_of_measure: mg/dL
              range_minimum: 20
              range_maximum: 200
              comments: null
            - result_type: quantity
              name: Vitamin B12
              time_collected: '2023-01-14T04:30:11.222Z'
              result: <10
              unit_of_measure: pg/mL
              range_minimum: 20
              range_maximum: 200
              comments: null
            - result_type: reactivity
              name: Chlamydia
              time_collected: '2023-01-14T04:30:11.222Z'
              result: negative
              unit_of_measure: null
              range_minimum: null
              range_maximum: null
              comments: null
            - result_type: genotype
              name: rs1234567
              time_collected: '2023-01-14T04:30:11.222Z'
              result: TT
              unit_of_measure: null
              range_minimum: null
              range_maximum: null
              comments: null
        pdf:
          type: string
          format: url
          description: A URL to the PDF report.
          example: >-
            https://app.spotkits.com/results/f0e5a607-5b52-4d7c-a3f2-c40772d41482.pdf
          nullable: true
        txt:
          type: string
          format: url
          description: A URL to the TXT report.
          example: >-
            https://app.spotkits.com/results/f0e5a607-5b52-4d7c-a3f2-c40772d41482.txt
          nullable: true
        date_collected:
          type: string
          format: date-time
        date_received:
          type: string
          format: date-time
        date_resulted:
          type: string
          format: date-time
        is_amendment:
          type: boolean
          description: Whether this report is an amendment to a previous report.
          example: false
    ResultQuantity:
      type: object
      properties:
        result_type:
          type: string
          enum:
            - quantity
        name:
          type: string
          description: The biomarker that was analyzed.
        time_collected:
          type: string
          format: date-time
        result:
          description: ''
          oneOf:
            - type: string
            - type: number
        unit_of_measure:
          type: string
          nullable: true
        range_minimum:
          type: string
          minimum: 0
        range_maximum:
          type: number
          minimum: 0
        comments:
          type: string
          nullable: true
    ResultReactivity:
      type: object
      properties:
        result_type:
          type: string
          enum:
            - reactivity
        name:
          type: string
          description: The biomarker that was analyzed.
        time_collected:
          type: string
          format: date-time
        result:
          description: ''
          type: string
          enum:
            - positive
            - negative
        unit_of_measure:
          type: string
          nullable: true
        range_minimum:
          type: number
          nullable: true
        range_maximum:
          type: number
          nullable: true
        comments:
          type: string
          nullable: true
    ResultGenotype:
      type: object
      properties:
        result_type:
          type: string
          enum:
            - genotype
        name:
          type: string
          description: The biomarker that was analyzed.
        time_collected:
          type: string
          format: date-time
        result:
          description: ''
          type: string
          enum:
            - TT
            - GG
            - CG
            - AG
            - CT
            - CC
            - AA
            - AT
            - AC
            - TA
            - TG
            - TC
            - GA
            - GT
            - GC
            - CA
        unit_of_measure:
          type: string
          nullable: true
        range_minimum:
          type: number
          nullable: true
        range_maximum:
          type: number
          nullable: true
        comments:
          type: string
          nullable: true
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Token"

````