Referral Ingestion API

Partners submit referrals with a single HTTPS POST. All responses include a requestId header/body so you can trace requests with Partner Ops.

Endpoint

Method	Path	Description
POST	/functions/v1/referrals	Submit one referral event.

Environments

Environment	Base URL
Staging	https://staging-api.profoundinstitute.org
Production	https://api.profoundinstitute.org

Authentication

Sign the raw JSON body with HMAC SHA-256 using the secret provided by Partner Ops. Send the digest in X-ICP-Signature. Example (Node.js):

import crypto from 'node:crypto';

const body = JSON.stringify(payload);
const signature = crypto
  .createHmac('sha256', process.env.ICP_REFERRAL_SECRET!)
  .update(body)
  .digest('hex');

await fetch('https://api.profoundinstitute.org/functions/v1/referrals', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-ICP-Signature': signature,
    'Idempotency-Key': payload.idempotencyKey,
  },
  body,
});

Python (verification or sending):

import hmac, hashlib, json, requests, os

body = json.dumps(payload).encode()
signature = hmac.new(
    os.environ["ICP_REFERRAL_SECRET"].encode(),
    body,
    hashlib.sha256,
).hexdigest()

requests.post(
    "https://api.profoundinstitute.org/functions/v1/referrals",
    headers={
        "Content-Type": "application/json",
        "X-ICP-Signature": signature,
        "Idempotency-Key": payload["idempotencyKey"],
    },
    data=body,
)

Idempotency & Rate Limits

• Header: Idempotency-Key (UUID v4). Keys are retained for 24 hours; the original response is replayed for duplicates.
• Default rate limit: 60 requests per minute per organization. Contact Partner Ops if you need more.

Request Payload

{
  "referralId": "ref_12345",
  "idempotencyKey": "ref_12345",
  "patient": {
    "firstName": "Ana",
    "lastName": "Lopez",
    "dob": "1951-02-04",
    "sex": "female",
    "phone": "+12135551234",
    "email": "[email protected]",
    "language": "es"
  },
  "coverage": {
    "payer": "Medicare Advantage",
    "memberId": "A123456789",
    "plan": "Acme Gold MA PPO"
  },
  "referring": {
    "organization": "Sunrise Health",
    "location": "Austin - North",
    "source": "pair-integrations-v1"
  },
  "context": {
    "reason": "depression_screen_positive",
    "phq9": 14,
    "gad7": 12
  }
}

Responses

• 202 Accepted

{
  "correlationId": "corr_abc",
  "status": "accepted",
  "requestId": "req_f4a1c5d4"
}

• 409 Conflict (duplicate idempotency key with matching payload hash) — returns original response body/correlationId.
• 400/401 for validation/authentication errors with details per Payloads & Error Semantics.

Notes

• Send one referral per request; contact Partner Ops for bulk file imports.
• Do not include financial account data. Eligibility and billing enrichment happen downstream.
• Save the correlationId—it ties partner events to internal audit logs and appears on referral status webhooks.