API Overview

Partners only need two surfaces: submit referrals and receive status webhooks. Every response returns a requestId you can share with Partner Ops for audit or replay.

Environments & Auth

Environment	Base URL	Notes
Staging	https://staging-api.profoundinstitute.org	Use for all testing before go-live
Production	https://api.profoundinstitute.org	Provisioned after security review

• Auth: Sign every request body with HMAC SHA-256 using your shared secret. Send the digest in X-ICP-Signature.
• TLS: HTTPS only (TLS 1.2+). Set a descriptive User-Agent header for partner tracing.
• Idempotency: Include Idempotency-Key (UUID v4). Keys are retained for 24 hours.
• Rate limits: Default 60 requests/minute per organization; contact Partner Ops for adjustments.

Submit Referrals

POST /functions/v1/referrals with HMAC auth, idempotency, and staging/production environments.

See referral API

Referral Status Webhooks

Receive lifecycle callbacks (accepted → enrolled) with signed payloads and deterministic retries.

Read webhook guide

Payloads & Errors

Reference envelopes, error codes, and response shapes shared by the referral POST and webhooks.

Check payload rules

Integration Checklist

Step	What to do	Notes
Obtain credentials	Request partner API access (JWT/HMAC)	Provisioned by Partner Ops with least-privilege scopes
Test in staging	Use staging endpoints provided at kickoff	Same schemas and error semantics as production
Register webhooks	Configure Stripe/Twilio callbacks to staging and then production	Replay vendor payloads before enabling prod
Monitor & audit	Use correlation IDs and the Partner Ops portal	All events are captured in audit logs for review

Deterministic Testing

Use your partner staging credentials against the published staging endpoints and our Postman/OpenAPI collection. Each request returns a correlation ID you can share with Partner Ops to replay in our audit logs. No local stacks or internal scripts are required.