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.
/profiles/{profileReference}/esims/{esimReference}/port-outs/{portOutRequestReference}/answerAuthorization
Authorization: Bearer {token} — an OAuth2 access token from the client-credentials flow. How authentication works
Path parameters
profileReferencestringrequiredProfile reference
esimReferencestringrequiredeSIM reference
portOutRequestReferencestringrequiredPort-out request reference
Headers
X-Idempotency-KeystringOptional 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
approvedobjectShow propertiesHide properties
decisionstringrequiredfirstPossibleAtstring · date-timeThe 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 | otherShow propertiesHide properties
customer_number_mismatchobjectThe customerId the recipient sent is not this customer's.
Show propertiesHide properties
decisionstringrequiredreasonstringrequiredcontract_commitmentobjectThe customer's contract has more than 4 months left to run.
Show propertiesHide properties
decisionstringrequiredreasonstringrequiredfirstPossibleAtstring · date-timerequiredWhen the customer can leave; at least 120 days out
not_portableobjectThe number cannot be ported.
Show propertiesHide properties
decisionstringrequiredreasonstringrequiredotherobjectShow propertiesHide properties
decisionstringrequiredreasonstringrequirednotestringrequiredWhy, for the recipient
Responses
200The answer was taken; the port-out carries it and its new statusapplication/jsonShow response bodyHide response body
dataobjectoptionalShow propertiesHide properties
portOutRequestReferencestringPort-out request reference
profileReferencestringesimReferencestringmsisdnstringThe number leaving, in international format (E.164 without a leading +)
statusstringrequested: The recipient asked for the number; no answer yetapproved: The port-out was approved; the number leaves at the agreed moment. It can still be rejectedrejected: The port-out was rejected (seeanswer.reason); the number stayscancelled: The recipient cancelled; the number stayscompleted: The number left for the recipient. The only final status: a rejected, cancelled or failed port-out completes when the number left after allfailed: The port-out could not be carried out; the number stays
requestedapprovedrejectedcancelledcompletedfailedanswerone of approved | rejected | nullThe answer to the port-out; null until it has one
Show propertiesHide properties
approvedobjectoptionalShow propertiesHide properties
decisionstringansweredBystringExtensible enum. Who answered: client,
firsty (Firsty, when you did not answer), or provider (the network answers by itself).
clientfirstyprovideransweredAtstring · date-timerejectedobjectoptionalShow propertiesHide properties
decisionstringreasonobjectWhy the port-out was rejected
Show propertiesHide properties
codestringExtensible enum. The cause of the rejection, the same for every market.
not_portablecustomer_number_mismatchcustomer_number_unverifiedcontract_commitmentsim_number_mismatchothermessagestringThe cause in a sentence, for a person; free-form, not intended to be parsed
answeredBystringExtensible enum. Who answered: client,
firsty (Firsty, when you did not answer), or provider (the network answers by itself).
clientfirstyprovideransweredAtstring · date-timedetailsone of BE | NLExtensible by country: the market's own fields. Ignore a country you do not know.
Show propertiesHide properties
BEobjectoptionalA Belgian port-out. The network answers it and carries it out by itself.
Show propertiesHide properties
countrystringNLobjectoptionalA 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 propertiesHide properties
countrystringcustomerIdstring | nullThe 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
contractActionstringExtensible 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.
terminate_at_expiryterminate_earlykeep_with_new_numbernotestring | nullThe recipient's note; null when it sent none
answerBeforestring · date-timeWhen the answer is due
firstPossibleAtstring | null · date-timeThe earliest moment the number can leave, once answered; null until then
createdAtstring · date-timeupdatedAtstring · date-timecompletedAtstring | null · date-timeWhen the number left; null until it has
cancelledAtstring | null · date-timeWhen 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/jsonShow response bodyHide response body
dataobjectoptionalShow propertiesHide properties
portOutRequestReferencestringPort-out request reference
profileReferencestringesimReferencestringmsisdnstringThe number leaving, in international format (E.164 without a leading +)
statusstringrequested: The recipient asked for the number; no answer yetapproved: The port-out was approved; the number leaves at the agreed moment. It can still be rejectedrejected: The port-out was rejected (seeanswer.reason); the number stayscancelled: The recipient cancelled; the number stayscompleted: The number left for the recipient. The only final status: a rejected, cancelled or failed port-out completes when the number left after allfailed: The port-out could not be carried out; the number stays
requestedapprovedrejectedcancelledcompletedfailedanswerone of approved | rejected | nullThe answer to the port-out; null until it has one
Show propertiesHide properties
approvedobjectoptionalShow propertiesHide properties
decisionstringansweredBystringExtensible enum. Who answered: client,
firsty (Firsty, when you did not answer), or provider (the network answers by itself).
clientfirstyprovideransweredAtstring · date-timerejectedobjectoptionalShow propertiesHide properties
decisionstringreasonobjectWhy the port-out was rejected
Show propertiesHide properties
codestringExtensible enum. The cause of the rejection, the same for every market.
not_portablecustomer_number_mismatchcustomer_number_unverifiedcontract_commitmentsim_number_mismatchothermessagestringThe cause in a sentence, for a person; free-form, not intended to be parsed
answeredBystringExtensible enum. Who answered: client,
firsty (Firsty, when you did not answer), or provider (the network answers by itself).
clientfirstyprovideransweredAtstring · date-timedetailsone of BE | NLExtensible by country: the market's own fields. Ignore a country you do not know.
Show propertiesHide properties
BEobjectoptionalA Belgian port-out. The network answers it and carries it out by itself.
Show propertiesHide properties
countrystringNLobjectoptionalA 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 propertiesHide properties
countrystringcustomerIdstring | nullThe 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
contractActionstringExtensible 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.
terminate_at_expiryterminate_earlykeep_with_new_numbernotestring | nullThe recipient's note; null when it sent none
answerBeforestring · date-timeWhen the answer is due
firstPossibleAtstring | null · date-timeThe earliest moment the number can leave, once answered; null until then
createdAtstring · date-timeupdatedAtstring · date-timecompletedAtstring | null · date-timeWhen the number left; null until it has
cancelledAtstring | null · date-timeWhen 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+jsonShow response bodyHide response body
typestring · uriURI reference to error documentation
titlestringShort, consistent error summary
statusintegerHTTP status code
detailstringHuman-readable explanation specific to this occurrence
codestringExtensible enum. Machine-readable error slug. Branch on this field. The URI in type documents the code. Handle an unknown code by its HTTP status.
bad_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_unavailable422The 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+jsonShow response bodyHide response body
typestring · uriURI reference to error documentation
titlestringShort, consistent error summary
statusintegerHTTP status code
detailstringHuman-readable explanation specific to this occurrence
codestringExtensible enum. Machine-readable error slug. Branch on this field. The URI in type documents the code. Handle an unknown code by its HTTP status.
bad_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_unavailable400Bad 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