Telgea Developer Docs

Bring a number from another carrier: discover the fields each country needs, validate, submit and track the port.

The port-in object

Port phone numbers from other providers into Telgea.

Field Type Description

idrequired

string

UUID of the port-in request.

c3d4e5f6-a7b8-9012-c345-678901234567

countryCoderequired

string

Market the number is being ported into.

DE

msisdnrequired

string

The number being ported, in E.164 format.

+4915112345678

executionDaterequired

string

The porting date, as YYYY-MM-DD.

2027-03-01

typerequired

string

Port-in type this request was submitted under, or null when the donor needed none.

personal

statusrequired

enum

PENDINGCREATEDSUBMITTEDACCEPTEDREJECTEDSUCCEEDEDFAILED

Current status of the port-in

CREATED

numberIdrequired

string

UUID of the number this port-in creates. Use it to read the line once porting succeeds.

8238c1b9-c2c0-4455-9b03-4bd787052709

failurerequired PortInFailure Why a REJECTED or FAILED port-in ended that way: values you can branch on, and a text you can show your customer. Null in every other status.

Show 3 child fields of failure

Field	Type	Description
`reason`required	enum `WRONG_CUSTOMER_TYPECONTRACT_LOCKEDNUMBER_OWNERSHIP_MISMATCHNUMBER_ALREADY_PORTINGAUTHORIZATION_CODE_INVALIDPORTING_DATE_UNAVAILABLEFIELD_MISSINGFIELD_INVALIDFIELD_MISMATCHREJECTED_BY_DONORCANCELLED`	Why the port-in ended this way, or null when we could not classify it. `AUTHORIZATION_CODE_INVALID`
`field`required	string	What the donor objected to, when it identified something. Either a key you sent in `fields` (e.g. `authorizationCode`) or a top-level property of the port-in (`msisdn`, `type`, `executionDate`). `authorizationCode`
`text`required	string	What happened and what to do next, in English, for showing to your customer. The wording may change at any time: branch on `reason`, never on this. `Your authorization code was refused or has ex…`

createdAtrequired

string

When the port-in was submitted, ISO 8601.

2027-02-22T10:00:00Z

updatedAtrequired

string

When the port-in last changed status, ISO 8601.

2027-02-22T10:00:00Z

Get port-in fields for a country

GET/v1/port-ins/fields/{countryCode}

Enterprise APIPartner API

Retrieves the dynamic form fields required to submit a number port-in for a given country. Different countries and providers require different information (e.g., authorization codes, account numbers, personal details).

The response is keyed by port-in type (e.g., "personal", "business"). Each type contains a human-readable label and an array of input field definitions with validation rules.

Each type also carries the market's transfer date as executionDate and how a port-in into the market runs as timing. Both hold for the whole market, and repeat in every type because the response is keyed by type.

Use this endpoint to build dynamic forms that collect the right data before submitting a port-in.

Requires the permission port-ins:read on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Parameter	In	Type	Description
`countryCode`required	path	string	ISO 3166-1 alpha-2 country code (e.g., "DK", "US", "GB") `DE`

Responses

Status	Meaning	Body
`200`	Successfully retrieved port-in field definitions for the specified country. The response is keyed by port-in type (e.g., `personal`, `business`). Each type contains a human-readable label and an array of field definitions describing the inputs required for that port-in type. Field types are `text`, `select`, `date`, `number` and `checkbox`. Each carries only the constraints that apply to it: `minLength`, `maxLength` and `regex` on text; `options` on select; `minDate`, `maxDate`, `dates` and `validUntil` on date; `min`, `max` and `decimalPlaces` on number; `requiredValue` on checkbox. Any field can carry `help`, `howToGet` and an `example` of its format. `executionDate` is a date field whose `dates` are every date a port-in can happen on, as of today in the market's time zone. They hold until `validUntil`, the market's next midnight; fetch the fields again after it.	`GetPortInFieldsResponse`
`400`	The countryCode is not a valid ISO 3166-1 alpha-2 code. Valid codes look like DK, US, GB or FR.	none
`401`	Missing or invalid API key in the X-API-Key header	`UnauthorizedError`
`403`	Insufficient permissions to read port-in data	`ForbiddenError`
`429`	The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.	`TooManyRequestsError`
`500`	Internal server error. Contact support if this persists.	`InternalError`

Problems this endpoint can return

This endpoint returns no domain-specific problems.

GET/v1/port-ins/fields/{countryCode}

Request

curl -X GET "https://api.telgea.com/v1/port-ins/fields/DE" \
  -H "x-api-key: $TELGEA_API_KEY"

Response

