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

# Create Order

> Creates an order for a user.

```http theme={null}
POST https://api.speccheckrx.com/v1/orders
```

### Authentication

This endpoint requires bearer token authentication.

### Headers

<ParamField header="Authorization" type="string" required="true">
  Your bearer token in the format `Bearer <token>`.
</ParamField>

<ParamField header="User-Email" type="string" required="true">
  The email address of the user creating the order.

  Must exactly match the email address used to log in to the SpecCheck Dashboard.
</ParamField>

### Body

<ParamField body="mode" type="string" required="true">
  Controls whether the order is saved as a draft or submitted to the lab.

  Possible enum values:

  * `draft` — Saves the order as a draft for review and finalization in the SpecCheck Dashboard.
  * `submit` — Submits the order to the lab for fulfillment.
</ParamField>

<ParamField body="submission_type" type="string" required="true">
  The type of submission for this order.

  Possible enum values:

  * `new` — A new order.
  * `redo` — A redo of a previous order.
  * `multi_pair` — An additional pair submitted as part of a multi-pair order.
</ParamField>

<ParamField body="order_type" type="string" required="true">
  The type of order. Must be one of the values in `order_types` returned by [Retrieve Order Settings](/api-reference/endpoint/retrieve_order_settings).

  Order type `rx` is always available; other order types vary by lab.
</ParamField>

<ParamField body="lab" type="string" required="true">
  The ID of the lab for this order.
</ParamField>

<ParamField body="account_number" type="string" required="true">
  The lab account number for this order.
</ParamField>

<ParamField body="patient" type="object" required="true">
  Patient information.
</ParamField>

<Expandable title="patient">
  <ParamField body="first_name" type="string" required="true">
    The patient’s first name.

    The maximum length is 50 characters.
  </ParamField>

  <ParamField body="last_name" type="string" required="true">
    The patient’s last name.

    The maximum length is 50 characters.
  </ParamField>

  <ParamField body="email" type="string">
    The patient’s email address.
  </ParamField>

  <ParamField body="phone_number" type="string">
    The patient’s phone number.

    The maximum length is 20 characters.
  </ParamField>
</Expandable>

<ParamField body="mounting_option" type="string">
  Mounting option for the order. Must be one of the values in `mounting_options` returned by [Retrieve Order Settings](/api-reference/endpoint/retrieve_order_settings). Required when `order_type` is `rx`.
</ParamField>

<ParamField body="lens" type="object">
  Lens configuration. Required when `order_type` is `rx` and `mode` is `submit`.
</ParamField>

<Expandable title="lens">
  <ParamField body="style" type="string" required="true">
    The ID of the lens style. Must be an `id` from the `data` array returned by [List Lens Styles](/api-reference/endpoint/list_lens_styles).
  </ParamField>

  <ParamField body="material" type="string" required="true">
    The ID of the lens material. Must be an `id` from the `data` array returned by [List Lens Materials](/api-reference/endpoint/list_lens_materials).
  </ParamField>

  <ParamField body="color" type="string" required="true">
    The ID of the lens color. Must be an `id` from the `colors` array returned by [List Lens Addons](/api-reference/endpoint/list_lens_addons).
  </ParamField>

  <ParamField body="coats" type="array of string">
    A list of coat IDs. Each value must be an `id` from the `coats` array returned by [List Lens Addons](/api-reference/endpoint/list_lens_addons).
  </ParamField>

  <ParamField body="tint" type="string">
    The lens tint for this order. Must be one of the values in `tints` returned by [List Lens Addons](/api-reference/endpoint/list_lens_addons).
  </ParamField>

  <ParamField body="tint_instruction" type="string">
    Instructions for the lens tint. Required when `tint` is provided.

    The maximum length is 250 characters.
  </ParamField>
</Expandable>

<ParamField body="frame" type="object" required="true">
  Frame information.
</ParamField>

