---
title: "List port-ins for a number"
method: GET
path: "/v1/port-ins/number/{numberId}"
tags: ["Port-Ins"]
---

# List port-ins for a number

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

## Request

- Base URL: `https://api.telgea.com`
- URL: `https://api.telgea.com/v1/port-ins/number/{numberId}`
- Auth: API key in header `x-api-key`

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.

## Path parameters

- `numberId` string, uuid, required: UUID of the number resource

## Query parameters

- `page` integer: Page to return, starting at 1.
- `pageSize` integer: Items per page, at most 100. Defaults to 50.

## Response `200`

Successfully retrieved port-ins for the specified number.

- ListPortInsResponse
  - `page` integer, required: The page these items came from.
  - `pageSize` integer, required: Items per page, as requested.
  - `itemsCount` integer, required: Total items across all pages. Divide by pageSize to get the number of pages.
  - `items` GetPortInResponse[], required: Port-ins on this page, newest first.
    - `id` string, required: UUID of the port-in request.
    - `countryCode` string, required: Market the number is being ported into.
    - `msisdn` string, required: The number being ported, in E.164 format.
    - `executionDate` string, required: The porting date, as YYYY-MM-DD.
    - `type` string, nullable, required: Port-in type this request was submitted under, or null when the donor needed none.
    - `status` 'PENDING' | 'CREATED' | 'SUBMITTED' | 'ACCEPTED' | 'REJECTED' | 'SUCCEEDED' | 'FAILED', required: Current status of the port-in
    - `numberId` string, required: UUID of the number this port-in creates. Use it to read the line once porting succeeds.
    - `failure` PortInFailure, nullable, required: 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.
      - `reason` 'WRONG_CUSTOMER_TYPE' | 'CONTRACT_LOCKED' | 'NUMBER_OWNERSHIP_MISMATCH' | 'NUMBER_ALREADY_PORTING' | 'AUTHORIZATION_CODE_INVALID' | 'PORTING_DATE_UNAVAILABLE' | 'FIELD_MISSING' | 'FIELD_INVALID' | 'FIELD_MISMATCH' | 'REJECTED_BY_DONOR' | 'CANCELLED' | 'null', nullable, required: Why the port-in ended this way, or null when we could not classify it.
      - `field` string, nullable, required: 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`).
      - `text` string, required: 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.
    - `createdAt` string, required: When the port-in was submitted, ISO 8601.
    - `updatedAt` string, required: When the port-in last changed status, ISO 8601.

## Other responses

- `400`: Request failed schema validation, or was refused by a business rule
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: Insufficient permissions to read port-in data
- `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)