---
title: "Obtain a line"
method: POST
path: "/v1/numbers"
tags: ["Numbers"]
---

# Obtain a line

`POST /v1/numbers`

## Request

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

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.

## Headers

- `idempotency-key` string: 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.

## Request body

- CreateNumberBody
  - `userId` string, uuid, required: UUID of an existing user to obtain the line for
  - `countryCode` string, 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.

## Response `202`

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

- CreateNumberResponse
  - `numberId` string, 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.

## Other responses

- `400`: Request failed schema validation, or the country code is not a supported ISO 3166-1 alpha-2 code
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions, or the requested country is not available for your organization: nothing it can buy covers the country, or the country requires business verification your organization has not passed.
- `404`: User not found in your organization, or no plan is available for the requested market.
- `409`: The user already holds an active line, so nothing was created.
- `429`: The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.
- `500`: Internal server error. Contact support if this persists.

---

[API](https://skmtc.dev/telgea/apis/telgea-api.md) - [All operations](https://skmtc.dev/telgea/apis/telgea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telgea/apis/telgea-api/revisions/4e8f8c04fe9e?raw)