Fulfillment Authorization

POST/api/v1/fulfillment-authorization

Authorizes a fill in reply to a FULFILLMENT_AUTHORIZATION_REQUESTED webhook. Once authorized, CareValidate places the order automatically. Optionally authorizes a period of treatment so later fills in that period do not need a new request.

cv-api-key

Productionhttps://api.care360-next.carevalidate.com/api/v1/fulfillment-authorization

Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/fulfillment-authorization

Overview

Use this endpoint to answer a FULFILLMENT_AUTHORIZATION_REQUESTED webhook. That webhook tells you a fill needs your authorization. Reply here with the requestId from the webhook to authorize it. CareValidate then places the order automatically.

Availability

• This flow applies only to organizations that handle their own patient payments. CareValidate sends FULFILLMENT_AUTHORIZATION_REQUESTED webhooks only to organizations set up this way. If your organization doesn't handle its own payments, you won't receive the webhook and don't need this endpoint.
• To be set up this way, your organization must have an enabled webhook subscription to FULFILLMENT_AUTHORIZATION_REQUESTED. The configuration change is rejected without one.
• Access is limited to organizations CareValidate has enabled for this flow. Contact CareValidate to have your organization enabled.

What a reply does

A reply authorizes the fill named in the request, and the order is placed automatically.

validFor is optional. It authorizes a number of intervals of treatment (for example, 3 months).

important

Always use "month" as the interval. Prescription fills are measured in months, so other values (day, week, year) are accepted by validation but should not be used currently.

• With validFor: the fill is authorized, and the following fills within that period are authorized too, so you don't receive a new webhook for each one. A new webhook is sent only once the period has run out or no longer covers the fill.
• Without validFor: only the fill in this request is authorized. A new request is sent the next time a fill needs authorization.
• Sending validFor on a later reply starts a new period from that moment and replaces any earlier one.

Request Body

Body Parameters

requestIdstringrequired

UUID. The fulfillment authorization request ID sent in the FULFILLMENT_AUTHORIZATION_REQUESTED webhook payload (its fulfillmentAuthorizationRequestId field).

Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

validForobjectoptional

How long the authorization lasts, as a number of intervals (for example, 3 months). Omit to authorize only the fill in this request. Must contain only the properties listed below.

Show 2 child properties

intervalstringrequired

The unit of time. Use "month" only: prescription fills are measured in months, so the other values should not be used currently.

Values:dayweekmonthyear

intervalCountnumberrequired

Positive integer number of intervals the authorization lasts. E.g. interval: "month", intervalCount: 3 authorizes 3 months of treatment.

Example: 3

Request Examples

cURL

curl -X POST "https://api.care360-next.carevalidate.com/api/v1/fulfillment-authorization" \
-H "Content-Type: application/json" \
-H "cv-api-key: YOUR_SECRET_KEY_HERE" \
-d '{
  "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "validFor": {
    "interval": "month",
    "intervalCount": 3
  }
}'

JavaScript

const response = await fetch(
"https://api.care360-next.carevalidate.com/api/v1/fulfillment-authorization",
{
  method: "POST",
  headers: {
    "cv-api-key": "YOUR_SECRET_KEY_HERE",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    requestId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    validFor: {
      interval: "month",
      intervalCount: 3,
    },
  }),
}
);

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
  "https://api.care360-next.carevalidate.com/api/v1/fulfillment-authorization",
  headers={
      "cv-api-key": "YOUR_SECRET_KEY_HERE",
      "Content-Type": "application/json",
  },
  json={
      "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "validFor": {
          "interval": "month",
          "intervalCount": 3,
      },
  },
)

data = response.json()
print(data)

Try It Out

Try itAPI Playground

▶

Responses

▶200SuccessAuthorization received. Replying again to a request that has already been processed also returns 200 with no further effect, so retries are safe.

{
  "status": 200,
  "success": true,
  "message": "Fulfillment authorization received"
}

▶400Validation ErrorReturned when requestId is missing or not a valid UUID, or validFor doesn't match the required shape.

{
  "status": 400,
  "success": false,
  "message": "Invalid request",
  "error": "<validation message>",
  "code": "VALIDATION_ERROR"
}

▶400Not FoundReturned when requestId doesn't correspond to any known fulfillment authorization request.

{
  "status": 400,
  "success": false,
  "message": "Invalid case data",
  "error": "No fulfillment authorization request found for id: <requestId>",
  "code": "CASE_ERROR"
}

▶400Request No Longer NeededReturned when the authorization is no longer needed because CareValidate's support team already placed the order manually for this fill before your reply arrived. Nothing is applied, and you don't need to retry.

{
  "status": 400,
  "success": false,
  "message": "Invalid case data",
  "error": "Fulfillment authorization voided; order already placed",
  "code": "CASE_ERROR"
}

▶401Permission DeniedReturned when the request identified by requestId belongs to a different organization than the one authenticated via cv-api-key.

{
  "status": 401,
  "success": false,
  "message": "Permission Denied",
  "error": "Permission denied",
  "code": "PERMISSION_DENIED_ERROR"
}