# Port-in lifecycle

How a number moves from your request to living on Telgea, where it can fail, and what to do in each state.

> Partner API · https://developer.telgea.com/docs/partner/concepts/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}`](https://developer.telgea.com/docs/partner/api/port-ins#get-port-in-status) is the source of truth.

## States [#states]

## What to build [#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}`](https://developer.telgea.com/docs/partner/api/port-ins#get-port-in-fields-for-a-country), 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`](https://developer.telgea.com/docs/partner/api/port-ins#discard-a-failed-port-in) 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 [#related]

* [Port a number in](https://developer.telgea.com/docs/partner/guides/port-in): the step-by-step guide, with every failure code and reason.
* [Number and eSIM lifecycle](https://developer.telgea.com/docs/partner/concepts/number-lifecycle): what happens to the number during and after the port.