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.
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
status | Meaning | Webhook |
|---|---|---|
requested | Accepted by Firsty, being submitted to the porting provider. | portin.submitted on each submission |
approved | The donor accepted. scheduledAt is the earliest moment the number moves, once known. | portin.approved, then portin.rescheduled on each move |
cancelling | You asked to cancel; the provider hasn't confirmed yet. | None |
completed | The number is on this eSIM. | portin.completed |
rejected | The donor said no. See reason. | portin.rejected |
failed | The port failed. See reason. | portin.failed |
cancelled | The 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.
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.
| Belgium | Netherlands | |
|---|---|---|
msisdn | 324 + 8 digits | 316 + 8 digits |
donorContractType | prepaid, postpaid, business | prepaid, postpaid |
Proof for prepaid | donorIccid and/or donorSimNumber | donorAccountNumber optional; donorContractAction refused |
Proof for postpaid | Any of donorIccid, donorSimNumber, donorAccountNumber | donorAccountNumber and donorContractAction required |
Proof for business | donorAccountNumber only | n/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_expiryends it where it can end. The donor may refuse the port while a commitment period runs.terminate_earlyends it even during a commitment period, which may cost the customer an early-termination fee at the donor.keep_with_new_numberkeeps 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 to | Call | Allowed when |
|---|---|---|
| Retry with fixed details | Create port-in | The latest request is rejected, failed or cancelled |
| Stop a pending port | Cancel port-in | The request is requested or approved |
| Move the porting moment | Reschedule port-in | The request is approved, on a Dutch number |
| Keep the temporary number | Abandon port-in | The 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.
code | Meaning |
|---|---|
msisdn_sim_mismatch | The donor SIM doesn't belong to the number. |
msisdn_account_mismatch | The donor account number doesn't belong to the number. |
donor_contract_type_mismatch | donorContractType differs from the contract at the donor. |
number_not_active | The number isn't active at the donor. |
number_not_portable | The donor or the porting provider says the number can't be ported. |
porting_window_unavailable | The port can't happen in the porting window, for example during a contract term. |
number_porting_in_progress | Another porting of the number is already under way. |
provider_failure | Any 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.
status | Meaning | Webhook |
|---|---|---|
requested | The new provider asked for the number. | portout.requested |
approved | The number leaves at the agreed moment. It can still be rejected. | portout.approved |
rejected | The number stays. See answer.reason. | portout.rejected |
cancelled | The new provider cancelled. The number stays. | portout.cancelled |
failed | The port-out couldn't be carried out. The number stays. | portout.failed |
completed | The 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 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.
status | Meaning |
|---|---|
processing | On its way to the registry, or awaiting its verdict. |
completed | The registry accepted it. |
error | It 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.
Get number registration reads it back; the eSIM details response embeds the same object.