{
  "personal": {
    "label": "Personal",
    "typeLabel": {
      "id": "port-in.de.typeLabel",
      "en": "Who is the number registered to?"
    },
    "explanation": {
      "id": "port-in.de.personal.explanation",
      "en": "The contract is in a person's name."
    },
    "fields": [
      {
        "name": "currentCarrier",
        "label": "Current carrier",
        "description": "Your current mobile carrier",
        "type": "select",
        "help": {
          "id": "port-in.de.currentCarrier.help",
          "en": "The brand on your bill or SIM."
        },
        "options": [
          {
            "label": "Congstar",
            "value": "CONG"
          },
          {
            "label": "O2 Deutschland GmbH",
            "value": "O2DE"
          },
          {
            "label": "Vodafone GmbH",
            "value": "VODA"
          }
        ]
      },
      {
        "name": "authorizationCode",
        "label": "Date of birth",
        "description": "Owner date of birth (YYYY-MM-DD)",
        "type": "date",
        "help": {
          "id": "port-in.de.personal.authorizationCode.help",
          "en": "Date of birth of the contract holder."
        }
      },
      {
        "name": "ownerFirstName",
        "label": "First name",
        "description": "Account owner first name",
        "type": "text",
        "minLength": 1,
        "help": {
          "id": "port-in.de.asOnTheContract",
          "en": "As on the contract."
        }
      },
      {
        "name": "ownerLastName",
        "label": "Last name",
        "description": "Account owner last name",
        "type": "text",
        "minLength": 1,
        "help": {
          "id": "port-in.de.asOnTheContract",
          "en": "As on the contract."
        }
      },
      {
        "name": "isUnlocked",
        "label": "Number released for porting",
        "description": "Please confirm that the current carrier has been contacted and unlocked the number for port-out",
        "type": "checkbox",
        "help": {
          "id": "port-in.de.isUnlocked.help",
          "en": "Ask your current carrier to release the number before you start."
        },
        "requiredValue": true
      }
    ],
    "executionDate": {
      "name": "executionDate",
      "label": "Transfer date",
      "type": "date",
      "help": {
        "id": "port-in.executionDate.help.a-weekday-from-7-days-to-14-days-from-today",
        "en": "A weekday, from 7 days to 14 days from today."
      },
      "errorMessage": "That date isn't possible. Choose a weekday from 7 days to 14 days from today.",
      "minDate": "2027-03-01",
      "maxDate": "2027-03-08",
      "dates": [
        "2027-03-01",
        "2027-03-02",
        "2027-03-03",
        "2027-03-04",
        "2027-03-05",
        "2027-03-08"
      ],
      "validUntil": "2027-02-22T23:00:00.000Z"
    },
    "timing": {
      "submitted": "beforeTheDate",
      "finalDateSetBy": "oldCarrier",
      "dateMayMove": true,
      "cancel": "beforeSubmission",
      "reschedule": "beforeSubmission"
    }
  },
  "business": {
    "label": "Business",
    "typeLabel": {
      "id": "port-in.de.typeLabel",
      "en": "Who is the number registered to?"
    },
    "explanation": {
      "id": "port-in.de.business.explanation",
      "en": "The contract is in a company's name."
    },
    "fields": [
      {
        "name": "currentCarrier",
        "label": "Current carrier",
        "description": "Your current mobile carrier",
        "type": "select",
        "help": {
          "id": "port-in.de.currentCarrier.help",
          "en": "The brand on your bill or SIM."
        },
        "options": [
          {
            "label": "Congstar",
            "value": "CONG"
          },
          {
            "label": "O2 Deutschland GmbH",
            "value": "O2DE"
          },
          {
            "label": "Vodafone GmbH",
            "value": "VODA"
          }
        ]
      },
      {
        "name": "authorizationCode",
        "label": "Customer number",
        "description": "Your customer number with the current carrier. Can be found on a recent bill from them or by contacting the carrier directly.",
        "type": "text",
        "minLength": 1,
        "help": {
          "id": "port-in.de.business.authorizationCode.help",
          "en": "On the current carrier's invoice."
        },
        "howToGet": {
          "id": "port-in.de.business.authorizationCode.howToGet",
          "en": "On the current carrier's invoice."
        }
      },
      {
        "name": "companyName",
        "label": "Company name",
        "description": "Registered company name of company that owns the number",
        "type": "text",
        "minLength": 1,
        "help": {
          "id": "port-in.de.asOnTheContract",
          "en": "As on the contract."
        }
      },
      {
        "name": "isUnlocked",
        "label": "Number released for porting",
        "description": "Please confirm that the current carrier has been contacted and unlocked the number for port-out",
        "type": "checkbox",
        "help": {
          "id": "port-in.de.isUnlocked.help",
          "en": "Ask your current carrier to release the number before you start."
        },
        "requiredValue": true
      }
    ],
    "executionDate": {
      "name": "executionDate",
      "label": "Transfer date",
      "type": "date",
      "help": {
        "id": "port-in.executionDate.help.a-weekday-from-7-days-to-14-days-from-today",
        "en": "A weekday, from 7 days to 14 days from today."
      },
      "errorMessage": "That date isn't possible. Choose a weekday from 7 days to 14 days from today.",
      "minDate": "2027-03-01",
      "maxDate": "2027-03-08",
      "dates": [
        "2027-03-01",
        "2027-03-02",
        "2027-03-03",
        "2027-03-04",
        "2027-03-05",
        "2027-03-08"
      ],
      "validUntil": "2027-02-22T23:00:00.000Z"
    },
    "timing": {
      "submitted": "beforeTheDate",
      "finalDateSetBy": "oldCarrier",
      "dateMayMove": true,
      "cancel": "beforeSubmission",
      "reschedule": "beforeSubmission"
    }
  }
}

