Integration checklist
Check your integration's versioning, errors, retries, webhooks, credentials and safety before you send real traffic.
Use this checklist after your integration works with test numbers and before it sends real traffic. Each item links to the page with the full rules.
Requests#
Pin the API version. Send Polymorfa-Version: 2026-09-22 on every Messaging and Platform request, so a new contract date doesn't change your integration without warning. Read the version the response echoes. See Versioning.
Handle every error. Branch on the error code, not the message text. Treat 401 and 403 as configuration problems and 404 on another project's resource as a boundary, not a reason to retry. Log the request ID. See Errors and, in TypeScript, SDK errors.
Retry writes with an idempotency key. Send an Idempotency-Key with every message write you might retry, and reuse the same key for the retry. Platform webhook changes require one. A key never makes a changed request safe. See Idempotent requests.
Respect rate limits. Back off on 429 and follow Retry-After. See Rate limits.
Webhooks#
Register endpoints for each project. Subscribe to the event types you handle, in the project that owns the Numbers. Team endpoints receive only team events. See Webhooks.
Verify every signature. Check X-Webhook-Signature against the raw request body before you parse it, and reject a mismatch. See Verify a webhook.
Handle duplicates and order. Store each event id and skip repeats. Expect retries and events that arrive out of order. Return 2xx only after you have stored the event. See Receiver rules.
Credentials#
Keep keys on your servers. Team keys and project tokens belong in a secret manager or server environment, never in browser or mobile code. Give browsers and apps a client token instead.
Use the narrowest credential. Prefer a project token over a team key, and select only the permissions the integration uses. See API keys.
Plan rotation. Deploy a replacement before you revoke a credential, and revoke any credential that may have been exposed. See Rotate a key.
Numbers and safety#
Replace test numbers with real numbers. Test numbers reach only other test numbers in the same project. Connect real numbers with QuickLink and choose each Number's tier. See Number tiers.
Protect new real numbers. Turn on the warm-up plan for the project and review Safe Mode before you send at volume. See Safety.
Honor opt-outs. Keep your team's opt-out list current and don't message numbers on it. See Opt-outs.
Billing#
Upgrade to Pay-As-You-Go when you need more than Free. Free teams have one project and one real Number at no charge, and can't send QuickLinks for real numbers. See Upgrade to Pay-As-You-Go.
Set spending limits. Give projects, Customers and Numbers monthly limits in credits, so a fault in your integration can't spend the whole balance. See Spending budgets and Usage.