Payloads and Error Semantics

This page describes the envelopes and errors shared by the Referral Ingestion API and Referral Status Webhooks. Schemas are defined with Zod and versioned; breaking changes trigger a new version string and advance notice.

Response Envelope

{
  "data": {"...": "..."},
  "meta": {
    "version": "2025-01-01",
    "requestId": "req_123",
    "timestamp": "2025-01-18T22:31:05.123Z"
  }
}

• meta.version maps to the change history communicated in Partner Ops release notes.
• requestId appears in response bodies and X-Request-Id headers—log it for audit or support tickets.

Error Format

JSON

{
  "error": {
    "code": "minutes/invalid-state",
    "message": "Encounter already closed",
    "details": {
      "encounterId": "enc_789",
      "currentState": "resolved"
    }
  }
}

TypeScript

type ApiError = {
  error: {
    code:
      | `auth/${string}`
      | `validation/${string}`
      | `minutes/${string}`
      | `integrations/${string}`
      | `internal/${string}`;
    message: string;
    details?: Record<string, unknown>;
  };
};

export const isRetryable = (error: ApiError) =>
  error.error.code.startsWith('internal/');

Code Pattern	Meaning
auth/*	Missing/invalid HMAC signature.
validation/*	Payload failed schema validation.
referrals/*	Business-rule errors processing the referral.
webhooks/*	Delivery-specific errors (rare; surfaced via Partner Ops).
internal/*	Unexpected server error; retriable.

Idempotency Rules

• Referral POSTs accept Idempotency-Key (UUID v4). Keys persist for 24 hours.
• If the key matches an existing request, the API returns the original response verbatim.
• Duplicates outside the allowed window are rejected with 409 Conflict.

Sample Referral Request/Response

cURL

curl -X POST "https://api.profoundinstitute.org/functions/v1/referrals" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ref_12345" \
  -H "X-ICP-Signature: $(node sign.js payload.json)" \
  -d @payload.json

202 Response

{
  "data": {
    "correlationId": "corr_abc",
    "status": "accepted"
  },
  "meta": {
    "requestId": "req_f4a1c5d4",
    "version": "2025-01-01",
    "timestamp": "2025-01-18T16:04:11.219Z"
  }
}

Webhook Payloads

Webhooks use the same envelope shape (with data set to the event payload unique to each type). Verify X-ICP-Signature before acknowledging; see Referral Status Webhooks for details.

Versioning & Deprecation

• Breaking changes require a new route (/v2/...) with a clear deprecation window communicated through Partner Ops release notes.
• We provide upgrade guides and sample payloads for partners at least 90 days before enforcing sunset dates.

Consistent payloads and errors make it easier for partners and automation to interact with the platform confidently.