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​