Port-in lifecycle

Porting is the one flow where the outcome depends on a third party: the losing carrier. A port-in therefore has more states than any other resource, and two of them are failures you must handle. The status field on GET /v1/port-ins/{portInId} is the source of truth.

States

Status	Meaning	Your action
PENDING	Part of the published enum, but not returned today.	None.
CREATED	Accepted by POST /v1/port-ins. Data that fails validation is refused in that response instead, and no port-in is created.	Nothing; submission to the losing carrier follows automatically.
SUBMITTED	Sent to the losing carrier for processing.	Wait for the losing carrier to accept or refuse it; poll gently.
ACCEPTED	The losing carrier accepted the port and confirmed the execution date, which may differ from the one you requested.	Tell the customer the date; keep the old SIM active until then.
SUCCEEDED	The number is now on Telgea and attached to the user plan, which goes ACTIVE.	Deliver the eSIM if not already installed.
REJECTED	Refused by the losing carrier or by provider validation: at submission, after it, or on the porting date.	Read `failure`, correct the data and submit a new port-in for the same number, or discard this one to give up on the number. Either way it stays readable.
FAILED	Failed at submission, during the acceptance check or on the porting date, or was cancelled.	Read `failure`; submit a new port-in, or discard this one to give up on the number. Contact support only if the losing carrier must be involved.

What to build

• Pick the date from the list. Offer only the dates in the type's executionDate.dates from GET /v1/port-ins/fields/{countryCode}, and fetch them again after executionDate.validUntil. A date outside the list is refused before the port-in is created.
• Poll the port-in. GET /v1/port-ins/{portInId} returns its current status. The losing carrier can take days to answer, so poll gently rather than in a tight loop.
• Read failure. A port-in that ended REJECTED or FAILED carries a failure object with the reason and, where the carrier named one, the field it objected to.
• Retry with a new port-in. Correct the data and POST /v1/port-ins again for the same number. The plan the number is arriving on stays PORTING in between, and the earlier port-in stays readable.
• Or discard it. If you won't try again, POST /v1/port-ins/{portInId}/discard discards the port-in and the number leaves the plan it was arriving on. The port-in stays readable at its own id and keeps its status.
• Keep the old SIM working until SUCCEEDED. The customer loses service on the old carrier only when the port completes.

There is no API for cancelling a port-in.

Related

• Port a number in: the step-by-step guide, with every failure code and reason.
• Number and eSIM lifecycle: what happens to the number during and after the port.