DOH Endpoints

Card-limit and medical-dispense-history integrations for the Department of Health.

All endpoints require an administrative authorization token in the Authorization: Bearer <token> header.

Server Bearer token

GET/v1/doh/connection/statusCheck the DOH API connection↑ Back to top

Reports whether the DOH API is reachable and whether the supplied authorization token is accepted. Use it to confirm connectivity and token validity before calling the card-limit or purchase-history operations. The request takes no parameters other than the authorization header.

Parameters

Name	In	Description
`Authorization` required	header Bearer token	Administrative authorization token. No query parameters are required.

Try it out

Request URL

—

Server response

—

Successful Response

The endpoint returns the standard { status, message, data } envelope. A status of ok means the DOH API accepted the token and answered the request.

{
  "status": "ok",
  "message": "",
  "data": {
    "organizationId": 3682,
    "organizationName": "POS Sandbox - Test 7A",
    "locationId": 5102,
    "address": "300 Test 7A Medical Retail Way",
    "city": "Las Cruces",
    "posApiConnectionStatus": "prepared"
  }
}

Response Fields

Field	Type	Description
`status`	string	`ok` when the connection check succeeded; `error` otherwise.
`message`	string	Empty on success; carries the failure reason when `status` is `error`.
`data`	string	Connection-status payload. Currently returned empty; treat the envelope `status` as the connection indicator.

Unauthorized

Returned with HTTP 401 when the bearer token is missing, malformed, expired, or fails verification.

{
  "status": "error",
  "message": "Unauthorized.",
  "data": null
}

Endpoint-Specific Errors

Error code	Typical message or condition	Meaning
`UNAUTHORIZED`	Unauthorized.	The authorization token was missing, expired, or rejected.
`CONNECTION_STATUS_FAILED`	Unable to process request. DOH API request timed out.	The DOH API did not answer within the request timeout.
`CONNECTION_STATUS_FAILED`	Unable to process request. DOH API authorization failed.	The DOH API rejected the service credentials configured for this environment.

GET/v1/doh/cardPurchaseHistoryGet purchase history↑ Back to top

Returns medical dispense history for the requested cannabis card.

Parameters

Name	In	Description
`medicalCannabisCardId` required	query string	Medical cannabis card identifier whose history will be returned.
`Authorization` required	header Bearer token	Administrative authorization token.

Try it out

Request URL

—

Server response

—

Successful Response

{
  "status": "ok",
  "message": "",
  "data": {
    "medicalCannabisCardId": "2Q78Q47AJF",
    "patientMedicalIdentifierId": "2Q78Q47AJF",
    "cardType": "Patient",
    "patient": {
      "firstName": "Dave",
      "lastName": "Isda",
      "expirationDate": "2028-04-27T00:00:00.000Z",
      "applicationId": "2Q78Q47AJF",
      "customerId": "165-patient",
      "dob": "01/01/2000"
    },
    "caregiver": null,
    "units": {
      "limit": 425,
      "usedLast90Days": 13,
      "remaining": 412,
      "milligramsPerUnit": 200
    },
    "dispenseTicketCount": 2,
    "dispenseItemCount": 2,
    "dispenseRows": [
      {
        "retailDispenseTicketId": 103,
        "orderNumber": "7253347155997584",
        "organizationId": 3637,
        "locationId": 5005,
        "createdDateTime": "2026-07-17 19:52:49",
        "dispenseDateTime": "2026-07-17 19:52:49",
        "dispenseType": "delivery",
        "deliveryFulfillmentType": "retailer",
        "ticketTotalItems": 1,
        "ticketMedicalUnitsTotal": 5,
        "retailDispenseTicketItemId": 125,
        "inventoryId": 509,
        "inventoryBarCode": "0803060206011198",
        "productTypeId": 36,
        "productType": "Cannabis Packaged",
        "productName": null,
        "strainName": "OG Ravens #1",
        "quantity": 1,
        "unit": "pkg",
        "medicalCalculationType": "gram_units",
        "itemMedicalUnits": 5,
        "delta9ThcMgDispensed": 100,
        "cannabisGramsPerPackage": 5,
        "delta9ThcMgPerPackage": 100,
        "plantCount": 0
      },
      {
        "retailDispenseTicketId": 108,
        "orderNumber": "4651517319134044",
        "organizationId": 3663,
        "locationId": 5064,
        "createdDateTime": "2026-07-22 23:13:39",
        "dispenseDateTime": "2026-07-22 23:13:39",
        "dispenseType": "in-store",
        "deliveryFulfillmentType": null,
        "ticketTotalItems": 1,
        "ticketMedicalUnitsTotal": 8,
        "retailDispenseTicketItemId": 131,
        "inventoryId": 1549,
        "inventoryBarCode": "0719303830336053",
        "productTypeId": 36,
        "productType": "Cannabis Packaged",
        "productName": null,
        "strainName": "GG#1",
        "quantity": 1,
        "unit": "pkg",
        "medicalCalculationType": "gram_units",
        "itemMedicalUnits": 8,
        "delta9ThcMgDispensed": 80,
        "cannabisGramsPerPackage": 8,
        "delta9ThcMgPerPackage": 80,
        "plantCount": 0
      }
    ]
  }
}