Get port-in fields JSON Schema

GET/v1/port-ins/fields/{countryCode}/schema

Enterprise APIPartner API

Retrieves JSON Schema definitions for port-in fields, keyed by port-in type. Use these schemas for client-side validation of port-in form data before submission.

Each key in the response corresponds to a port-in type (e.g., "personal", "business"), and the value is a standard JSON Schema object that can be used with any JSON Schema validator.

A type whose market declares transfer dates also carries $defs.executionDate: check the port-in's executionDate against it. Its dates hold until the executionDate.validUntil the fields endpoint returns; fetch the schema again after it. Nothing in the schema's properties refers to it, so the schema validates fields alone.

Requires the permission port-ins:read on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Parameter	In	Type	Description
`countryCode`required	path	string	ISO 3166-1 alpha-2 country code (e.g., "DK", "US", "GB") `DE`

Responses

Status	Meaning	Body
`200`	Successfully retrieved JSON Schema definitions for port-in fields.	`GetPortInFieldsSchemaResponse`
`400`	The countryCode is not a valid ISO 3166-1 alpha-2 code. Valid codes look like DK, US, GB or FR.	none
`401`	Missing or invalid API key in the X-API-Key header	`UnauthorizedError`
`403`	Insufficient permissions to read port-in data	`ForbiddenError`
`429`	The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.	`TooManyRequestsError`
`500`	Internal server error. Contact support if this persists.	`InternalError`

Problems this endpoint can return

This endpoint returns no domain-specific problems.

GET/v1/port-ins/fields/{countryCode}/schema

Request

curl -X GET "https://api.telgea.com/v1/port-ins/fields/DE/schema" \
  -H "x-api-key: $TELGEA_API_KEY"

Response

{
  "personal": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "currentCarrier": {
        "type": "string",
        "enum": [
          "CONG",
          "O2DE",
          "VODA"
        ],
        "errorMessage": "Value must be one of the allowed options"
      },
      "authorizationCode": {
        "type": "string",
        "format": "date",
        "errorMessage": "Value must be a valid date"
      },
      "ownerFirstName": {
        "type": "string",
        "minLength": 1
      },
      "ownerLastName": {
        "type": "string",
        "minLength": 1
      },
      "isUnlocked": {
        "type": "boolean",
        "const": true,
        "errorMessage": "Value must be true"
      }
    },
    "required": [
      "currentCarrier",
      "authorizationCode",
      "ownerFirstName",
      "ownerLastName",
      "isUnlocked"
    ],
    "additionalProperties": false,
    "$defs": {
      "executionDate": {
        "type": "string",
        "enum": [
          "2027-03-01",
          "2027-03-02",
          "2027-03-03",
          "2027-03-04",
          "2027-03-05",
          "2027-03-08"
        ],
        "format": "date",
        "errorMessage": "That date isn't possible. Choose a weekday from 7 days to 14 days from today."
      }
    }
  }
}

Validate port-in data

POST/v1/port-ins/validate

Enterprise APIPartner API

Validates port-in data against provider requirements without creating a port-in. Use this endpoint to check whether the submitted fields, phone number, and execution date would pass provider validation before committing to a port-in submission.

The executionDate must be one of the type's executionDate.dates from GET /v1/port-ins/fields/{countryCode}, which hold until its validUntil. The date is checked once everything else passes: a date outside them is then refused with 400 BAD_REQUEST, not valid: false.

This is a dry-run operation — no resources are created or modified.

Requires the permission port-ins:validate on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Parameter	In	Type	Description
`idempotency-key`	header	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. `0b7e4f1c-6a2d-4c9e-8f35-d1a7b2c93e60`

Request body

Field	Type	Description
`countryCode`required	string	ISO 3166-1 alpha-2 country code `DE`
`type`required	string	Port-in type as returned by the fields endpoint (e.g., "personal", "business") `personal`
`msisdn`required	string	Phone number to port in, in E.164 format `+4915112345678`
`executionDate`required	string (date)	Requested porting date in YYYY-MM-DD format. Must be one of the type's `executionDate.dates` from `GET /v1/port-ins/fields/{countryCode}`, which hold until its `validUntil`. `2027-03-01`
`fields`required	map of unknown	Port-in fields as defined by the fields endpoint. Must include authorizationCode. `{"currentCarrier":"CONG","authorizationCode":…`

Responses

Status	Meaning	Body
`200`	Validation completed. Check the `valid` field to determine if the data passed. If `valid` is false, the `errors` array contains details: each error names its `field` and carries a stable `code` to branch on.	`ValidatePortInResponse`
`400`	Request body failed schema validation, or everything else passed and the `executionDate` is not one the market offers	none
`401`	Missing or invalid API key in the X-API-Key header	`UnauthorizedError`
`403`	Insufficient permissions to validate port-ins	`ForbiddenError`
`409`	The number cannot be ported in: Telgea already holds it, or a port-in for it is already in flight. Creating the port-in would be refused the same way.	`ConflictError`
`429`	The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.	`TooManyRequestsError`
`500`	Internal server error. Contact support if this persists.	`InternalError`

