Create an order

Creates an order at a location linked to the API token and returns it. When order matching finds an equivalent existing order, that order is returned instead with status 200 and a matched block. The participant’s identifiers are included only for tokens that also carry order.participant.read. Returns 400 at /location or /package for a reference that does not exist or is outside the token’s access, without distinguishing the two. A package name with no exact match is matched ignoring case; returns 409 when that matches more than one package and nothing else fails. Requires the order.create scope.

POST /api/v2/orders

Create an order

cURL

curl --request POST \
  --url https://api.stage.origin.one/api/v2/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "deliveryMethods": [
    {
      "to": "[e-mail]",
      "type": "email",
      "cc": [
        "[e-mail]"
      ]
    }
  ],
  "location": {
    "id": "456",
    "name": "Acme Downtown"
  },
  "package": {
    "id": "789",
    "name": "5 Panel Urine"
  },
  "participant": {
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1980-11-11",
    "email": "[e-mail]",
    "identifiers": [
      {
        "type": "ssn",
        "value": "123-12-1234"
      }
    ],
    "middleName": "Q",
    "phone": "[phone]"
  },
  "requester": {
    "email": "[e-mail]",
    "firstName": "Jane",
    "lastName": "Doe",
    "middleName": "R",
    "phone": "[phone]"
  },
  "settings": {
    "schedulingOption": "order",
    "billingCode": "PO-2026-001",
    "clinicSelectionMode": "closestToParticipant",
    "expiresIn": 30,
    "expiresInUnit": "days",
    "observedCollection": false
  },
  "testReason": "preEmployment"
}
'

200

{
  "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "object": "order",
  "code": "CPmJ6QbYMo",
  "agency": {
    "code": "FAA",
    "id": "3",
    "object": "agency",
    "url": "/api/v2/agencies/3"
  },
  "clinic": {
    "address": {
      "city": "Seattle",
      "country": "US",
      "line1": "123 Main St",
      "line2": "Suite 400",
      "object": "address",
      "postalCode": "98101",
      "state": "WA"
    },
    "id": "42",
    "name": "Austin Downtown Clinic",
    "object": "clinic",
    "phone": "[phone]",
    "url": "/api/v2/clinics/42"
  },
  "company": {
    "id": "123",
    "name": "Acme Inc",
    "object": "company",
    "url": "/api/v2/companies/123"
  },
  "createdAt": "2026-09-24T09:00:00.000Z",
  "expiresAt": "2026-09-24T15:15:00.000Z",
  "isFinal": false,
  "jobCategory": {
    "id": "3987402f-e963-45a9-8799-b9ea6621adae",
    "name": "Flight Crewmember",
    "object": "jobCategory",
    "url": "/api/v2/agencies/3/jobCategories/3987402f-e963-45a9-8799-b9ea6621adae"
  },
  "location": {
    "id": "456",
    "name": "Acme Downtown",
    "object": "location",
    "url": "/api/v2/locations/456"
  },
  "otherTestReason": "courtOrdered",
  "packages": [
    {
      "id": "789",
      "name": "DOT Pre-Employment Drug Test",
      "object": "package",
      "url": "/api/v2/packages/789"
    }
  ],
  "participant": {
    "address": {
      "city": "Seattle",
      "country": "US",
      "line1": "123 Main St",
      "line2": "Suite 400",
      "object": "address",
      "postalCode": "98101",
      "state": "WA"
    },
    "birthDate": "1980-11-11",
    "email": "[e-mail]",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Q",
    "phone": "[phone]",
    "identifiers": [
      {
        "issuingCountry": "US",
        "issuingState": "WA",
        "object": "participantIdentifier",
        "type": "driverLicense",
        "value": "D1234567"
      }
    ]
  },
  "services": [
    {
      "attributes": {
        "category": "standardPanels",
        "type": "urine"
      },
      "courierServiceName": "FedEx",
      "id": "<string>",
      "isDot": false,
      "isFinal": false,
      "lab": {
        "id": "64cba816-3c52-4a63-9d0e-0f2b5d1a7e11",
        "name": "CRL",
        "object": "vendor",
        "type": "lab"
      },
      "name": "5 Panel Urine",
      "object": "orderService",
      "screenHistory": [
        {
          "object": "orderServiceScreenHistory",
          "occurredAt": "2026-09-24T15:15:00.000Z",
          "type": "specimenCollected"
        }
      ],
      "specimenId": "SP-1",
      "status": "pending_collectionCompleted",
      "statusHistory": [
        {
          "groupType": "specimenCollected",
          "object": "orderServiceStatusHistory",
          "occurredAt": "2026-09-24T15:15:00.000Z",
          "status": "pending_collectionCompleted"
        }
      ],
      "statusUpdatedAt": "2026-09-24T15:15:00.000Z",
      "trackingNumber": "1Z999AA10123456784"
    }
  ],
  "status": "pending",
  "statusUpdatedAt": "2026-09-24T15:15:00.000Z",
  "testReason": "preEmployment",
  "updatedAt": "2026-09-24T15:20:00.000Z",
  "url": "/api/v2/orders/a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "matched": {
    "originalSource": "app",
    "score": 100
  }
}