Response Fields

Field	Type	Description
`medicalCannabisCardId`	string	Card ID submitted with the lookup request.
`cardType`	string	Indicates whether the submitted card belongs to a `Patient` or `Caregiver`.
`patient`	object	Patient information associated with the card.
`caregiver`	object or null	Caregiver information when the submitted card is a caregiver card. Otherwise null.
`units`	object	Current Medical-unit information for the patient.
`dispenseTicketCount`	number	Total number of dispense tickets associated with the patient.
`dispenseItemCount`	number	Total number of dispense items associated with the patient.
`dispenseRows`	object	List of dispense records associated with the patient.

Patient Fields

Field	Type	Description
`firstName`	string	Patient's first name.
`lastName`	string	Patient's last name.
`expirationDate`	date/time or null	Patient's card expiration date.
`applicationId`	string	Patient's application ID.
`customerId`	string	Customer identifier associated with the patient.
`dob`	string	Patient's date of birth.

Caregiver Fields

Field	Type	Description
`firstName`	string	Caregiver's first name.
`lastName`	string	Caregiver's last name.
`expirationDate`	date/time or null	Caregiver's card expiration date.
`applicationId`	string	Caregiver's application ID.
`customerId`	string	Customer identifier associated with the caregiver.
`dob`	string	Caregiver's date of birth.

The caregiver object is returned only when cardType is Caregiver.

Unit Fields

Field	Type	Description
`limit`	number	Maximum Medical units allowed during the applicable 90-day period.
`usedLast90Days`	number	Medical units recorded as used by the patient during the previous 90 days.
`remaining`	number	Medical units currently available to the patient.
`milligramsPerUnit`	number	Number of milligrams represented by one medical unit.

Dispense Row Fields

Field	Type	Description
`createdDateTime`	date/time	Date and time when the dispense ticket was created.
`dispenseDateTime`	date/time	Date and time when the item was dispensed.
`dispenseType`	string	Indicates how the dispense was completed, such as in-store or delivery.
`deliveryFulfillmentType`	string or null	Fulfillment type for a delivery dispense. Returns null when not applicable.
`ticketTotalItems`	number	Total number of items included in the dispense ticket.
`ticketMedicalUnitsTotal`	number	Total medical units associated with the dispense ticket.
`retailDispenseTicketItemId`	number	Unique identifier for the dispense ticket item.
`inventoryId`	number	Identifier of the inventory item dispensed.
`inventoryBarCode`	string	Barcode associated with the dispensed inventory item.
`productTypeId`	number	Identifier of the product type.
`productType`	string	Type or category of the dispensed product.
`productName`	string or null	Name of the dispensed product, when available.
`strainName`	string	Strain name of the dispensed cannabis product.
`quantity`	number	Quantity of the product dispensed.
`unit`	string	Unit of measurement for the quantity.
`medicalCalculationType`	string	Medical-unit calculation method used for the dispensed product.
`itemMedicalUnits`	number	Number of medical units associated with the dispense item.
`delta9ThcMgDispensed`	number	Amount of Delta-9 THC, in milligrams, dispensed for the item.
`cannabisGramsPerPackage`	number	Amount of cannabis, in grams, contained in the package.
`delta9ThcMgPerPackage`	number	Amount of Delta-9 THC, in milligrams, contained in the package.
`plantCount`	number	Number of plants associated with the dispensed item.

Endpoint-Specific Errors