Problems this endpoint can return

Status	Problem	When
`409`	Number already with Telgea	A port-in is submitted for a number that is already served by Telgea.
`409`	Number in termination grace period	A port-in is submitted for a number whose plan ended recently.
`409`	Port-in already in progress	A port-in is submitted for a number while an earlier port-in for it has not finished.
`400`	Transfer date not offered	A port-in is validated or submitted with an executionDate outside the dates its market offers.

Response fields

200 ValidatePortInResponse

Field Type Description

validrequired

boolean

Whether the port-in data passed validation

true

errorsrequired array of PortInValidationError List of validation errors, empty if valid

Show 3 child fields of errors

Field	Type	Description
`message`required	string	Validation error description `A PAC is 3 letters, then 6 digits (e.g. ABC12…`
`field`	string	The field that caused the validation error `authorizationCode`
`code`required	enum `REQUIREDFORMAT_INVALIDLENGTH_INVALIDNOT_ALLOWEDDATE_NOT_ALLOWEDCHECK_DIGIT_INVALIDWRONG_CUSTOMER_TYPE`	Why the value was refused, as a stable code to branch on. A code is never renamed or removed, but new ones can be added: show the `message` for a code you do not recognise. `FORMAT_INVALID`

POST/v1/port-ins/validate

Request

curl -X POST "https://api.telgea.com/v1/port-ins/validate" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "countryCode": "DE",
  "type": "personal",
  "msisdn": "+4915112345678",
  "executionDate": "2027-03-01",
  "fields": {
    "currentCarrier": "CONG",
    "authorizationCode": "1985-04-12",
    "ownerFirstName": "Erika",
    "ownerLastName": "Mustermann",
    "isUnlocked": true
  }
}'

Response

{
  "valid": true,
  "errors": []
}

Submit a port-in request

POST/v1/port-ins

Enterprise APIPartner API

Submits a number porting request to bring a phone number from another carrier into Telgea. The user must have an existing plan in INACTIVE or PORTING status.

Important constraints: - The executionDate must be one of the type's executionDate.dates from GET /v1/port-ins/fields/{countryCode}, which hold until its validUntil. The date is checked once everything else passes: a date outside them is then refused with 400 BAD_REQUEST, and no port-in is created. - Only one port-in can be in progress per phone number at a time. Submitting a port-in for an MSISDN that already has an active (non-completed, non-failed, non-rejected) port-in will be rejected. - A number already with Telgea cannot be ported in: one on a Telgea line, or one whose plan ended within the last 14 days and can still be restored. It is refused with 409 CONFLICT.

Recommended flow: 1. Call GET /v1/port-ins/fields/{countryCode} to discover required fields for the country 2. Call POST /v1/port-ins/validate to verify the data before submission 3. Call this endpoint to submit the port-in

If provider-side validation fails, the response will have status: "REJECTED" with an errors array describing the issues. A successful submission returns status: "CREATED".

The port-in will progress through states: CREATED → SUBMITTED → ACCEPTED → SUCCEEDED. Check the status with GET /v1/port-ins/{portInId}.

Retrying a port-in that ended in REJECTED or FAILED: read failure.reason and failure.field on the port-in, correct what they point at (failure.text explains it in words you can show your customer), then call this endpoint again with the same msisdn. The failed attempt is kept as history and stays readable at its own id — GET /v1/port-ins/number/{numberId} lists every attempt for the number, newest first. A retry sent while a port-in for that number is still in flight is refused with 409 CONFLICT — a number can only be ported once at a time anywhere. Wait for it to finish, then read failure.reason and submit again.

Requires the permission port-ins:create on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Parameter	In	Type	Description
`idempotency-key`	header	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. `0b7e4f1c-6a2d-4c9e-8f35-d1a7b2c93e60`

Request body

Field	Type	Description
`userId`required	string (uuid)	UUID of the user to port a number for. The user must have an INACTIVE or PORTING plan. `9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01`
`countryCode`required	string	ISO 3166-1 alpha-2 country code `DE`
`msisdn`required	string	Phone number to port in, in E.164 format `+4915112345678`
`executionDate`required	string (date)	Requested porting date in YYYY-MM-DD format. Must be one of the type's `executionDate.dates` from `GET /v1/port-ins/fields/{countryCode}`, which hold until its `validUntil`. `2027-03-01`
`type`required	string	Port-in type as returned by the fields endpoint (e.g., "personal", "business") `personal`
`fields`required	map of unknown	Port-in fields as defined by the fields endpoint. Must include authorizationCode. `{"currentCarrier":"CONG","authorizationCode":…`

Responses

Status	Meaning	Body
`200`	Port-in request processed. Check the `status` field: "CREATED" means the port-in was accepted for processing; "REJECTED" means validation failed — see the `errors` array.	`CreatePortInResponse`
`400`	Request body failed schema validation, or business rule violation (e.g., user plan not in correct state, or, once everything else passes, an `executionDate` the market does not offer)	none
`401`	Missing or invalid API key in the X-API-Key header	`UnauthorizedError`
`403`	Insufficient permissions to create port-ins, or the country is not available for your organization: it is not enabled, or it requires business verification your organization has not passed.	`ForbiddenError`
`404`	No user with the given `userId` exists in your organization, so no port-in was created.	`NotFoundError`
`409`	No port-in was created: Telgea already holds this number, or a port-in for it is already in flight.	`ConflictError`
`429`	The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.	`TooManyRequestsError`
`500`	Internal server error. Contact support if this persists.	`InternalError`

