Firsty

Search...

Search...

Core concepts

Number porting

Port-ins, port-outs and number registration, with the webhooks for each step.

A port-in brings a customer's existing number to a new Firsty eSIM. A port-out is the reverse: the customer's new provider takes the number away. Number registration records the subscriber against the number in its country's registry, where the regulator requires it.

Ordering with a port-in

Port-in intent is part of the order: add a portIn block to the eSIM order. Add numberRegistration alongside it when the number's market requires one; it then registers the ported number, not the temporary one.

POST /esims
requests.post(
    "https://connect.test.firsty.app/api/v3/esims",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "portIn": {
        "msisdn": "32470123456",
        "details": {
          "donorContractType": "postpaid",
          "donorIccid": "8932031234567890128"
        }
      },
      "numberRegistration": {
        "countryCode": "BE",
        "languageCode": "nl",
        "firstName": "Jane",
        "lastName": "Doe",
        "address": {
          "streetName": "Grote Markt",
          "houseNumber": "1",
          "postalCode": "1000",
          "city": "Brussel"
        }
      }
    }
)

The response carries a portIn object with its portInRequestReference. Have the customer install the eSIM on their device straight away.

Meanwhile the eSIM stays preactive, installable but without service, until the port completes or you abandon it.

Request status

statusMeaningWebhook
requestedAccepted by Firsty, being submitted to the porting provider.portin.submitted on each submission
approvedThe donor accepted. scheduledAt is the earliest moment the number moves, once known.portin.approved, then portin.rescheduled on each move
cancellingYou asked to cancel; the provider hasn't confirmed yet.None
completedThe number is on this eSIM.portin.completed
rejectedThe donor said no. See reason.portin.rejected
failedThe port failed. See reason.portin.failed
cancelledThe cancellation is confirmed.portin.cancelled

status is an extensible enum: handle a value you don't know. A port-in can be submitted more than once under the same portInRequestReference, and each submission sends portin.submitted again.

