Skip to main content

Create Case with Products

POST/api/v1/cases

Creates a new case with user details, payment, and products in a single request. Supports forced case creation, intake forms with PHI, and test mode.

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

Parameters​

Headers
cv-api-keystringrequired
Your unique API key for authentication.
Content-Typestringrequired
Must be application/json.
Example: application/json
Request Body
statusstringoptional
Initial case status. Accepts OPEN or ABANDONED (case-insensitive). Default is OPEN.
Values:OPENABANDONED
isTestbooleanoptional
Enables test mode. Default is false.
forceCreatebooleanoptional
Force new case creation even if an open case exists. Default is false.
userobjectrequired
User details for the case
Show 8 child properties
firstNamestringrequired
Patient first name
lastNamestringrequired
Patient last name
emailstringrequired
Patient email address. Must be unique.
genderstringoptional
Patient gender
Values:MALEFEMALEOTHER
phoneNumberstringrequired
Patient phone number in E.164 format
Example: +1987654321
dobstringrequired
Date of birth in YYYY-MM-DD format
Example: 1990-05-15
languagePreferencesarrayoptional
ISO language codes for preferred languages
Example: ["en", "es", "fr"]
shippingAddressobjectoptional
Shipping address for the patient
Show 6 child properties
addressLine1stringoptional
Street address line 1
addressLine2stringoptional
Street address line 2 (optional)
citystringoptional
City name
statestringoptional
State abbreviation
countrystringoptional
Country code (e.g. US)
postalCodestringoptional
Postal/ZIP code
paymentobjectoptional
Total payment information for the case
Show 6 child properties
amountnumberrequired
Total payment amount
currencystringrequired
ISO 4217 currency code
Example: USD
descriptionstringoptional
Payment description
statusstringoptional
Use UNPAID when no payment method is provided
promoCodestringoptional
Active promo code (matched by name or value). Pass the gross `amount`; the discount is validated and applied server-side. An invalid or inactive code returns a 400. Can also be set on a product's `payment` to discount a single product. Exception: for an Affirm hold (`providerReference.type` `PAYMENT_INTENT`), send the already-discounted amount your PaymentIntent was authorized for; the code is only attached and the amount is never reduced (see Affirm Holds).
Example: SAVE10
providerReferenceobjectrequired
Payment gateway reference
Show 2 child properties
typestringrequired
Payment reference type
Values:SETUP_INTENTPAYMENT_INTENTPAYMENT_TOKEN
idstringrequired
Gateway reference ID
Example: seti_1Sk8JiGkkQS2eXzhTHyVTDj9
productsarrayrequired
Products to attach to the case. Each case can include one or more products.
Show 3 child properties
idstring (UUID)required
Organization product ID
visitTypestringoptional
Visit type for this product
Values:ASYNC_TEXT_EMAILSYNC_IN_PERSONSYNC_PHONESYNC_VIDEO
formobjectoptional
Healthcare intake form
Show 3 child properties
titlestringoptional
Form title
descriptionstringoptional
Form description
questionsarrayoptional
Array of form questions. See the Question Object reference below.
Show 6 child properties
questionstringrequired
Question text
Example: What is your current weight?
typestringrequired
Question type
Values:TEXTBOOLEANSINGLESELECTMULTISELECTDATERANGE
answerstringrequired
User response
Example: 150 lbs
requiredbooleanoptional
Whether the question is mandatory
optionsarrayoptional
Selectable options for SINGLESELECT and MULTISELECT question types
phibooleanoptional
PHI indicator

Affirm Holds​

Affirm can only capture the full amount it authorized — it does not support partial captures. When providerReference is a PAYMENT_INTENT that is an Affirm hold already authorized (requires_capture), the case is still created, but the payment amount behaves differently:

  • amount is the amount your PaymentIntent was authorized for. If you send a different amount, the request still succeeds and the payment is recorded at the authorized amount, because that is the only amount that can be captured.
  • promoCode is attached, not subtracted. Send the already-discounted amount your PaymentIntent was built for. The code is attached to the case and the payment, and the discount it implies is recorded on the payment for reporting; the payment amount is never reduced. Sending the gross amount does not discount it.
  • The amount can't be lowered later. Editing an unpaid Affirm payment to a lower amount, including by changing its promo code, is rejected with an error explaining that Affirm doesn't support partial captures. To charge a different amount, cancel the payment and create a new one.

Other payment methods, including Klarna and Afterpay, are unaffected.

Abandoned Cart Behavior​

  • user.firstName and user.lastName are required for all requests, including when status is ABANDONED.
  • When status is ABANDONED, the case is created with ABANDONED status.
  • Products are still attached to the case.
  • Payment validation and payment processing are skipped.
  • Auto-assignment is skipped, so the case is not assigned to providers.
  • Case-created notifications are skipped.

Examples​

curl -X POST "https://api.care360-next.carevalidate.com/api/v1/cases" \
-H "cv-api-key: <redacted>" \
-H "Content-Type: application/json" \
-d '{
  "isTest": true,
  "forceCreate": false,
  "user": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "gender": "MALE",
    "phoneNumber": "+1987654321",
    "dob": "1990-05-15",
    "languagePreferences": ["en"],
    "shippingAddress": {
      "addressLine1": "2720 Providence Hills Drive",
      "addressLine2": "",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "postalCode": "28105"
    }
  },
  "payment": {
    "amount": 159,
    "currency": "USD",
    "description": "Monthly Plan",
    "promoCode": "SAVE10",
    "providerReference": {
      "type": "SETUP_INTENT",
      "id": "seti_1Sk8JiGkkQS2eXzhTHyVTDj9"
    }
  },
  "products": [
    {
      "id": "9fc0d0f5-f211-4bf9-b105-485b1f29eb39",
      "visitType": "ASYNC_TEXT_EMAIL",
      "form": {
        "title": "Healthcare Intake Form",
        "description": "Patient intake form for healthcare services",
        "questions": [
          {
            "question": "How much do you weigh?",
            "answer": "138 lbs",
            "phi": true,
            "type": "TEXT"
          },
          {
            "question": "What are your weight loss goals?",
            "answer": "Lose 1-20lbs for good",
            "type": "SINGLESELECT",
            "required": true,
            "options": [
              "Lose 1-20lbs for good",
              "Lose 21-50lbs for good",
              "Lose over 50 for good",
              "Maintain my healthy weight"
            ]
          }
        ]
      }
    }
  ]
}'

Abandoned Cart Request Example​

{
  "status": "ABANDONED",
  "user": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "abandoned@example.com"
  },
  "products": [
    {
      "id": "9fc0d0f5-f211-4bf9-b105-485b1f29eb39"
    }
  ]
}

Responses​

▶200SuccessCase created successfully with products attached.
{
  "success": true,
  "data": {
    "caseId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
▶400Bad RequestInvalid request body or parameters, e.g. an invalid or inactive payment.promoCode.
{
  "success": false,
  "error": "Promo code 'SAVE10' not found or inactive"
}
▶401UnauthorizedMissing or invalid authentication token.
{
  "success": false,
  "message": "Unauthorized"
}
▶409ConflictCase conflict (e.g., open case already exists and forceCreate is false).
{
  "success": false,
  "message": "Case conflict"
}
▶422Validation FailedRequest body failed validation rules.
{
  "success": false,
  "message": "Validation failed"
}
▶500Internal Server ErrorUnexpected server error.
{
  "success": false,
  "message": "Internal server error"
}

Try It Out​

API Version: v2.3