Problems this endpoint can return

Status	Problem	When
`400`	Plan state does not allow a port-in	A port-in is requested for a user whose plan is not in one of the states a port-in accepts.
`409`	Number already with Telgea	A port-in is submitted for a number that is already served by Telgea.
`409`	Number in termination grace period	A port-in is submitted for a number whose plan ended recently.
`409`	Port-in already in progress	A port-in is submitted for a number while an earlier port-in for it has not finished.
`404`	User not found	A request names a user that your organization does not have.
`400`	Transfer date not offered	A port-in is validated or submitted with an executionDate outside the dates its market offers.
`403`	Business verification required	A plan or port-in is created in a country that requires business verification, before your organization has passed it.
`403`	Country not available to your organization	A plan is created for a country your organization has no offering in.
`409`	User already has a plan	A plan is created for a user whose current plan has not ended.

Response fields

200 CreatePortInResponse

Field Type Description

idrequired

string

UUID of the created port-in

c3d4e5f6-a7b8-9012-c345-678901234567

statusrequired

enum

CREATEDREJECTED

Status of the port-in. CREATED means accepted for processing; REJECTED means validation failed.

CREATED

msisdn

string

The phone number being ported

+4915112345678

numberId

string

UUID of the associated number resource

8238c1b9-c2c0-4455-9b03-4bd787052709

executionDate

string

Confirmed execution date

2027-03-01

errors array of PortInValidationError Validation errors when status is REJECTED

Show 3 child fields of errors

Field	Type	Description
`message`required	string	Validation error description `A PAC is 3 letters, then 6 digits (e.g. ABC12…`
`field`	string	The field that caused the validation error `authorizationCode`
`code`required	enum `REQUIREDFORMAT_INVALIDLENGTH_INVALIDNOT_ALLOWEDDATE_NOT_ALLOWEDCHECK_DIGIT_INVALIDWRONG_CUSTOMER_TYPE`	Why the value was refused, as a stable code to branch on. A code is never renamed or removed, but new ones can be added: show the `message` for a code you do not recognise. `FORMAT_INVALID`

POST/v1/port-ins

Request

curl -X POST "https://api.telgea.com/v1/port-ins" \
  -H "x-api-key: $TELGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
  "countryCode": "DE",
  "type": "personal",
  "msisdn": "+4915112345678",
  "executionDate": "2027-03-01",
  "fields": {
    "currentCarrier": "CONG",
    "authorizationCode": "1985-04-12",
    "ownerFirstName": "Erika",
    "ownerLastName": "Mustermann",
    "isUnlocked": true
  }
}'

Response

{
  "id": "c3d4e5f6-a7b8-9012-c345-678901234567",
  "status": "CREATED",
  "msisdn": "+4915112345678",
  "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709",
  "executionDate": "2027-03-01",
  "errors": []
}

Get port-in status

GET/v1/port-ins/{portInId}

Enterprise APIPartner API

Retrieves the current status and details of a port-in request. Use this endpoint to track the progress of a submitted port-in through its lifecycle.

Requires the permission port-ins:read on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Parameter	In	Type	Description
`portInId`required	path	string (uuid)	UUID of the port-in request. `c3d4e5f6-a7b8-9012-c345-678901234567`

Responses

Status	Meaning	Body
`200`	Successfully retrieved port-in details.	`GetPortInResponse`
`400`	Request failed schema validation, or was refused by a business rule	none
`401`	Missing or invalid API key in the X-API-Key header	`UnauthorizedError`
`403`	Insufficient permissions to read port-in data	`ForbiddenError`
`404`	Port-in not found. The specified ID does not match any existing port-in.	`NotFoundError`
`429`	The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.	`TooManyRequestsError`
`500`	Internal server error. Contact support if this persists.	`InternalError`

Problems this endpoint can return

Status	Problem	When
`404`	Port-in not found	A port-in is requested by an id that does not exist in your organization.

Response fields

200 GetPortInResponse

Field Type Description

idrequired

string

UUID of the port-in request.

c3d4e5f6-a7b8-9012-c345-678901234567

countryCoderequired

string

Market the number is being ported into.

DE

msisdnrequired

string

The number being ported, in E.164 format.

+4915112345678

executionDaterequired

string

The porting date, as YYYY-MM-DD.

2027-03-01

typerequired

string

Port-in type this request was submitted under, or null when the donor needed none.

personal

statusrequired

enum

PENDINGCREATEDSUBMITTEDACCEPTEDREJECTEDSUCCEEDEDFAILED

Current status of the port-in

CREATED

numberIdrequired

string

UUID of the number this port-in creates. Use it to read the line once porting succeeds.

8238c1b9-c2c0-4455-9b03-4bd787052709

failurerequired PortInFailure Why a REJECTED or FAILED port-in ended that way: values you can branch on, and a text you can show your customer. Null in every other status.

