Submit a number registration profile

Prepare the saved profile and number

Use this workflow to associate a saved registration profile with a purchased number and, for supported carrier-backed numbers, request registration review. It is not a general activation API for every number provider. A successful request does not prove that documents are approved or the number is active.

Use an enabled MultiTEL API account over HTTPS with its configured credentials and IP restrictions. Both the non-deleted profile and the purchased, non-void number must belong to your account.

1. Create a registration profile or select an existing one. Keep the local profile uuid from create_document; get_document returns the same local reference as id.
2. For carrier-backed submission, the profile needs its saved identity and address references. Attach the required proofs and supporting documents through their appropriate workflows before submission.
3. Check that the number and profile meet the applicable country and number requirements. Do not assume that a saved profile is approved for every number.

Submit the association

curl --silent --show-error --request POST \
  --user "$API_USER:$API_PASSWORD" \
  --form-string document_uuid="$PROFILE_UUID" \
  --form-string service_description="Example customer support line" \
  https://api.multitel.net/v3/number_identity/12125550123

The path contains the purchased telephone number, not its UUID, a PBX extension or an identity ID. The handler removes non-digits from the number. Use the full international number with country code. The example is fictional and must be replaced with your own number and saved local profile reference.

For multipart requests, an array uses repeated onetime_files[] fields. A JSON request is also accepted with Content-Type: application/json; its properties are merged into the form payload. A number may be provided in the payload when the path number is omitted. Prefer the explicit path shown above to avoid ambiguity.

Distinguish association from approval

Read both the HTTP result and the JSON status.code. JSON errors can arrive with HTTP 200. A carrier-backed success reports Address verification task created; awaiting carrier review. This example uses fictional references.

{
  "status": {
    "code": 200,
    "msg": "Address verification task created; awaiting carrier review."
  },
  "response": {
    "number": "+12125550123",
    "did_id": "11111111111111111111111111111111",
    "document_uuid": "0123456789abcdef0123456789abcdef",
    "identity_id": "22222222222222222222222222222222",
    "address_id": "33333333333333333333333333333333",
    "address_verification_id": "44444444444444444444444444444444",
    "verification_status": "pending",
    "verification_reference": null,
    "requirement_id": "55555555555555555555555555555555",
    "registration_details_id": "8516ac99dc60603295de7bdb6a153530"
  }
}

The provider-related identifiers are masked references, not interchangeable local profile IDs. document_uuid remains the local profile reference you submitted. In this handler's carrier-backed path, registration_details_id is a further hash of that local reference; do not replace document_uuid with it in later profile or submission requests.

Some allocated numbers use local identity association rather than creation of a carrier verification. Their successful result is Identity associated. with an empty response array. It does not create a carrier review task or establish approval. The portal has a newer association workflow whose provider handling and repeat-submission checks differ from this endpoint.

Handle errors without creating duplicate tasks

API code 400 covers a missing number or profile reference. Code 404 covers a profile or number unavailable for the account or a number missing from the carrier inventory. Code 422 can report missing identity/address references, seller requirements or carrier validation rejection. Missing callback configuration can produce 503, and a creation transport failure can produce 502. Read the message and any requirement_diagnostics rather than treating every failure the same way.

The carrier-backed path can update local pending-registration flags before requirement validation, callback configuration checks or task creation finish. An error therefore does not imply that local state is unchanged, and a pending flag alone does not prove that a task exists. Do not use those flags as confirmation of approval or delivery of the request.

The provider may accept a task even if a later local database operation fails, and this helper does not check every local write result before reporting success. There is no client idempotency parameter or duplicate-submission guard in this handler. After a timeout, error or uncertain result, check the number's registration history in the portal or contact support before submitting again. A missing local record does not by itself prove the provider received nothing.

One-time document limitation

The handler accepts onetime_files and forwards each nonempty string into the carrier's encrypted-file relationship. It does not look up the owning account's upload rows or translate external masked upload IDs into provider file IDs. The offline audit verified forwarding behavior, not successful carrier attachment.

Do not assume that a file ID from create_encrypt_files can be copied into this field to complete a one-time agreement workflow. Use the portal or confirm the supported identifier workflow with MultiTEL when a number requires these documents. This remains an unresolved part of the API review, not a verified end-to-end example.

Protect registration information

Only submit information and documents you are authorized to use for the number. Keep profile and verification references associated with the correct account, and avoid logging full registration payloads. This request does not delete or replace every prior proof or verification. Carrier review, activation and retention are separate processes.