Firsty

Search...

Search...

PortingExperimental

Answer a port-out

Approves or rejects a port-out that asks for an answer: one whose details.answerBefore is set, which portout.requested announces. The answer is due before that moment. The answer is sent on to the network once, and the response status says what became of it. An answer that was taken moves the port-out, and portout.approved or portout.rejected follows. A port-out still unanswered shortly before the answer is due gets one from Firsty: a rejection when the request carries a customer number nobody checked, so the customer confirms by SMS instead, and an approval otherwise.

post/profiles/{profileReference}/esims/{esimReference}/port-outs/{portOutRequestReference}/answer

Authorization

Authorization: Bearer {token} — an OAuth2 access token from the client-credentials flow. How authentication works

Path parameters

profileReferencestringrequired

Profile reference

esimReferencestringrequired

eSIM reference

portOutRequestReferencestringrequired

Port-out request reference

Headers

X-Idempotency-Keystring

Optional idempotency key for requests that change state. If provided, duplicate requests with the same key within 48 hours will return the cached original response without duplicating side effects.

Behavior:

  • Same key + same method, path and request body → returns cached response (prevents duplicate operations)
  • Same key + different method, path or request body → returns 422 error
  • Same key + in-flight request → returns 423 error
  • Keys are held for at least 48 hours; use a fresh key for every new request

Request Body Matching: Request bodies are compared by their JSON content. Object key order, including in nested objects, and whitespace do not affect matching. This means:

  • {"a":1,"b":2} and {"b":2,"a":1} are treated as identical ✓
  • Whitespace differences are ignored ✓
  • The method and the full path, query included, must match as well; headers are not compared

Best Practices:

  • Use UUIDs or client-generated unique strings
  • Store keys on your side to support retries
  • Don't reuse keys across different operations

Request body

application/json · required

approvedobject
Show properties
decisionstringrequired
firstPossibleAtstring · date-time

The earliest moment the number may leave, in the porting window (Monday to Friday, 08:30 to 17:30 Dutch time) and not in the past. Without it, 08:30 on the next business day, or on the first business day 3 days out for terminate_early.

rejectedone of customer_number_mismatch | contract_commitment | not_portable | other
Show properties
customer_number_mismatchobject

The customerId the recipient sent is not this customer's.

Show properties
decisionstringrequired
reasonstringrequired
contract_commitmentobject

The customer's contract has more than 4 months left to run.

Show properties
decisionstringrequired
reasonstringrequired
firstPossibleAtstring · date-timerequired

When the customer can leave; at least 120 days out

not_portableobject

The number cannot be ported.

Show properties
decisionstringrequired
reasonstringrequired
otherobject
Show properties
decisionstringrequired
reasonstringrequired
notestringrequired

Why, for the recipient

Responses

200The answer was taken; the port-out carries it and its new statusapplication/json
Show response body
dataobjectoptional
Show properties
portOutRequestReferencestring

Port-out request reference

profileReferencestring
esimReferencestring
msisdnstring

The number leaving, in international format (E.164 without a leading +)

statusstring

Extensible enum.

  • requested: The recipient asked for the number; no answer yet
  • approved: The port-out was approved; the number leaves at the agreed moment. It can still be rejected
  • rejected: The port-out was rejected (see answer.reason); the number stays
  • cancelled: The recipient cancelled; the number stays
  • completed: The number left for the recipient. The only final status: a rejected, cancelled or failed port-out completes when the number left after all
  • failed: The port-out could not be carried out; the number stays
Examplesrequestedapprovedrejectedcancelledcompletedfailed
answerone of approved | rejected | null

The answer to the port-out; null until it has one

Show properties
approvedobjectoptional
Show properties
decisionstring
answeredBystring

Extensible enum. Who answered: client, firsty (Firsty, when you did not answer), or provider (the network answers by itself).

Examplesclientfirstyprovider
answeredAtstring · date-time
rejectedobjectoptional
Show properties
decisionstring
reasonobject

Why the port-out was rejected

Show properties
codestring

Extensible enum. The cause of the rejection, the same for every market.

Examplesnot_portablecustomer_number_mismatchcustomer_number_unverifiedcontract_commitmentsim_number_mismatchother
messagestring

The cause in a sentence, for a person; free-form, not intended to be parsed

answeredBystring

Extensible enum. Who answered: client, firsty (Firsty, when you did not answer), or provider (the network answers by itself).