Show 3 child fields of failure

Field	Type	Description
`reason`required	enum `WRONG_CUSTOMER_TYPECONTRACT_LOCKEDNUMBER_OWNERSHIP_MISMATCHNUMBER_ALREADY_PORTINGAUTHORIZATION_CODE_INVALIDPORTING_DATE_UNAVAILABLEFIELD_MISSINGFIELD_INVALIDFIELD_MISMATCHREJECTED_BY_DONORCANCELLED`	Why the port-in ended this way, or null when we could not classify it. `AUTHORIZATION_CODE_INVALID`
`field`required	string	What the donor objected to, when it identified something. Either a key you sent in `fields` (e.g. `authorizationCode`) or a top-level property of the port-in (`msisdn`, `type`, `executionDate`). `authorizationCode`
`text`required	string	What happened and what to do next, in English, for showing to your customer. The wording may change at any time: branch on `reason`, never on this. `Your authorization code was refused or has ex…`

createdAtrequired

string

When the port-in was submitted, ISO 8601.

2027-02-22T10:00:00Z

updatedAtrequired

string

When the port-in last changed status, ISO 8601.

2027-02-22T10:00:00Z

GET/v1/port-ins/{portInId}

Request

curl -X GET "https://api.telgea.com/v1/port-ins/c3d4e5f6-a7b8-9012-c345-678901234567" \
  -H "x-api-key: $TELGEA_API_KEY"

Response

{
  "id": "c3d4e5f6-a7b8-9012-c345-678901234567",
  "countryCode": "DE",
  "msisdn": "+4915112345678",
  "executionDate": "2027-03-01",
  "type": "personal",
  "status": "SUBMITTED",
  "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709",
  "failure": null,
  "createdAt": "2027-02-22T10:00:00Z",
  "updatedAt": "2027-02-22T10:00:00Z"
}

Discard a failed port-in

POST/v1/port-ins/{portInId}/discard

Enterprise APIPartner API

Gives up on a port-in that ended in REJECTED or FAILED, when you will not submit it again. The number leaves the plan and stays with the losing carrier. Unless the user has another number, the plan reads INACTIVE, so you can create a user plan with a new number or port in a different one.

The port-in stays readable at its own id and keeps its REJECTED or FAILED status. A discard shows as the number leaving the plan it was being ported onto, and the number's port-ins also leave GET /v1/port-ins/number/{numberId}.

Only a port-in that ended in REJECTED or FAILED can be discarded, and not while a newer port-in for the same number is in flight or once one has succeeded. Either is refused with 400 BAD_REQUEST. Discarding a port-in that is already discarded succeeds and changes nothing.

Requires the permission port-ins:discard on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Parameter	In	Type	Description
`portInId`required	path	string (uuid)	UUID of the port-in request. `c3d4e5f6-a7b8-9012-c345-678901234567`
`idempotency-key`	header	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. `0b7e4f1c-6a2d-4c9e-8f35-d1a7b2c93e60`

Responses

Status	Meaning	Body
`204`	Port-in discarded. No content returned.	none
`400`	Request failed schema validation, or the port-in cannot be discarded: it has not failed, or a newer port-in has taken over its number	none
`401`	Missing or invalid API key in the X-API-Key header	`UnauthorizedError`
`403`	Insufficient permissions to discard port-ins	`ForbiddenError`
`404`	Port-in not found. The specified ID does not match any existing port-in.	`NotFoundError`
`429`	The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.	`TooManyRequestsError`
`500`	Internal server error. Contact support if this persists.	`InternalError`

Problems this endpoint can return

Status	Problem	When
`404`	Port-in not found	A port-in is requested by an id that does not exist in your organization.
`400`	Port-in cannot be discarded	A port-in is discarded before it was rejected or failed, or after a newer port-in for the same number took the number over.

POST/v1/port-ins/{portInId}/discard

Request

curl -X POST "https://api.telgea.com/v1/port-ins/c3d4e5f6-a7b8-9012-c345-678901234567/discard" \
  -H "x-api-key: $TELGEA_API_KEY"

Response

{
  "type": "https://developer.telgea.com/errors/http/BAD_REQUEST",
  "title": "Bad request",
  "status": 400,
  "detail": "This request was refused, and no more specific code describes why.",
  "code": "BAD_REQUEST",
  "requestId": "req_123"
}

List port-ins for a number

GET/v1/port-ins/number/{numberId}

Enterprise APIPartner API

Retrieves a paginated list of all port-in requests associated with a specific number. Use this to see the full porting history for a phone number, including completed, failed, and in-progress port-ins.

Requires the permission port-ins:read on the key.

Try it in the playground → Calls run against your live organization; there is no sandbox.

Parameters

Parameter	In	Type	Description
`numberId`required	path	string (uuid)	UUID of the number resource `8238c1b9-c2c0-4455-9b03-4bd787052709`
`page`	query	integer	Page to return, starting at 1. `1`
`pageSize`	query	integer	Items per page, at most 100. Defaults to 50. `50`

Responses