Authorizations

Authorization · string · header · required

Origin One API token. Pass it in the Authorization header: Authorization: Bearer <token>.

Body

application/json

deliveryMethods · object[] · required

How the participant receives the order. One entry for now; more channels may be allowed later.

Required array length: 1 element

Option 1

Option 2

Show child attributes

location · object · required

Location the order is placed at; must be under a company linked to the API token.

Show child attributes

package · object · required

Package to order; must be available at the location or its company.

Show child attributes

participant · object · required

The person being tested.

Show child attributes

requester · object · required

Who is placing the order.

Show child attributes

settings · object · required

How the order is completed, and other order settings.

Show child attributes

testReason · enum<string> · required

Reason for the test.

Available options: blindSample, fitnessForDuty, followUp, jobTransfer, notIndicated, other, periodic, periodicMedical, postAccident, preEmployment, preSiteAccess, probation, promotion, random, reasonableSuspicion, returnToDuty, splitSpecimen, sweep, unauthorizedTest, unknown, injury

Example:

"preEmployment"

callback · object

Webhook that receives order.updated events for this order.

Show child attributes

agency · object

Regulatory agency the order is placed under, one of GET /agencies. Required when the package includes a DOT service.

Show child attributes

jobCategory · object

DOT job category of the participant, one of those agency publishes (see GET /agencies). Accepted only for an order with a DOT service under FAA, FRA or FTA, and required there when the package includes a DOT urine test.

Show child attributes

orderMatching · object

Order matching overrides; defaults to the location or company setting.

Show child attributes

otherTestReason · string

Detail for a testReason of other, up to 30 characters; not allowed with any other testReason. Free text when the package includes a DOT drug, alcohol or occupational health service; otherwise one of clinical, courtOrdered, criminalJustice, diversion, drugTreatment, employeeAnnual, forensic, personal, personalLegal, probableCause, proficiencyTesting, reversal, sendOut, specialForensic.

Required string length: 1 - 30

Example:

"courtOrdered"

Response

200

application/json

An equivalent existing resource was returned instead; see matched.

id · string · required

Unique identifier of the order.

Example:

"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"

object · enum<string> · required

Object type; always order.

Available options: order

Example:

"order"

code · string · required

Human-readable order code.

Example:

"CPmJ6QbYMo"

agency · object | null · required

Regulatory agency the order was placed under; null for a non-regulated order.

Show child attributes

clinic · object | null · required

Collection site; null until one is assigned.

Show child attributes

company · object | null · required

Company the order was placed for.

Show child attributes

createdAt · string<date-time> · required

When the order was created.

Example:

"2026-09-24T09:00:00.000Z"

expiresAt · string<date-time> | null · required

When the order expires; null when it does not.

Example:

"2026-09-24T15:15:00.000Z"

isFinal · boolean · required

Whether the order has reached an outcome. Cancelled, expired and no-show orders report false; check status for those.

Example:

false

jobCategory · object | null · required

DOT job category of the participant; null when the order has none.

Show child attributes

location · object | null · required

Location the order was placed at.

Show child attributes

otherTestReason · string | null · required

Detail for a testReason of other; null when none was given.

Example:

"courtOrdered"

packages · object[] · required

Packages the order was created from.

Show child attributes

participant · object · required

The person being tested.

Show child attributes

services · object[] · required

Services on the order, in creation order.

Show child attributes

status · enum<string> string · required

Current order status; new values may appear.

Available options: adulterated, cancelled, complete, expired, fail, fitForDuty, incomplete, integrationError, negative, lostInTransit, nonNegative, noShow, notFitForDuty, ordered, pass, pending, positive, released, scheduled, substituted, testCancelled, testNotPerformed, unobtainable

Example:

"pending"

statusUpdatedAt · string<date-time> · required

When the order status last changed; the creation time until the first change.

Example:

"2026-09-24T15:15:00.000Z"

testReason · enum<string> string · required

Reason for the test.

Available options: blindSample, fitnessForDuty, followUp, jobTransfer, notIndicated, other, periodic, periodicMedical, postAccident, preEmployment, preSiteAccess, probation, promotion, random, reasonableSuspicion, returnToDuty, splitSpecimen, sweep, unauthorizedTest, unknown, injury

Example:

"preEmployment"

updatedAt · string<date-time> · required

When the order was last updated.

Example:

"2026-09-24T15:20:00.000Z"

url · string<uri-reference> · required

Canonical path of this resource, relative to the API origin.

Example:

"/api/v2/orders/a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"

matched · object

Present on a create response when an equivalent existing order was returned instead.

Show child attributes