Examplesclientfirstyprovider
answeredAtstring · date-time
detailsone of BE | NL

Extensible by country: the market's own fields. Ignore a country you do not know.

Show properties
BEobjectoptional

A Belgian port-out. The network answers it and carries it out by itself.

Show properties
countrystring
NLobjectoptional

A Dutch port-out. Answer it with POST .../port-outs/{portOutRequestReference}/answer before answerBefore; a port-out still unanswered shortly before gets a default answer from Firsty.

Show properties
countrystring
customerIdstring | null

The customer number the recipient sent, to check against the customer's; null when it sent none and the customer confirmed the request by SMS instead

contractActionstring

Extensible enum. What the recipient asked for the customer's contract here: terminate_at_expiry ends it where it can end, terminate_early ends it even during a commitment, keep_with_new_number keeps it running on a new number.

Examplesterminate_at_expiryterminate_earlykeep_with_new_number
notestring | null

The recipient's note; null when it sent none

answerBeforestring · date-time

When the answer is due

firstPossibleAtstring | null · date-time

The earliest moment the number can leave, once answered; null until then

createdAtstring · date-time
updatedAtstring · date-time
completedAtstring | null · date-time

When the number left; null until it has

cancelledAtstring | null · date-time

When the recipient cancelled; null unless it did

202The answer was sent, but it is not confirmed yet that it was taken; the port-out is still `requested`. Do not send it again; `portout.approved` or `portout.rejected` follows once it is confirmedapplication/json
Show response body
dataobjectoptional
Show properties
portOutRequestReferencestring

Port-out request reference

profileReferencestring
esimReferencestring
msisdnstring

The number leaving, in international format (E.164 without a leading +)

statusstring

Extensible enum.

  • requested: The recipient asked for the number; no answer yet
  • approved: The port-out was approved; the number leaves at the agreed moment. It can still be rejected
  • rejected: The port-out was rejected (see answer.reason); the number stays
  • cancelled: The recipient cancelled; the number stays
  • completed: The number left for the recipient. The only final status: a rejected, cancelled or failed port-out completes when the number left after all
  • failed: The port-out could not be carried out; the number stays
Examplesrequestedapprovedrejectedcancelledcompletedfailed
answerone of approved | rejected | null

The answer to the port-out; null until it has one

Show properties
approvedobjectoptional
Show properties
decisionstring
answeredBystring

Extensible enum. Who answered: client, firsty (Firsty, when you did not answer), or provider (the network answers by itself).

Examplesclientfirstyprovider
answeredAtstring · date-time
rejectedobjectoptional
Show properties
decisionstring
reasonobject

Why the port-out was rejected

Show properties
codestring

Extensible enum. The cause of the rejection, the same for every market.

Examplesnot_portablecustomer_number_mismatchcustomer_number_unverifiedcontract_commitmentsim_number_mismatchother
messagestring

The cause in a sentence, for a person; free-form, not intended to be parsed

answeredBystring

Extensible enum. Who answered: client, firsty (Firsty, when you did not answer), or provider (the network answers by itself).

Examplesclientfirstyprovider
answeredAtstring · date-time
detailsone of BE | NL

Extensible by country: the market's own fields. Ignore a country you do not know.

Show properties
BEobjectoptional

A Belgian port-out. The network answers it and carries it out by itself.

Show properties
countrystring
NLobjectoptional

A Dutch port-out. Answer it with POST .../port-outs/{portOutRequestReference}/answer before answerBefore; a port-out still unanswered shortly before gets a default answer from Firsty.

Show properties
countrystring
customerIdstring | null

The customer number the recipient sent, to check against the customer's; null when it sent none and the customer confirmed the request by SMS instead

contractActionstring

Extensible enum. What the recipient asked for the customer's contract here: terminate_at_expiry ends it where it can end, terminate_early ends it even during a commitment, keep_with_new_number keeps it running on a new number.

Examplesterminate_at_expiryterminate_earlykeep_with_new_number
notestring | null

The recipient's note; null when it sent none

answerBeforestring · date-time

When the answer is due

firstPossibleAtstring | null · date-time

The earliest moment the number can leave, once answered; null until then

createdAtstring · date-time
updatedAtstring · date-time
completedAtstring | null · date-time

When the number left; null until it has

cancelledAtstring | null · date-time