Status	Meaning	Body
`200`	Successfully retrieved port-ins for the specified number.	`ListPortInsResponse`
`400`	Request failed schema validation, or was refused by a business rule	none
`401`	Missing or invalid API key in the X-API-Key header	`UnauthorizedError`
`403`	Insufficient permissions to read port-in data	`ForbiddenError`
`429`	The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.	`TooManyRequestsError`
`500`	Internal server error. Contact support if this persists.	`InternalError`

Problems this endpoint can return

This endpoint returns no domain-specific problems.

Response fields

200 ListPortInsResponse

Field Type Description

pagerequired

integer

The page these items came from.

1

pageSizerequired

integer

Items per page, as requested.

50

itemsCountrequired

integer

Total items across all pages. Divide by pageSize to get the number of pages.

142

itemsrequired array of GetPortInResponse Port-ins on this page, newest first.

Show 10 child fields of items

Field Type Description

idrequired

string

UUID of the port-in request.

c3d4e5f6-a7b8-9012-c345-678901234567

countryCoderequired

string

Market the number is being ported into.

DE

msisdnrequired

string

The number being ported, in E.164 format.

+4915112345678

executionDaterequired

string

The porting date, as YYYY-MM-DD.

2027-03-01

typerequired

string

Port-in type this request was submitted under, or null when the donor needed none.

personal

statusrequired

enum

PENDINGCREATEDSUBMITTEDACCEPTEDREJECTEDSUCCEEDEDFAILED

Current status of the port-in

CREATED

numberIdrequired

string

UUID of the number this port-in creates. Use it to read the line once porting succeeds.

8238c1b9-c2c0-4455-9b03-4bd787052709

failurerequired PortInFailure Why a REJECTED or FAILED port-in ended that way: values you can branch on, and a text you can show your customer. Null in every other status.

Show 3 child fields of failure

Field	Type	Description
`reason`required	enum `WRONG_CUSTOMER_TYPECONTRACT_LOCKEDNUMBER_OWNERSHIP_MISMATCHNUMBER_ALREADY_PORTINGAUTHORIZATION_CODE_INVALIDPORTING_DATE_UNAVAILABLEFIELD_MISSINGFIELD_INVALIDFIELD_MISMATCHREJECTED_BY_DONORCANCELLED`	Why the port-in ended this way, or null when we could not classify it. `AUTHORIZATION_CODE_INVALID`
`field`required	string	What the donor objected to, when it identified something. Either a key you sent in `fields` (e.g. `authorizationCode`) or a top-level property of the port-in (`msisdn`, `type`, `executionDate`). `authorizationCode`
`text`required	string	What happened and what to do next, in English, for showing to your customer. The wording may change at any time: branch on `reason`, never on this. `Your authorization code was refused or has ex…`

createdAtrequired

string

When the port-in was submitted, ISO 8601.

2027-02-22T10:00:00Z

updatedAtrequired

string

When the port-in last changed status, ISO 8601.

2027-02-22T10:00:00Z

GET/v1/port-ins/number/{numberId}

Request

curl -X GET "https://api.telgea.com/v1/port-ins/number/8238c1b9-c2c0-4455-9b03-4bd787052709" \
  -H "x-api-key: $TELGEA_API_KEY"

Response

{
  "page": 1,
  "pageSize": 50,
  "itemsCount": 2,
  "items": [
    {
      "id": "c3d4e5f6-a7b8-9012-c345-678901234567",
      "countryCode": "DE",
      "msisdn": "+4915112345678",
      "executionDate": "2027-03-01",
      "type": "personal",
      "status": "SUBMITTED",
      "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709",
      "failure": null,
      "createdAt": "2027-02-22T10:00:00Z",
      "updatedAt": "2027-02-22T10:00:00Z"
    },
    {
      "id": "b1d2c3e4-f5a6-7890-b123-456789012345",
      "countryCode": "DE",
      "msisdn": "+4915112345678",
      "executionDate": "2027-03-01",
      "type": "personal",
      "status": "FAILED",
      "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709",
      "failure": {
        "reason": "CONTRACT_LOCKED",
        "field": null,
        "text": "The current contract doesn't allow the transfer yet. Ask your current carrier to release the number for porting."
      },
      "createdAt": "2027-02-22T10:00:00Z",
      "updatedAt": "2027-02-22T10:00:00Z"
    }
  ]
}

GET/v1/port-ins/fields/{countryCode}

Request

curl -X GET "https://api.telgea.com/v1/port-ins/fields/DE" \
  -H "x-api-key: $TELGEA_API_KEY"

Response