Error code	Typical message or condition	Meaning
`INVALID_MEDICAL_CANNABIS_CARD_ID`	Medical Cannabis Card ID cannot exceed 100 characters.	The top-level dispense object was missing or malformed.
`MEDICAL_CARD_LOOKUP_FAILED`	Unable to process request. Medical Cannabis Card ID not found.	The logical sale identifier was already stored; reconcile through order lookup.
`MEDICAL_CARD_LOOKUP_FAILED`	Unable to process request. DOH API authorization failed.	A request-field or business-rule validation failed.
`MEDICAL_CARD_LOOKUP_FAILED`	Unable to process request. DOH API request timed out.	The location cannot perform the requested dispense.
`MEDICAL_CARD_LOOKUP_FAILED`	Unable to look up Medical Cannabis Card.	The proposed Medical order exceeds the authoritative current balance.

POST/v1/doh/recordPatientMedicalCannabisCardReplacementRecord a card replacement↑ Back to top

Records that a patient's medical cannabis card was replaced, linking the retired card identifier to its replacement so that dispense history and 90-day unit usage continue to follow the patient onto the new card.

Parameters

Name	In	Description
`oldPatientMedicalCannabisCardId` required	body string	Identifier of the card being replaced.
`newPatientMedicalCannabisCardId` required	body string	Identifier of the replacement card issued to the same patient.
`Authorization` required	header Bearer token	Administrative authorization token. The token must be issued for the DOH domain; tokens from other domains are rejected by the operation itself.
`Content-Type` required	header string	Must be `application/json`.

Request Body

{
  "oldPatientMedicalCannabisCardId": "4UX58G5R4G",
  "newPatientMedicalCannabisCardId": "47Y6UD25SE"
}

Try it out

Request URL

—

Request body

—

Server response

—

Successful Response

The replacement is forwarded to the authoritative service, and its payload is returned in the data object of the standard envelope.

{
  "status": "ok",
  "message": "",
  "data": {
    "patientMedicalCannabisCardReplacementId": 2,
    "oldPatientMedicalCannabisCardId": "KJH",
    "newPatientMedicalCannabisCardId": "KJHN",
    "createdDateTime": "2026-08-20 19:35:00"
  }
}

Response Fields

Field	Type	Description
`status`	string	Envelope status. `ok` when the request was processed without a transport or service error.
`message`	string	Empty on success; carries the failure reason when the envelope `status` is `error`.
`data`	object	Result reported by the authoritative service. Inspect its own `status` field to confirm the replacement was recorded.
`data.status`	string	`error` when the replacement was rejected; any other value indicates the record was accepted.
`data.message`	string	Explanation accompanying `data.status`.
`data.timestamp`	date-time	UTC time the result was produced.

Execute the request against your environment to confirm the exact fields the authoritative service currently returns inside data.

Card has already been replaced

{
  "status": "ok",
  "message": "",
  "data": {
    "status": "error",
    "errorCode": "PATIENT_MEDICAL_CARD_ALREADY_REPLACED",
    "message": "The old patient Medical Cannabis Card ID has already been replaced.",
    "data": null
  }
}

Non-DOH Token

When the bearer token verifies but was not issued for the DOH domain, the request is not forwarded. The envelope still reports HTTP 200 and status: "ok"; the rejection is carried inside data.

{
  "status": "ok",
  "message": "",
  "data": {
    "status": "error",
    "message": "Invalid DOH authorization token.",
    "timestamp": "2026-08-17T15:04:11.482Z",
    "data": null
  }
}

Unauthorized

Returned with HTTP 401 when the bearer token is missing, malformed, expired, or fails verification.

{
  "status": "error",
  "message": "Unauthorized.",
  "data": null
}

Endpoint-Specific Errors

Error code	Typical message or condition	Meaning
`UNAUTHORIZED`	Unauthorized.	The authorization token was missing, expired, or failed verification.
`INVALID_DOH_AUTHORIZATION_TOKEN`	Invalid DOH authorization token.	The token verified but was not issued for the DOH domain, so the replacement was not recorded.
`CARD_REPLACEMENT_FAILED`	Unable to process request. DOH API request timed out.	The authoritative service did not answer within the 45-second request timeout.
`CARD_REPLACEMENT_FAILED`	Unable to record the medical cannabis card replacement.	The authoritative service rejected the submitted card identifiers.