Skip to main content

Place orders for a case

POST/api/v1/cases/:caseId

Places a medication order for a case. Includes prescription items, prescriber information, and optional patient health details.

cv-api-key
Productionhttps://api.care360-next.carevalidate.com/api/v1/cases/:caseId
Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/cases/:caseId

Path Parameters​

caseIdstringrequired
The unique identifier of the case.

Headers​

cv-api-keystringrequired
API key for organization authentication.
Content-Typestringrequired
Must be application/json.
Example: application/json

Request Body​

Body Parameters
actionstringrequired
The action to be performed.
Values:PLACE_ORDER
idempotencyKeystringoptional
Optional unique key to prevent duplicate order creation. Scoped per organization.
orderobjectrequired
Object containing order details.
Show 9 child properties
shippingAddressobjectoptional
Shipping address for the order. If not provided, uses the patient's address from the case.
Show 6 child properties
addressLine1stringrequired
Street address line 1.
addressLine2stringoptional
Street address line 2.
citystringrequired
City name.
statestringrequired
Valid US state abbreviation (e.g., CA, NY, TX).
countrystringrequired
Country code. Must be exactly 2 characters. Automatically converted to uppercase.
postalCodestringrequired
Must be exactly 5 digits, numeric only.
patientHealthInfoobjectoptional
Optional patient health details.
Show 3 child properties
allergiesstringoptional
Known allergies.
healthConditionsstringoptional
Current health conditions.
currentMedicationsstringoptional
Current medications.
prescriberobjectrequired
Prescriber information.
Show 9 child properties
firstNamestringrequired
Prescriber's first name.
lastNamestringrequired
Prescriber's last name.
titlestringoptional
Professional title (e.g., "Dr.").
titleSuffixstringoptional
Title suffix (e.g., "MD", "DO").
npistringrequired
National Provider Identifier.
deastringoptional
Drug Enforcement Administration number.
emailstringrequired
Prescriber's email address. Must be a valid email format.
phoneNumberstringrequired
Contact phone number. Must be a valid phone number format.
addressobjectrequired
Prescriber's address.
Show 6 child properties
addressLine1stringrequired
Street address line 1.
addressLine2stringoptional
Street address line 2.
citystringrequired
City name.
statestringrequired
Valid US state abbreviation.
countrystringrequired
Country code (2 characters).
postalCodestringrequired
Postal code (5 digits).
diagnosisstringrequired
Medical diagnosis for the prescription.
pharmacyIdstringrequired
Target pharmacy identifier.
dateWrittenstringoptional
Date prescription was written.
dateSignedstringoptional
Date prescription was signed.
datePrescribedstringoptional
Date prescription was prescribed.
prescriptionItemsarray of objectsrequired
Array of prescription items (at least one required).
Show 6 child properties
drugIdstringrequired
Unique identifier for the medication.
directionstringoptional
Dosage instructions.
quantitystringrequired
Quantity to be prescribed.
refillCountnumberoptional
Number of refills allowed.
supplyDaysnumberoptional
Days of supply.
customFieldsobjectoptional
Additional custom fields as key-value pairs.

Validation Rules​

  • State: Must be a valid US state abbreviation (e.g., "CA", "NY", "TX")
  • Country: Must be exactly 2 characters; automatically converted to uppercase
  • Postal Code: Must be exactly 5 digits, numeric only
  • Email: Must be a valid email format
  • Phone Number: Must be a valid phone number format

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.

Request Examples​

curl -X POST "https://api.care360-next.carevalidate.com/api/v1/cases/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "cv-api-key: YOUR_SECRET_KEY" \
-d '{
  "action": "PLACE_ORDER",
  "idempotencyKey": "unique-order-key-123",
  "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
      }
    ]
  }
}'

Responses​

▶200SuccessOrder created successfully.
{
  "status": 200,
  "success": true,
  "message": "Order created successfully",
  "data": {
    "order": {
      "id": "<order_id>"
    }
  }
}
▶400Bad RequestMissing required fields, invalid field formats, invalid state codes, invalid email format, invalid postal code format, or missing API key.
{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "firstName is required"
}
▶401UnauthorizedInvalid or missing API key, or organization not found.
{
  "status": 401,
  "success": false,
  "message": "Invalid request",
  "error": "Unauthorized"
}
▶403ForbiddenCase does not belong to the organization or permission denied.
{
  "status": 403,
  "success": false,
  "message": "Invalid request",
  "error": "Permission denied"
}
▶409ConflictA record with the provided idempotencyKey already exists for this organization.
{
  "status": 409,
  "success": false,
  "code": "IDEMPOTENCY_ERROR",
  "description": "A record with the provided idempotencyKey already exists for this organization."
}

Try It Out​