<Expandable title="frame">
  <ParamField body="handling" type="string" required="true">
    The frame handling option. Must be one of the values in `frame_handling_options` returned by [Retrieve Order Settings](/api-reference/endpoint/retrieve_order_settings).
  </ParamField>

  <ParamField body="manufacturer" type="string" required="true">
    The frame manufacturer.

    The maximum length is 50 characters.
  </ParamField>

  <ParamField body="model" type="string" required="true">
    The frame model.

    The maximum length is 50 characters.
  </ParamField>

  <ParamField body="material" type="string" required="true">
    The frame material. Must be one of the values in `frame_materials` returned by [Retrieve Order Settings](/api-reference/endpoint/retrieve_order_settings).
  </ParamField>

  <ParamField body="color" type="string" required="true">
    The frame color.

    The maximum length is 50 characters.
  </ParamField>

  <ParamField body="eye_size" type="integer" required="true">
    Eye size, in millimeters.

    The value must be between 10 and 100.
  </ParamField>

  <ParamField body="bridge" type="integer" required="true">
    Bridge size, in millimeters.

    The value must be between 10 and 100.
  </ParamField>

  <ParamField body="temple" type="integer">
    Temple length, in millimeters.

    The value must be between 100 and 200.
  </ParamField>

  <ParamField body="a" type="number">
    A measurement, in millimeters.

    The value must be between 10 and 100.
  </ParamField>

  <ParamField body="b" type="number">
    B measurement, in millimeters.

    The value must be between 10 and 100.
  </ParamField>

  <ParamField body="lens_ed" type="number">
    Lens effective diameter (ED), in millimeters.

    The value must be between 10 and 100.
  </ParamField>

  <ParamField body="vertex" type="number">
    Vertex distance, in millimeters.

    The value must be between 1 and 30.
  </ParamField>

  <ParamField body="pantoscopic_tilt" type="number">
    Pantoscopic tilt, in degrees.

    The value must be between -20 and 20.
  </ParamField>

  <ParamField body="wrap" type="number">
    Wrap angle, in degrees.

    The value must be between 0 and 40.
  </ParamField>

  <ParamField body="sku" type="string">
    The frame SKU.

    The maximum length is 50 characters.
  </ParamField>
</Expandable>

<ParamField body="rx" type="object">
  Prescription details. Required when `order_type` is `rx`.
</ParamField>

<Expandable title="rx">
  <ParamField body="left_eye" type="object">
    Left-eye prescription. When `order_type` is `rx`, at least one of `left_eye` or `right_eye` must be provided.
  </ParamField>

  <ParamField body="right_eye" type="object">
    Right-eye prescription. When `order_type` is `rx`, at least one of `left_eye` or `right_eye` must be provided.
  </ParamField>

  <Expandable title="left_eye / right_eye">
    <ParamField body="sphere" type="number">
      Sphere power, in diopters.

      The value must be between -30 and 30.
    </ParamField>

    <ParamField body="pd" type="number">
      Interpupillary distance (IPD) for this eye, in millimeters. Must be provided as a monocular value (per eye), not a combined value.

      The value must be between 20 and 50.
    </ParamField>

    <ParamField body="near_pd" type="number">
      Near (reading) interpupillary distance (IPD) for this eye, in millimeters. Must be provided as a monocular value (per eye), not a combined value.

      The value must be between 20 and 50.
    </ParamField>

    <ParamField body="cylinder" type="number">
      Cylinder power, in diopters.

      The value must be between -20 and 20. Required when `axis` is provided.
    </ParamField>

    <ParamField body="axis" type="integer">
      Axis, in degrees.

      The value must be an integer from 1 to 180. Required when `cylinder` is provided.
    </ParamField>

    <ParamField body="add" type="number">
      Add power, in diopters.

      The value must be between 0.5 and 5. Required when `seg_height` is provided.
    </ParamField>

    <ParamField body="seg_height" type="number">
      Segment height, in millimeters.

      The value must be between 0.5 and 50. Required when `add` is provided.
    </ParamField>

    <ParamField body="oc_height" type="number">
      Optical center height, in millimeters.

      The value must be between 0.5 and 50.
    </ParamField>

    <ParamField body="horizontal_prism" type="object">
      Horizontal prism values.
    </ParamField>

    <Expandable title="horizontal_prism">
      <ParamField body="power" type="number" required="true">
        Prism power, in prism diopters.

        The value must be between 0.01 and 50.
      </ParamField>

      <ParamField body="direction" type="string" required="true">
        The prism direction. One of `in` or `out`.
      </ParamField>
    </Expandable>

    <ParamField body="vertical_prism" type="object">
      Vertical prism values.
    </ParamField>

    <Expandable title="vertical_prism">
      <ParamField body="power" type="number" required="true">
        Prism power, in prism diopters.

        The value must be between 0.01 and 50.
      </ParamField>

      <ParamField body="direction" type="string" required="true">
        The prism direction. One of `up` or `down`.
      </ParamField>
    </Expandable>
  </Expandable>
