Skip to main content
Keep one number request throughout onboarding. Its business verification is reusable for later requests only after the customer explicitly confirms the same legal entity and current identity revision.

​
Resumable flow

  1. Create a number draft. Save partial details without starting verification, publishing a site, or provisioning a number.
  2. List existing businesses and ask the customer to select their legal entity, or create a business from the confirmed legal facts. Set businessRelationship to account_business or client_business. A duplicate complete legal identity returns 409 business_identity_exists with the existing businessProfileId; fetch that business and obtain confirmation before reuse.
  3. Confirm the business on the request using its current verificationIdentityRevision. A pending business can be bound while the customer finishes the messaging program and opt-in details.
  4. Complete verification. A complete US identity starts automated KYB; other countries require supporting documents and review. Poll the business or its submission history, or use the existing business_profile.* webhooks.
  5. Submit the saved number request when its businessVerification.ready is true and all required request fields are complete.
The one-shot Create Number Request endpoint remains available with an explicit nested businessVerification confirmation. Existing integrations must add that confirmation; an unrelated verified business elsewhere on the account no longer authorizes a request.

​
Identity and program ownership

Business verification covers the legal entity. The number request retains its own carrier registration identifier, brand, program, public support contacts, URLs, and documents. Confirming a business copies none of those fields. Legal and carrier identifiers can have different purposes: a GB Companies House registration number can verify the entity while the carrier request uses VAT. Equivalent identifier types, such as US EIN, must match. Meaningful identity changes increment the business revision and invalidate old verification evidence and request confirmation. Cosmetic case or punctuation edits preserve them; explicit canonical-name confirmation starts a new revision even when the normalized name is unchanged. Update the affected request facts and confirm the current revision again. A status label alone does not establish eligibility: archived, locked, expired, stale, or unproven businesses cannot authorize provisioning. Historical verified businesses require explicit confirmation; older manual approvals without current audited evidence require review.

​
Names, disputes, and renewal

For name_confirm_required, display verificationCanonicalName. To accept it, PATCH the business with companyLegalName and expectedIdentityRevision; this follows the normal verification lifecycle and does not instantly mark the business verified. If the suggestion is wrong, request manual review. For expired matching provider verification, explicitly request renewal on the same business. Pending retries reuse the ongoing verification; creating another business is not a renewal mechanism.

​
Verification states

​
API keys and agents

Business writes require an account-owned live API key. Binding, submission, name disputes, and renewal also require an associated user. New number submission requires a paid plan or approved billing bypass and the current key owner’s verified email; inert drafts and business confirmation remain available beforehand. Sandbox keys can read and use the validation dry-run. Existing rate limits and account verification caps still apply. Delegated trackly.registration access remains limited to preparing agent drafts and previews. The account owner completes business confirmation, verification, and submission in Trackly; ordinary public mutations reject agent-prepared rows with agent_review_required.