{
  "personal": {
    "label": "Personal",
    "typeLabel": {
      "id": "port-in.de.typeLabel",
      "en": "Who is the number registered to?"
    },
    "explanation": {
      "id": "port-in.de.personal.explanation",
      "en": "The contract is in a person's name."
    },
    "fields": [
      {
        "name": "currentCarrier",
        "label": "Current carrier",
        "description": "Your current mobile carrier",
        "type": "select",
        "help": {
          "id": "port-in.de.currentCarrier.help",
          "en": "The brand on your bill or SIM."
        },
        "options": [
          {
            "label": "Congstar",
            "value": "CONG"
          },
          {
            "label": "O2 Deutschland GmbH",
            "value": "O2DE"
          },
          {
            "label": "Vodafone GmbH",
            "value": "VODA"
          }
        ]
      },
      {
        "name": "authorizationCode",
        "label": "Date of birth",
        "description": "Owner date of birth (YYYY-MM-DD)",
        "type": "date",
        "help": {
          "id": "port-in.de.personal.authorizationCode.help",
          "en": "Date of birth of the contract holder."
        }
      },
      {
        "name": "ownerFirstName",
        "label": "First name",
        "description": "Account owner first name",
        "type": "text",
        "minLength": 1,
        "help": {
          "id": "port-in.de.asOnTheContract",
          "en": "As on the contract."
        }
      },
      {
        "name": "ownerLastName",
        "label": "Last name",
        "description": "Account owner last name",
        "type": "text",
        "minLength": 1,
        "help": {
          "id": "port-in.de.asOnTheContract",
          "en": "As on the contract."
        }
      },
      {
        "name": "isUnlocked",
        "label": "Number released for porting",
        "description": "Please confirm that the current carrier has been contacted and unlocked the number for port-out",
        "type": "checkbox",
        "help": {
          "id": "port-in.de.isUnlocked.help",
          "en": "Ask your current carrier to release the number before you start."
        },
        "requiredValue": true
      }
    ],
    "executionDate": {
      "name": "executionDate",
      "label": "Transfer date",
      "type": "date",
      "help": {
        "id": "port-in.executionDate.help.a-weekday-from-7-days-to-14-days-from-today",
        "en": "A weekday, from 7 days to 14 days from today."
      },
      "errorMessage": "That date isn't possible. Choose a weekday from 7 days to 14 days from today.",
      "minDate": "2027-03-01",
      "maxDate": "2027-03-08",
      "dates": [
        "2027-03-01",
        "2027-03-02",
        "2027-03-03",
        "2027-03-04",
        "2027-03-05",
        "2027-03-08"
      ],
      "validUntil": "2027-02-22T23:00:00.000Z"
    },
    "timing": {
      "submitted": "beforeTheDate",
      "finalDateSetBy": "oldCarrier",
      "dateMayMove": true,
      "cancel": "beforeSubmission",
      "reschedule": "beforeSubmission"
    }
  },
  "business": {
    "label": "Business",
    "typeLabel": {
      "id": "port-in.de.typeLabel",
      "en": "Who is the number registered to?"
    },
    "explanation": {
      "id": "port-in.de.business.explanation",
      "en": "The contract is in a company's name."
    },
    "fields": [
      {
        "name": "currentCarrier",
        "label": "Current carrier",
        "description": "Your current mobile carrier",
        "type": "select",
        "help": {
          "id": "port-in.de.currentCarrier.help",
          "en": "The brand on your bill or SIM."
        },
        "options": [
          {
            "label": "Congstar",
            "value": "CONG"
          },
          {
            "label": "O2 Deutschland GmbH",
            "value": "O2DE"
          },
          {
            "label": "Vodafone GmbH",
            "value": "VODA"
          }
        ]
      },
      {
        "name": "authorizationCode",
        "label": "Customer number",
        "description": "Your customer number with the current carrier. Can be found on a recent bill from them or by contacting the carrier directly.",
        "type": "text",
        "minLength": 1,
        "help": {
          "id": "port-in.de.business.authorizationCode.help",
          "en": "On the current carrier's invoice."
        },
        "howToGet": {
          "id": "port-in.de.business.authorizationCode.howToGet",
          "en": "On the current carrier's invoice."
        }
      },
      {
        "name": "companyName",
        "label": "Company name",
        "description": "Registered company name of company that owns the number",
        "type": "text",
        "minLength": 1,
        "help": {
          "id": "port-in.de.asOnTheContract",
          "en": "As on the contract."
        }
      },
      {
        "name": "isUnlocked",
        "label": "Number released for porting",
        "description": "Please confirm that the current carrier has been contacted and unlocked the number for port-out",
        "type": "checkbox",
        "help": {
          "id": "port-in.de.isUnlocked.help",
          "en": "Ask your current carrier to release the number before you start."
        },
        "requiredValue": true
      }
    ],
    "executionDate": {
      "name": "executionDate",
      "label": "Transfer date",
      "type": "date",
      "help": {
        "id": "port-in.executionDate.help.a-weekday-from-7-days-to-14-days-from-today",
        "en": "A weekday, from 7 days to 14 days from today."
      },
      "errorMessage": "That date isn't possible. Choose a weekday from 7 days to 14 days from today.",
      "minDate": "2027-03-01",
      "maxDate": "2027-03-08",
      "dates": [
        "2027-03-01",
        "2027-03-02",
        "2027-03-03",
        "2027-03-04",
        "2027-03-05",
        "2027-03-08"
      ],
      "validUntil": "2027-02-22T23:00:00.000Z"
    },
    "timing": {
      "submitted": "beforeTheDate",
      "finalDateSetBy": "oldCarrier",
      "dateMayMove": true,
      "cancel": "beforeSubmission",
      "reschedule": "beforeSubmission"
    }
  }
}

Need the raw schema? OpenAPI JSON