TEtelgea
Numbers

Obtain a line

Obtains a local line for one of your customers: a market-bound phone number and the eSIM that carries it.

The user must exist in your organization first — create one with POST /v1/users.

Provisioning flow:

  1. This call returns the line's id and state: PROVISIONING
  2. A SIM is assigned from available inventory and the number allocated with the local market's operator
  3. The line reaches READY, and GET /v1/numbers/{numberId} carries its sim.activationCode

Organizations with Telgea's end-user communications enabled also send the user installation instructions by email. White-label integrations have them switched off, so that activation code is the only delivery and presenting it is yours to do.

post/v1/numbers

Request

  • Base URL
    https://api.telgea.com
  • Auth
    API key in header x-api-key

Headers

idempotency-keystring

A value unique to this request, of 1 to 255 printable ASCII characters — a UUID is the usual choice. Retry with the same key within 24 hours and you get the original response back, even if it was a failure, and nothing is done twice. Send a new key whenever you change the request. Keys are private to your API key and organisation.

Example:0b7e4f1c-6a2d-4c9e-8f35-d1a7b2c93e60

Request body

userIdstring uuid required

UUID of an existing user to obtain the line for

countryCodestring required

Two-character ISO country code of the market the line belongs to. Must be a valid ISO 3166-1 alpha-2 code (e.g., "DK", "US", "GB") and available in your organization's list of supported markets. Case-insensitive. Invalid codes are rejected immediately. Contact support to enable additional countries.

Example request

{
  "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
  "countryCode": "DK"
}

Response

Line accepted and being provisioned. Poll GET /v1/numbers/{numberId} until it reaches READY with its SIM.

numberIdstring required

UUID of the line being obtained.

state'PENDING' | 'PORTING' | 'PORTING_FAILED' | 'PROVISIONING' | 'READY' | 'REPLACING' | 'CHANGING' | 'SUSPENDING' | 'SUSPENDED' | 'RESTORING' | 'RECONFIGURING' | 'DEACTIVATING' | 'DEACTIVATED' | 'PORTING_DISCARDED' | 'PORTING_OUT' | 'PORTED_OUT' required

State the line starts in. Poll GET /v1/numbers/{numberId} until it reaches READY.

Example response

{
  "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709",
  "state": "PROVISIONING"
}

Changes

No recorded changes to this operation across all 1 revision of this API.