OpenAPI Specification
openapi: 3.1.0
info:
title: SpecCheck Authentication Orders API
version: v1
summary: Optical lab ordering API for eyewear prescriptions, lens catalogs, and orders.
description: SpecCheck is an optical lab ordering platform. Its REST API lets eyecare practices and partners look up the labs and lens catalogs available to a user, retrieve a lab's order settings, and create prescription (rx), frame, and multi-pair orders programmatically. Authentication uses a bearer token obtained from client credentials, plus a `User-Email` header identifying the acting SpecCheck Dashboard user. POST requests support an `Idempotency-Key` header for safe retries. This specification was reconstructed by API Evangelist from SpecCheck's public documentation at https://docs.speccheckrx.com and is not an official SpecCheck artifact.
contact:
name: SpecCheck
url: https://docs.speccheckrx.com/introduction
x-apis-source: https://docs.speccheckrx.com/llms.txt
x-generated-by: api-evangelist enrichment pipeline (from docs)
servers:
- url: https://api.speccheckrx.com
description: Production
- url: https://api-staging.speccheckrx.com
description: Staging (testing and development)
security:
- bearerAuth: []
tags:
- name: Orders
description: Create and list optical orders.
paths:
/v1/orders:
get:
operationId: listOrders
tags:
- Orders
summary: List Orders
description: Returns orders for a lab, sorted by creation date with the most recent orders first. Supports cursor pagination via `starting_after` / `ending_before` and a `created` date interval filter.
parameters:
- $ref: '#/components/parameters/UserEmail'
- $ref: '#/components/parameters/LabQuery'
- $ref: '#/components/parameters/AccountNumberQuery'
- name: created[gt]
in: query
description: Return orders created after this Unix timestamp (exclusive).
schema:
type: integer
- name: created[gte]
in: query
description: Return orders created at or after this Unix timestamp (inclusive).
schema:
type: integer
- name: created[lt]
in: query
description: Return orders created before this Unix timestamp (exclusive).
schema:
type: integer
- name: created[lte]
in: query
description: Return orders created at or before this Unix timestamp (inclusive).
schema:
type: integer
- name: ending_before
in: query
description: Cursor - an object ID to fetch the previous page.
schema:
type: string
- name: starting_after
in: query
description: Cursor - an object ID to fetch the next page.
schema:
type: string
- name: limit
in: query
description: Number of objects to return (1-100, default 10).
schema:
type: integer
minimum: 1
maximum: 100
default: 10
responses:
'200':
description: A paginated list of orders.
content:
application/json:
schema:
type: object
properties:
has_more:
type: boolean
description: Whether there are more orders beyond this page.
data:
type: array
items:
$ref: '#/components/schemas/Order'
example:
has_more: false
data:
- id: ord_1234
tray_number: '1234'
invoice_number: '1234'
lab_status: in_progress
created: 1710000000
updated: 1710003600
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/PermissionError'
post:
operationId: createOrder
tags:
- Orders
summary: Create Order
description: Creates an order for a user, either saved as a draft or submitted to the lab. Supports rx, frame, redo, and multi-pair submissions. Send an `Idempotency-Key` header to safely retry.
parameters:
- $ref: '#/components/parameters/UserEmail'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrderRequest'
responses:
'200':
description: The created order.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/InvalidRequest'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/PermissionError'
'500':
$ref: '#/components/responses/ApiError'
components:
schemas:
CreateOrderRequest:
type: object
required:
- mode
- submission_type
- order_type
- lab
- account_number
- patient
- frame
properties:
mode:
type: string
enum:
- draft
- submit
description: Save as draft or submit to the lab.
submission_type:
type: string
enum:
- new
- redo
- multi_pair
order_type:
type: string
description: One of order_types from Retrieve Order Settings; rx is always available.
lab:
type: string
description: The ID of the lab.
account_number:
type: string
patient:
$ref: '#/components/schemas/Patient'
mounting_option:
type: string
description: One of mounting_options. Required when order_type is rx.
lens:
$ref: '#/components/schemas/Lens'
frame:
$ref: '#/components/schemas/Frame'
rx:
$ref: '#/components/schemas/Rx'
services:
type: array
items:
type: string
description: Lab services from Retrieve Order Settings.
special_instructions:
type: string
maxLength: 1000
redo_data:
$ref: '#/components/schemas/RedoData'
multi_pair_data:
type: object
description: Details for a multi-pair order. Required when submission_type is multi_pair.
RedoData:
type: object
required:
- type
- reason
- reference
properties:
type:
type: string
description: One of redo_types from Retrieve Order Settings.
reason:
type: string
maxLength: 250
reference:
type: string
description: Identifier for the order being redone.
EyeRx:
type: object
description: Prescription for one eye.
properties:
sphere:
type: number
minimum: -30
maximum: 30
pd:
type: number
minimum: 20
maximum: 50
description: Monocular distance IPD in mm.
near_pd:
type: number
minimum: 20
maximum: 50
description: Monocular near IPD in mm.
cylinder:
type: number
minimum: -20
maximum: 20
description: Required when axis is provided.
axis:
type: integer
minimum: 1
maximum: 180
description: Required when cylinder is provided.
add:
type: number
minimum: 0.5
maximum: 5
description: Required when seg_height is provided.
seg_height:
type: number
minimum: 0.5
maximum: 50
description: Required when add is provided.
oc_height:
type: number
minimum: 0.5
maximum: 50
horizontal_prism:
$ref: '#/components/schemas/Prism'
vertical_prism:
$ref: '#/components/schemas/Prism'
Order:
type: object
properties:
id:
type: string
description: The unique identifier for the order.
tray_number:
type: string
invoice_number:
type: string
lab_status:
type: string
description: Current status of the order at the lab.
created:
type: integer
description: Creation time
seconds since Unix epoch.: null
updated:
type: integer
description: Last update time
seconds since Unix epoch.: null
Prism:
type: object
required:
- power
- direction
properties:
power:
type: number
minimum: 0.01
maximum: 50
description: Prism power in prism diopters.
direction:
type: string
description: in/out for horizontal, up/down for vertical.
Patient:
type: object
required:
- first_name
- last_name
properties:
first_name:
type: string
maxLength: 50
last_name:
type: string
maxLength: 50
email:
type: string
format: email
phone_number:
type: string
maxLength: 20
Rx:
type: object
description: Prescription details. At least one of left_eye or right_eye must be provided.
properties:
left_eye:
$ref: '#/components/schemas/EyeRx'
right_eye:
$ref: '#/components/schemas/EyeRx'
Frame:
type: object
required:
- handling
- manufacturer
- model
- material
- color
- eye_size
- bridge
properties:
handling:
type: string
description: Must be one of frame_handling_options from Retrieve Order Settings.
manufacturer:
type: string
maxLength: 50
model:
type: string
maxLength: 50
material:
type: string
description: Must be one of frame_materials from Retrieve Order Settings.
color:
type: string
maxLength: 50
eye_size:
type: integer
minimum: 10
maximum: 100
description: Eye size in mm.
bridge:
type: integer
minimum: 10
maximum: 100
description: Bridge size in mm.
temple:
type: integer
minimum: 100
maximum: 200
description: Temple length in mm.
a:
type: number
minimum: 10
maximum: 100
b:
type: number
minimum: 10
maximum: 100
lens_ed:
type: number
minimum: 10
maximum: 100
description: Lens effective diameter in mm.
vertex:
type: number
minimum: 1
maximum: 30
pantoscopic_tilt:
type: number
minimum: -20
maximum: 20
wrap:
type: number
minimum: 0
maximum: 40
sku:
type: string
maxLength: 50
Lens:
type: object
required:
- style
- material
- color
properties:
style:
type: string
description: Lens style id from List Lens Styles.
material:
type: string
description: Lens material id from List Lens Materials.
color:
type: string
description: Lens color id from List Lens Addons colors.
coats:
type: array
items:
type: string
description: Coat ids from List Lens Addons.
tint:
type: string
description: One of tints from List Lens Addons.
tint_instruction:
type: string
maxLength: 250
description: Required when tint is provided.
Error:
type: object
properties:
error:
type: object
required:
- type
- message
properties:
type:
type: string
enum:
- invalid_request_error
- authentication_error
- permission_error
- api_error
message:
type: string
code:
type: string
description: Stable machine-readable string
when applicable.: null
param:
type: string
description: Related input field or header
when applicable.: null
responses:
PermissionError:
description: Authenticated but not allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: permission_error
message: You do not have permission to perform this action.
InvalidRequest:
description: Missing or invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: invalid_request_error
message: Example message from the API.
code: invalid_request
param: User-Email
ApiError:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: api_error
message: Something went wrong.
AuthenticationError:
description: Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: authentication_error
message: Authentication failed.
parameters:
LabQuery:
name: lab
in: query
required: true
description: The ID of the lab for this request.
schema:
type: string
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: Unique key (up to 255 chars; a v4 UUID works well) to safely retry a POST without duplicating the operation. Do not use sensitive data as the key.
schema:
type: string
maxLength: 255
UserEmail:
name: User-Email
in: header
required: true
description: Email address of the acting user. Must exactly match the email used to log in to the SpecCheck Dashboard.
schema:
type: string
format: email
AccountNumberQuery:
name: account_number
in: query
required: true
description: The lab account number for this request.
schema:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token obtained from POST /v1/oauth/token using client credentials. Tokens expire after 24 hours.