Skip to main content

Orders API Documentation

Overview​

The PLACE_ORDER action is part of the Cases API that allows external systems to place medication orders for specific cases. This endpoint enables third-party integrations to create orders with prescription items, prescriber information, and patient health details.

Endpoint​

POST /api/v1/cases/:caseId

Authentication​

  • Header: cv-api-key (required)
  • Type: String
  • Description: API key for organization authentication

Request Parameters​

Path Parameters​

ParameterTypeRequiredDescription
caseIdStringYesThe unique identifier of the case

Request Body​

The request body must be a JSON object with the following structure:

{
  "action": "PLACE_ORDER",
  "order": {
    "shippingAddress": {
      "addressLine1": "string",
      "addressLine2": "string (optional)",
      "city": "string",
      "state": "string",
      "country": "string",
      "postalCode": "string"
    },
    "patientHealthInfo": {
      "allergies": "string (optional)",
      "healthConditions": "string (optional)",
      "currentMedications": "string (optional)"
    },
    "prescriber": {
      "firstName": "string",
      "lastName": "string",
      "title": "string (optional)",
      "titleSuffix": "string (optional)",
      "npi": "string",
      "dea": "string (optional)",
      "email": "string",
      "phoneNumber": "string",
      "address": {
        "addressLine1": "string",
        "addressLine2": "string (optional)",
        "city": "string",
        "state": "string",
        "country": "string",
        "postalCode": "string"
      }
    },
    "diagnosis": "string",
    "pharmacyId": "string",
    "dateWritten": "string (optional)",
    "dateSigned": "string (optional)",
    "datePrescribed": "string (optional)",
    "prescriptionItems": [
      {
        "drugId": "string",
        "direction": "string (optional)",
        "quantity": "string",
        "refillCount": "number (optional)",
        "supplyDays": "number (optional)",
        "customFields": "object (optional)"
      }
    ]
  }
}

Field Specifications​

Required Fields​

Root Level​

  • action: Must be exactly "PLACE_ORDER"
  • order: Object containing order details

Order Object​

  • prescriber: Prescriber information (optional fields are mentioned in above JSON structure)
  • diagnosis: Medical diagnosis for the prescription
  • pharmacyId: Target pharmacy identifier
  • prescriptionItems: Array of prescription items (at least one required)

Prescriber Object​

  • firstName: Prescriber's first name
  • lastName: Prescriber's last name
  • npi: National Provider Identifier
  • email: Prescriber's email address
  • phoneNumber: Contact phone number
  • address: Address object containing addressLine1, addressLine2, city, state, country, postalCode

Prescription Items​

  • drugId: Unique identifier for the medication
  • quantity: Quantity to be prescribed

Optional Fields​

Shipping Address​

  • shippingAddress: If not provided, uses patient's address from case

Patient Health Information​

  • patientHealthInfo: Optional health details
    • allergies: Known allergies
    • healthConditions: Current health conditions
    • currentMedications: Current medications

Prescriber Details​

  • title: Professional title (e.g., "Dr.")
  • titleSuffix: Title suffix (e.g., "MD", "DO")
  • dea: Drug Enforcement Administration number

Dates​

  • dateWritten: Date prescription was written
  • dateSigned: Date prescription was signed
  • datePrescribed: Date prescription was prescribed

Prescription Items​

  • direction: Dosage instructions
  • refillCount: Number of refills allowed
  • supplyDays: Days of supply
  • customFields: Additional custom fields as key-value pairs

Validation Rules​

State Validation​

  • state must be a valid US state abbreviation (e.g., "CA", "NY", "TX")

Country Validation​

  • country must be exactly 2 characters
  • Will be automatically converted to uppercase

Postal Code Validation​

  • Must be exactly 5 digits
  • Only numeric characters allowed

Email Validation​

  • Must be a valid email format

Phone Number Validation​

  • Must be a valid phone number format

Response Format​

Success Response​

{
  "status": 200,
  "success": true,
  "message": "Order created successfully",
  "data": {
    "order": {
      "id": "<order_id>"
    }
  }
}

Error Response​

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "Error description"
}

Error Scenarios​

400 Bad Request​

  • Missing required fields
  • Invalid field formats
  • Invalid state codes
  • Invalid email format
  • Invalid postal code format
  • Missing API key

401 Unauthorized​

  • Invalid or missing API key
  • Organization not found

403 Forbidden​

  • Case does not belong to the organization
  • Permission denied

Example Request​

curl -X POST "https://api.example.com/api/cases/123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -H "cv-api-key: your-api-key-here" \
  -d '{
    "action": "PLACE_ORDER",
    "order": {
      "shippingAddress": {
        "addressLine1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "postalCode": "94105"
      },
      "patientHealthInfo": {
        "allergies": "Penicillin",
        "healthConditions": "Hypertension",
        "currentMedications": "Lisinopril 10mg daily"
      },
      "prescriber": {
        "firstName": "John",
        "lastName": "Smith",
        "title": "Dr.",
        "titleSuffix": "MD",
        "npi": "1234567890",
        "email": "john.smith@example.com",
        "phoneNumber": "+1234567890",
        "address": {
            "addressLine1": "456 Medical Center Dr",
            "city": "San Francisco",
            "state": "CA",
            "country": "US",
            "postalCode": "94102"
        }
      },
      "diagnosis": "Hypertension",
      "pharmacyId": "pharmacy-123",
      "dateWritten": "2024-01-15",
      "prescriptionItems": [
        {
          "drugId": "drug-456",
          "direction": "Take 1 tablet daily with food",
          "quantity": "30",
          "refillCount": 3,
          "supplyDays": 30
        }
      ]
    }
  }'

Example Response​

Success​

{
  "status": 200,
  "success": true,
  "message": "Order created successfully",
  "data": {
    "order": {
      "id": "<order_id>"
    }
  }
}

Error​

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "firstName is required"
}

Notes​

  1. Case Ownership: The case must belong to the organization associated with the provided API key.

  2. Order Processing: Orders are processed asynchronously and may take time to complete.

  3. Prescription Download: Upon successful order creation, prescription documents are automatically downloaded and stored.

  4. Address Handling: If no shipping address is provided, the system will use the patient's address from the case.

  5. Notifications: Case activity notifications are sent upon successful order creation via webhooks.