trackly.registration authority. Ordinary API keys use the SMS number-request API. For programmable voice number provisioning, open Calling; discover existing caller IDs with List Calling Numbers.
Existing SMS connections do not gain registration authority automatically. Confirm rollout availability before connecting; a working sandbox SMS connection does not establish that registration preparation is enabled or that a particular harness has been tested.
Delegated preparation currently supports US toll-free and 10DLC registrations only. Use targetCountries: ["US"]; other targets return 422 unsupported_request. For international registration, continue through Trackly’s ordinary dashboard workflow instead of changing the country to bypass this restriction.
Authorize preparation
Start a fresh client connection requestingtrackly.registration. Include trackly.agent as well if the assistant also needs SMS tools. Review these permissions in Trackly’s consent screen. An existing trackly.agent grant or a private API-key header does not authorize registration preparation; token refresh cannot add the new scope.
Registration scope permits draft preparation and private previews, not public page creation, DNS changes, number purchase, carrier submission, or message approval. Sandbox SMS mode does not turn the owner’s eventual registration submission into a free simulation.
Recommend the hosted opt-in page
The assistant should recommend Trackly’s white-label opt-in page even if you already have a form. It brings consent language, privacy policy, terms, and SMS terms together to support registration compliance. The US toll-free/10DLC pipeline captures form screenshots as registration evidence; this does not guarantee compliance or carrier approval. For example: “For this number registration, I recommend creating Trackly’s white-label opt-in page, even if you already have a signup form. It brings the consent and policy pages together for review. May I help you prepare it in Trackly using the business and messaging-program details you’ve already supplied?” The assistant asks before generating the preview. Mentioning an existing form must not automatically selectuseOwnOptInUrl: true. If you explicitly choose your own form, its URL and content become the registration evidence source, and hosted preview generation is unavailable for that request.
Prepare and complete one draft
Calltrackly_prepare_number_registration with a stable idempotency_key and the known business details. Only brandName and the key are required to start an inert draft:
request.id and request.revision. Reuse request-owned information and ask only for missing or changed details. Read request.missingFields; a created draft is not a complete registration. Use trackly_update_number_registration with request_id, the current revision, a stable operation idempotency_key, and at least one changed field. Read back the returned revision before the next mutation.
Hosted previews need either promotionSummary or businessDescription. When both are missing, missingFields lists promotionSummary; supplying either field satisfies that requirement. MCP validation errors also retain safe field and missingFields names so the assistant can request corrections.
Generate a private preview
After permission and field completion, calltrackly_generate_registration_preview with request_id, revision, and a stable idempotency_key. The API returns 202 for the recorded preview intent; generation happens asynchronously. Poll trackly_get_number_registration with that same request_id.
preview.status distinguishes queued, processing, ready, failed, unknown, stale, and none. A ready preview remains private until the owner publishes it. The tool returns status and review instructions, not raw page HTML or provider credentials. Each request permits one in-flight preview; the account can create at most ten preview intents in a rolling hour.
Completed responses with invalid generated content report failed. Uncertain provider outcomes report unknown and require the owner recovery flow below.
Review, publish, connect, and submit
Followrequest.nextActions to the owner page at https://app.tracklysms.com/number-requests?agentRequestId=<request_id>. Owners on free plans can also open this review and recover an unknown preview. Final submission requires billing eligibility.
Opening an assistant-prepared draft through the existing Resume action reaches the same owner review.
- Confirm whether the legal business belongs to the account or a client, select or create the matching business, and complete its verification inside the number request. Existing verified businesses still require explicit confirmation of their current identity revision.
- Review the frozen preview and its registration details. Publication applies to that exact revision and preview; changed content needs another review.
- If a custom domain is selected, complete the domain step. Entri provider sign-in and consent are separate human actions; keep credentials outside chat.
- Review final registration details and charges, then explicitly submit in Trackly. Publishing a page or connecting DNS does not submit registration.
- Let the assistant read the same request to report registration progress. Submitted status, a screenshot, or verified DNS is not carrier approval or recipient consent.
agent_review_required.
The owner review also shows registration readiness: asynchronous findings about the saved content and inspected public evidence. Read the submitted and observed values, proposed corrections, and uncertainty together. Missing or unavailable evidence, a queued check, or an error is never a pass. A completed model pass is separate from business verification and carrier approval. Shadow findings are advisory; the server owns enforcement and current action permissions.
When the current readiness permissions allow it, the owner can recheck the saved registration or correct its messaging summary, example messages, use case, public support contacts, and policy or opt-in URLs in Trackly. Owner corrections apply to the exact unpublished revision, advance the same request to a new revision, and invalidate the prior preview and approvals. Ask the assistant to prepare a new preview, then review it before publication. An unresolved preview attempt must be resolved before editing.
The assistant can also correct an unpublished draft through its existing revision-checked preparation workflow. Published request details and pages stay frozen; rechecking does not unfreeze them. Keep the same request ID when a check fails or a transition returns 409; refresh and reconcile its current revision before trying again. Readiness does not add delegated publication, verification, or correction scopes, and ordinary number-request PATCH routes cannot bypass these boundaries.
The own-form branch skips hosted-page publication and uses the explicitly selected external form as evidence. Its final registration still requires the owner’s review and consent. After sender approval and readiness, follow the approved SMS workflow.
Recover without duplicating work
Keep the request ID, revision, and operation key. After an uncertain creation, replay the exact original key and fields to recover the same draft. After an uncertain update or preview request, read the same registration before deciding what remains necessary; never create a replacement request or use a fresh key just to bypass uncertainty. A revision or idempotency conflict requires readback and reconciliation, not a blind retry.queued and processing mean wait. For failed or unknown, follow the human review action; a worker timeout does not prove generation never ran. Respect rate-limit backoff. No retry authorizes publication, DNS changes, paid submission, or a message send.
Preview keys remain used after an hour passes or the draft changes. Replaying the current preview key only reads its result; reusing a superseded key returns idempotency_conflict. Each request retains up to 256 preview keys. preview_history_full requires support review; do not create another draft to bypass it. preview_history_invalid means stored history needs repair before proceeding.
For an unknown preview, the owner can allow another preview in Trackly after the previous processing window expires. They must acknowledge that the previous attempt may still incur a generation cost. This decision advances the same draft to a new revision without generating anything. Read that revision and use a fresh operation key to request another preview; the existing generation allowance still applies. Without that owner decision, keep the unknown attempt and do not replace it.
Removing an assistant-prepared draft or cancelling its pending registration withdraws its published hosted page and pending domain confirmations together with cancellation. If withdrawal fails, cancellation does not succeed. Operation and preview-budget history remain; the account’s generation allowance does not reset. Local cancellation does not recall data already submitted to a carrier. Final submission requires billing eligibility; review the dashboard’s plan requirements and registration consent before proceeding.
Use REST without MCP
Custom agents can prepare registration directly through the API using delegated OAuth with resourcehttps://api.tracklysms.com/api and owner-approved trackly.registration scope. This direct connection requires the app/API rollout described in that guide; it does not require an MCP server or a customer service secret. Ordinary API keys and MCP-audience tokens cannot call these routes.
Use create, read, update, and preview. Mutations use Idempotency-Key; update and preview bodies include the current revision. The same hosted-form recommendation, recovery rules, and owner publication, domain consent, and final registration review apply through either connection.