</Expandable>

<ParamField body="services" type="array of string">
  A list of lab services for this order. Each value must be one of the values in `services` returned by [Retrieve Order Settings](/api-reference/endpoint/retrieve_order_settings).
</ParamField>

<ParamField body="special_instructions" type="string">
  Free-text special instructions for the lab.

  The maximum length is 1,000 characters.
</ParamField>

<ParamField body="redo_data" type="object">
  Details for a redo order. Required when `submission_type` is `redo`.
</ParamField>

<Expandable title="redo_data">
  <ParamField body="type" type="string" required="true">
    The redo type. Must be one of the values in `redo_types` returned by [Retrieve Order Settings](/api-reference/endpoint/retrieve_order_settings).
  </ParamField>

  <ParamField body="reason" type="string" required="true">
    A description of why this order is being redone.

    The maximum length is 250 characters.
  </ParamField>

  <ParamField body="reference" type="string" required="true">
    The identifier for the order being redone, such as an invoice number, tray number, or Rx number.
  </ParamField>
</Expandable>

<ParamField body="multi_pair_data" type="object">
  Details for a multi-pair order. Required when `submission_type` is `multi_pair`.
</ParamField>

<Expandable title="multi_pair_data">
  <ParamField body="reference" type="string" required="true">
    The identifier for the related order, such as an invoice number, tray number, or Rx number.
  </ParamField>
</Expandable>

<ParamField body="shipping" type="object">
  Shipping name and address.
</ParamField>

<Expandable title="shipping">
  <ParamField body="name" type="string" required="true">
    Recipient name.

    The maximum length is 50 characters.
  </ParamField>

  <ParamField body="address" type="object" required="true">
    Shipping address.
  </ParamField>

  <Expandable title="address">
    <ParamField body="line1" type="string" required="true">
      Address line 1, such as the street, PO Box, or company name.
    </ParamField>

    <ParamField body="line2" type="string">
      Address line 2, such as the apartment, suite, unit, or building. Omit if unused.
    </ParamField>

    <ParamField body="city" type="string" required="true">
      City, district, suburb, town, or village.
    </ParamField>

    <ParamField body="state" type="string" required="true">
      State, county, province, or region (for the US, [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) subdivision code). Two letters; must be a US state or territory code the API allows.
    </ParamField>

    <ParamField body="postal_code" type="string" required="true">
      ZIP or postal code.
    </ParamField>

    <ParamField body="country" type="string">
      A two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). Only `US` is supported. If omitted, defaults to `US`.
    </ParamField>
  </Expandable>
</Expandable>

### Returns

Returns an object with the order’s unique identifier and an optional `url`.

<ResponseField name="id" type="string">
  The unique identifier for the order.
</ResponseField>

<ResponseField name="url" type="string">
  The URL to review and finalize the order in the SpecCheck Dashboard. Present when `mode` is `draft`.
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "id": "ord_1234",
    "url": "https://dashboard.speccheckrx.com/orders/ord_1234"
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash theme={null}
  curl -X POST "https://api.speccheckrx.com/v1/orders" \
    -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
    -H "User-Email: {{USER_EMAIL}}" \
    -d @order.json
  ```
</RequestExample>