Check availability
This is a feature-gated scaffold, not a live registration service. First call GET /registration-capabilities. It reports whether the scaffold is enabled and the current foundation requirements for toll_free, short_code and rcs_agent. Provider-specific fields, contracts, fees and approval routes still need confirmation. No TCR brand verification gate applies to these types.
Draft and review lifecycle
- Create a draft with
POST /registrations, a uniqueIdempotency-Key, atype,provider_mode(manualorsandbox), and type-specificdetails. The example below is intentionally a partial draft. - Save its
refandrevision. Edit usingPATCH /registrations/{ref}withexpected_revision. A stale revision returns 409; read the current record before retrying. - Call
POST /registrations/{ref}/validateto see missing foundation requirements. Add HTTPS evidence references; files are not uploaded or fetched by this scaffold. - Request review with
/request-review. A reviewer can return it with/request-revisionand a reason, or approve the exact revision with/approve. These actions requireexpected_revision. - In sandbox mode, an authorized submitter can call
/submitwithexpected_revisionand anIdempotency-Key. It returns 202 and an operation reference. The result explicitly sayssimulated=trueandexternal_submitted=false. No provider is contacted. - Manual mode returns
409 manual_handoff_required; it does not claim to have performed a handoff. Internal approval never means provider or carrier readiness. Use/eventsfor revision history andGET /registration-operations/{ref}for the simulation result.
POST /registrations Idempotency-Key: <unique-request-id> { "type": "toll_free", "provider_mode": "sandbox", "details": { "country": "US", "business_name": "Example Business", "numbers": ["+18005550123"] } }
Registration creation and sandbox submission replay the original result for the same company, key and body; a changed body returns 409. Lists accept limit (1–100), an opaque cursor, and optional registration_type. The response's next cursor drives the next page.