When the recipient cancelled; null unless it did

409The port-out already has an answer (`port_out_already_answered`), the network refused the answer (`port_out_answer_refused`), or it is a port-out the network answers by itself (`port_out_not_answerable`)application/problem+json
Show response body
typestring · uri

URI reference to error documentation

titlestring

Short, consistent error summary

statusinteger

HTTP status code

detailstring

Human-readable explanation specific to this occurrence

codestring

Extensible enum. Machine-readable error slug. Branch on this field. The URI in type documents the code. Handle an unknown code by its HTTP status.

Examplesbad_requestvalidation_failedunauthorizedpayment_requiredfeature_not_enabledforbiddenbalance_not_foundesim_not_foundnot_foundnumber_registration_not_foundpackage_not_foundpackage_plan_not_foundport_in_not_foundport_out_not_foundprofile_not_foundscheduled_action_not_foundsubscription_not_foundsubscription_plan_not_foundwebhook_endpoint_not_foundbalance_not_availablebalance_update_pendingconcurrent_modificationconflictesim_change_pendingesim_not_activeesim_not_provisionedesim_suspendedesim_swap_cooldownesim_swap_pendingesim_terminatedinvalid_state_transitionlimit_reachedno_esim_availablenumber_registration_pendingport_in_pendingport_out_already_answeredport_out_answer_refusedport_out_not_answerableservices_change_pendingservices_not_availablebalance_not_supportedbalance_operation_not_supportedbalance_update_refusedclient_transaction_id_reusedesim_variant_not_allowedesim_variant_not_swappableidempotency_key_reusedinsufficient_balancemsisdn_swap_not_supportedmsisdn_swap_refusednumber_not_availablenumber_registration_not_supportedport_in_cancel_refusedport_in_reschedule_not_supportedport_in_reschedule_refusedport_out_answer_invalidporting_not_supportedservices_change_refusedservices_not_changeableservices_not_supportedsim_refused_by_networkunprocessable_entitylockedrate_limit_exceededinternal_errorbad_gatewayservice_unavailable
422The answer breaks a porting rule (`port_out_answer_invalid`): a moment outside the porting window or in the past, or a contract commitment less than 120 days out. Or an idempotency key was reused for a different request (`idempotency_key_reused`)application/problem+json
Show response body
typestring · uri

URI reference to error documentation

titlestring

Short, consistent error summary

statusinteger

HTTP status code

detailstring

Human-readable explanation specific to this occurrence

codestring

Extensible enum. Machine-readable error slug. Branch on this field. The URI in type documents the code. Handle an unknown code by its HTTP status.

Examplesbad_requestvalidation_failedunauthorizedpayment_requiredfeature_not_enabledforbiddenbalance_not_foundesim_not_foundnot_foundnumber_registration_not_foundpackage_not_foundpackage_plan_not_foundport_in_not_foundport_out_not_foundprofile_not_foundscheduled_action_not_foundsubscription_not_foundsubscription_plan_not_foundwebhook_endpoint_not_foundbalance_not_availablebalance_update_pendingconcurrent_modificationconflictesim_change_pendingesim_not_activeesim_not_provisionedesim_suspendedesim_swap_cooldownesim_swap_pendingesim_terminatedinvalid_state_transitionlimit_reachedno_esim_availablenumber_registration_pendingport_in_pendingport_out_already_answeredport_out_answer_refusedport_out_not_answerableservices_change_pendingservices_not_availablebalance_not_supportedbalance_operation_not_supportedbalance_update_refusedclient_transaction_id_reusedesim_variant_not_allowedesim_variant_not_swappableidempotency_key_reusedinsufficient_balancemsisdn_swap_not_supportedmsisdn_swap_refusednumber_not_availablenumber_registration_not_supportedport_in_cancel_refusedport_in_reschedule_not_supportedport_in_reschedule_refusedport_out_answer_invalidporting_not_supportedservices_change_refusedservices_not_changeableservices_not_supportedsim_refused_by_networkunprocessable_entitylockedrate_limit_exceededinternal_errorbad_gatewayservice_unavailable
400Bad request - invalid parameters401Unauthorized - missing or invalid API key403Forbidden - client does not have access to this resource404Resource not found423A request with this idempotency key is still being processed429Rate limit exceeded. A `429` can also arrive without these headers or this body; handle it by its status code.500Internal server error