GET /profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}
requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-ins/{portInRequestReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

List port-ins returns the eSIM's request history, newest first. Each corrected request is its own entry.

Donor details

details takes the shape of the eSIM variant's country. Unknown fields are rejected. msisdn is the number in international format without a leading +: the country code, not the national 0.

BelgiumNetherlands
msisdn324 + 8 digits316 + 8 digits
donorContractTypeprepaid, postpaid, businessprepaid, postpaid
Proof for prepaiddonorIccid and/or donorSimNumberdonorAccountNumber optional; donorContractAction refused
Proof for postpaidAny of donorIccid, donorSimNumber, donorAccountNumberdonorAccountNumber and donorContractAction required
Proof for businessdonorAccountNumber onlyn/a

In Belgium, prefer donorIccid: most donor operators accept it. Send donorSimNumber, the number printed on the donor SIM, only when the ICCID isn't available.

In the Netherlands, donorContractAction says what happens to the customer's contract at the donor:

  • terminate_at_expiry ends it where it can end. The donor may refuse the port while a commitment period runs.
  • terminate_early ends it even during a commitment period, which may cost the customer an early-termination fee at the donor.
  • keep_with_new_number keeps the contract running at the donor under a new number.

A Dutch port-in without donorAccountNumber needs the customer to confirm it with a code sent by SMS to the number being ported. It stays requested until they do. An unconfirmed code expires after 24 hours and the port-in is rejected.

The create port-in reference has the field formats.

When a port-in doesn't go through

After rejected, failed or cancelled, an eSIM that waits for its port stays preactive. Nothing releases it on its own: you either correct the request or abandon porting.

You want toCallAllowed when
Retry with fixed detailsCreate port-inThe latest request is rejected, failed or cancelled
Stop a pending portCancel port-inThe request is requested or approved
Move the porting momentReschedule port-inThe request is approved, on a Dutch number
Keep the temporary numberAbandon port-inThe request is the latest and rejected, failed or cancelled

Correct

A corrected request supersedes the previous one, which is marked abandoned, so only the newest request is ever live. The eSIM keeps waiting. A numberRegistration from the original order carries over and follows the corrected number; this call takes no registration of its own.

It returns 409 while a request is still in progress (port_in_pending), after the number has ported, or after porting was abandoned (invalid_state_transition).

Cancel

Cancelling is asynchronous. The request moves to cancelling, then to cancelled once the provider confirms, or straight to cancelled if the provider had already cancelled it. A completed port can't be cancelled (409), and the network can refuse (422 port_in_cancel_refused). Afterwards, correct or abandon.

Reschedule

Without a move, the number moves at the earliest moment the donor agreed to, the scheduledAt of portin.approved. From that moment it stops working on the customer's old SIM. Move it later when the customer wants to switch when their donor contract ends, when the eSIM isn't installed yet, or when they prefer another day.

The moment must fall Monday to Friday, 08:30 to 17:30 Dutch time, and between the earliest moment and 90 days after it. Anything outside is refused. Public holidays are outside the window too, but a moment on one is not refused. A network that doesn't move port-ins answers 422 port_in_reschedule_not_supported.

Abandon

Abandoning is irreversible. The temporary number becomes permanent, and every later port-in for the eSIM is refused. The eSIM stops waiting for the port; it goes live once nothing else holds it back, such as its install or your activate call. esim.lifecycle.activated tells you when. A registration captured for the ported number moves to the temporary one.

Reason codes

reason.code is the same for every porting provider. Branch on the code; reason.message is free text for support, not for parsing. The list is open: new codes may be added.

codeMeaning
msisdn_sim_mismatchThe donor SIM doesn't belong to the number.
msisdn_account_mismatchThe donor account number doesn't belong to the number.
donor_contract_type_mismatchdonorContractType differs from the contract at the donor.
number_not_activeThe number isn't active at the donor.
number_not_portableThe donor or the porting provider says the number can't be ported.
porting_window_unavailableThe port can't happen in the porting window, for example during a contract term.
number_porting_in_progressAnother porting of the number is already under way.
provider_failureAny cause without a more specific code.

Port-outs

A port-out starts at the customer's new provider, never through this API. You read it, you don't create it.

statusMeaningWebhook
requestedThe new provider asked for the number.portout.requested
approvedThe number leaves at the agreed moment. It can still be rejected.portout.approved
rejectedThe number stays. See answer.reason.portout.rejected
cancelledThe new provider cancelled. The number stays.portout.cancelled
failedThe port-out couldn't be carried out. The number stays.portout.failed
completedThe number left. The eSIM is terminated.portout.completed

completed is the only final status. A rejected, cancelled or failed port-out still completes if the number leaves after all. A completed port-out terminates the eSIM, and esim.lifecycle.terminated follows.

details is keyed by country; ignore a country you don't know. The only one so far is Belgium (BE). The porting provider answers a Belgian port-out by itself, so answer.answeredBy is provider, and a Belgian rejection carries reason.code other.

GET /profiles/{profileReference}/esims/{esimReference}/port-outs
requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/port-outs",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

Get port-out returns one port-out with its answer. Every portout.* webhook carries the port-out in the same shape.

Number registration

A registration always describes the number the eSIM is on or is porting to. Send it with the order as numberRegistration, or later with create or replace. It applies only to a local eSIM whose number's country has a registry Firsty submits to. For any other eSIM, both endpoints answer 422.

statusMeaning
processingOn its way to the registry, or awaiting its verdict.
completedThe registry accepted it.
errorIt couldn't be sent, or the registry rejected it. See reason.

A registration is submitted once the number is live. processing is therefore normal straight after a write, and a ported number stays there until its port-in completes. The outcome arrives as number-registration.completed or number-registration.rejected, which carries the registry's own code and message.

To fix a rejected registration, or to update a subscriber who moved or changed name, write it again. The write replaces the record in full: a field you leave out is cleared. A registration already sent and awaiting the registry can't be changed (409). Repeat the write once the outcome arrives, under a new X-Idempotency-Key; reusing the old key replays its 409.

POST /profiles/{profileReference}/esims/{esimReference}/number-registration
requests.post(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/number-registration",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "countryCode": "BE",
      "languageCode": "nl",
      "address": {
        "streetName": "Grote Markt",
        "houseNumber": "1",
        "unit": "A",
        "postalCode": "1000",
        "city": "Brussel"
      },
      "firstName": "Jane",
      "lastName": "Doe"
    }
)

Get number registration reads it back; the eSIM details response embeds the same object.