Firsty

Search...

Search...

Webhooks

Porting events

Signed POST requests to your webhook endpoint for port-in and port-out events. See the Webhooks overview for signature verification.

Port-In Submitted

portin.submittedExperimental

Triggered when a port-in has been submitted to the network. A port-in can be submitted more than once under the same portInRequestReference; each submission replaces the previous one and triggers this event again.

Payload

typestring
Optionsportin.submitted
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
Show properties
portInRequestReferencestring

Port-in request reference

profileReferencestring
esimReferencestring
msisdnstring

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

statusstring

Extensible enum.

  • requested: Accepted by Firsty; submission to the network in progress
  • approved: The donor accepted the port; scheduledAt is the earliest moment the number can move, once known, which can be days ahead. When that moment has already passed, the number moves right after the approval. The port finishes at completed
  • cancelling: Cancellation requested, awaiting the network's confirmation
  • completed: The donor released the number and it is assigned to this SIM
  • rejected: Donor rejected the request (see reason); submit a corrected request or abandon (see the Porting workflow). A rejection the customer can still correct may keep the request requested until it is final
  • failed: Port failed (see reason); submit a corrected request or abandon (see the Porting workflow)
  • cancelled: Cancellation confirmed; submit a corrected request or abandon (see the Porting workflow)
Examplesrequestedapprovedcancellingcompletedrejectedfailedcancelled
portin.submitted
{
  "type": "portin.submitted",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portInRequestReference": "K7Q2M9XA",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32470123456",
    "status": "requested"
  }
}

Port-In Approved

portin.approvedExperimental

Triggered when the donor operator approved the port-in.

Payload

typestring
Optionsportin.approved
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
Show properties
portInRequestReferencestring

Port-in request reference

profileReferencestring
esimReferencestring
msisdnstring

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

statusstring

Extensible enum.

  • requested: Accepted by Firsty; submission to the network in progress
  • approved: The donor accepted the port; scheduledAt is the earliest moment the number can move, once known, which can be days ahead. When that moment has already passed, the number moves right after the approval. The port finishes at completed
  • cancelling: Cancellation requested, awaiting the network's confirmation
  • completed: The donor released the number and it is assigned to this SIM
  • rejected: Donor rejected the request (see reason); submit a corrected request or abandon (see the Porting workflow). A rejection the customer can still correct may keep the request requested until it is final
  • failed: Port failed (see reason); submit a corrected request or abandon (see the Porting workflow)
  • cancelled: Cancellation confirmed; submit a corrected request or abandon (see the Porting workflow)
Examplesrequestedapprovedcancellingcompletedrejectedfailedcancelled
scheduledAtstring | null · date-time

When the number moves to this SIM, as the donor agreed or, on portin.rescheduled, as you moved it; null when the network gives no date. It may move until the port completes

portin.approved
{
  "type": "portin.approved",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portInRequestReference": "K7Q2M9XA",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32470123456",
    "status": "requested",
    "scheduledAt": "2026-01-15T09:30:00Z"
  }
}

Port-In Rescheduled

portin.rescheduledExperimental

Triggered when an approved port-in is moved to a new porting moment; scheduledAt carries the new moment.

Payload

typestring
Optionsportin.rescheduled
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
Show properties
portInRequestReferencestring

Port-in request reference

profileReferencestring
esimReferencestring
msisdnstring

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

statusstring

Extensible enum.

  • requested: Accepted by Firsty; submission to the network in progress
  • approved: The donor accepted the port; scheduledAt is the earliest moment the number can move, once known, which can be days ahead. When that moment has already passed, the number moves right after the approval. The port finishes at completed
  • cancelling: Cancellation requested, awaiting the network's confirmation
  • completed: The donor released the number and it is assigned to this SIM
  • rejected: Donor rejected the request (see reason); submit a corrected request or abandon (see the Porting workflow). A rejection the customer can still correct may keep the request requested until it is final
  • failed: Port failed (see reason); submit a corrected request or abandon (see the Porting workflow)
  • cancelled: Cancellation confirmed; submit a corrected request or abandon (see the Porting workflow)
Examplesrequestedapprovedcancellingcompletedrejectedfailedcancelled
scheduledAtstring | null · date-time

When the number moves to this SIM, as the donor agreed or, on portin.rescheduled, as you moved it; null when the network gives no date. It may move until the port completes

portin.rescheduled
{
  "type": "portin.rescheduled",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portInRequestReference": "K7Q2M9XA",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32470123456",
    "status": "requested",
    "scheduledAt": "2026-01-15T09:30:00Z"
  }
}

Port-In Rejected

portin.rejectedExperimental

Triggered when the donor operator rejected the port-in. Submit a corrected request or abandon (see the Porting workflow).

Payload

typestring
Optionsportin.rejected
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
Show properties
portInRequestReferencestring

Port-in request reference

profileReferencestring
esimReferencestring
msisdnstring

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

statusstring

Extensible enum.

  • requested: Accepted by Firsty; submission to the network in progress
  • approved: The donor accepted the port; scheduledAt is the earliest moment the number can move, once known, which can be days ahead. When that moment has already passed, the number moves right after the approval. The port finishes at completed
  • cancelling: Cancellation requested, awaiting the network's confirmation
  • completed: The donor released the number and it is assigned to this SIM
  • rejected: Donor rejected the request (see reason); submit a corrected request or abandon (see the Porting workflow). A rejection the customer can still correct may keep the request requested until it is final
  • failed: Port failed (see reason); submit a corrected request or abandon (see the Porting workflow)
  • cancelled: Cancellation confirmed; submit a corrected request or abandon (see the Porting workflow)
Examplesrequestedapprovedcancellingcompletedrejectedfailedcancelled
reasonobject

Why the port-in was rejected or failed. Present when status is rejected or failed, and on a requested port-in the donor has rejected for a reason the customer can still correct

Show properties
codestring

Normalized cause of the rejection or failure, the same in every country. provider_failure covers every cause without a more specific code. The list of values is open-ended; new values may be added

Examplesmsisdn_sim_mismatchmsisdn_account_mismatchdonor_contract_type_mismatchnumber_not_activenumber_not_portablenumber_porting_in_progressporting_window_unavailableprovider_failure
messagestring | null

Human-readable detail of the cause for support; free-form, not intended to be parsed. Null when there is none

portin.rejected
{
  "type": "portin.rejected",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portInRequestReference": "K7Q2M9XA",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32470123456",
    "status": "requested",
    "reason": {
      "code": "msisdn_sim_mismatch",
      "message": "MSISDN/SIM number mismatch"
    }
  }
}

Port-In Completed

portin.completedExperimental

Triggered when the port completed: the donor released the number and it is assigned to the SIM.

Payload

typestring
Optionsportin.completed
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
Show properties
portInRequestReferencestring

Port-in request reference

profileReferencestring
esimReferencestring
msisdnstring

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

statusstring

Extensible enum.

  • requested: Accepted by Firsty; submission to the network in progress
  • approved: The donor accepted the port; scheduledAt is the earliest moment the number can move, once known, which can be days ahead. When that moment has already passed, the number moves right after the approval. The port finishes at completed
  • cancelling: Cancellation requested, awaiting the network's confirmation
  • completed: The donor released the number and it is assigned to this SIM
  • rejected: Donor rejected the request (see reason); submit a corrected request or abandon (see the Porting workflow). A rejection the customer can still correct may keep the request requested until it is final
  • failed: Port failed (see reason); submit a corrected request or abandon (see the Porting workflow)
  • cancelled: Cancellation confirmed; submit a corrected request or abandon (see the Porting workflow)
Examplesrequestedapprovedcancellingcompletedrejectedfailedcancelled
portin.completed
{
  "type": "portin.completed",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portInRequestReference": "K7Q2M9XA",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32470123456",
    "status": "requested"
  }
}

Port-In Failed

portin.failedExperimental

Triggered when the port-in failed. Submit a corrected request or abandon (see the Porting workflow).

Payload

typestring
Optionsportin.failed
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
Show properties
portInRequestReferencestring

Port-in request reference

profileReferencestring
esimReferencestring
msisdnstring

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

statusstring

Extensible enum.

  • requested: Accepted by Firsty; submission to the network in progress
  • approved: The donor accepted the port; scheduledAt is the earliest moment the number can move, once known, which can be days ahead. When that moment has already passed, the number moves right after the approval. The port finishes at completed
  • cancelling: Cancellation requested, awaiting the network's confirmation
  • completed: The donor released the number and it is assigned to this SIM
  • rejected: Donor rejected the request (see reason); submit a corrected request or abandon (see the Porting workflow). A rejection the customer can still correct may keep the request requested until it is final
  • failed: Port failed (see reason); submit a corrected request or abandon (see the Porting workflow)
  • cancelled: Cancellation confirmed; submit a corrected request or abandon (see the Porting workflow)
Examplesrequestedapprovedcancellingcompletedrejectedfailedcancelled
reasonobject

Why the port-in was rejected or failed. Present when status is rejected or failed, and on a requested port-in the donor has rejected for a reason the customer can still correct

Show properties
codestring

Normalized cause of the rejection or failure, the same in every country. provider_failure covers every cause without a more specific code. The list of values is open-ended; new values may be added

Examplesmsisdn_sim_mismatchmsisdn_account_mismatchdonor_contract_type_mismatchnumber_not_activenumber_not_portablenumber_porting_in_progressporting_window_unavailableprovider_failure
messagestring | null

Human-readable detail of the cause for support; free-form, not intended to be parsed. Null when there is none

portin.failed
{
  "type": "portin.failed",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portInRequestReference": "K7Q2M9XA",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32470123456",
    "status": "requested",
    "reason": {
      "code": "msisdn_sim_mismatch",
      "message": "MSISDN/SIM number mismatch"
    }
  }
}

Port-In Cancelled

portin.cancelledExperimental

Triggered when a requested cancellation was confirmed by the network.

Payload

typestring
Optionsportin.cancelled
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
Show properties
portInRequestReferencestring

Port-in request reference

profileReferencestring
esimReferencestring
msisdnstring

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

statusstring

Extensible enum.

  • requested: Accepted by Firsty; submission to the network in progress
  • approved: The donor accepted the port; scheduledAt is the earliest moment the number can move, once known, which can be days ahead. When that moment has already passed, the number moves right after the approval. The port finishes at completed
  • cancelling: Cancellation requested, awaiting the network's confirmation
  • completed: The donor released the number and it is assigned to this SIM
  • rejected: Donor rejected the request (see reason); submit a corrected request or abandon (see the Porting workflow). A rejection the customer can still correct may keep the request requested until it is final
  • failed: Port failed (see reason); submit a corrected request or abandon (see the Porting workflow)
  • cancelled: Cancellation confirmed; submit a corrected request or abandon (see the Porting workflow)
Examplesrequestedapprovedcancellingcompletedrejectedfailedcancelled
portin.cancelled
{
  "type": "portin.cancelled",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portInRequestReference": "K7Q2M9XA",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32470123456",
    "status": "requested"
  }
}

Port-Out Requested

portout.requestedExperimental

Triggered when the recipient asks for one of your numbers. A port-out that carries details.answerBefore must be answered before that moment (see Answer a port-out); one without it needs no answer.

Payload

typestring
Optionsportout.requested
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
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

portout.requested
{
  "type": "portout.requested",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portOutRequestReference": "P7Q2M9XB",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32495708013",
    "status": "requested",
    "answer": {
      "decision": "approved",
      "answeredBy": "client",
      "answeredAt": "2026-01-15T09:30:00Z"
    },
    "details": {
      "country": "BE"
    },
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z",
    "completedAt": "2026-01-15T09:30:00Z",
    "cancelledAt": "2026-01-15T09:30:00Z"
  }
}

Port-Out Approved

portout.approvedExperimental

Triggered when the port-out was approved; the number leaves at the agreed moment.

Payload

typestring
Optionsportout.approved
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
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

portout.approved
{
  "type": "portout.approved",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portOutRequestReference": "P7Q2M9XB",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32495708013",
    "status": "requested",
    "answer": {
      "decision": "approved",
      "answeredBy": "client",
      "answeredAt": "2026-01-15T09:30:00Z"
    },
    "details": {
      "country": "BE"
    },
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z",
    "completedAt": "2026-01-15T09:30:00Z",
    "cancelledAt": "2026-01-15T09:30:00Z"
  }
}

Port-Out Rejected

portout.rejectedExperimental

Triggered when the port-out was rejected; the number stays.

Payload

typestring
Optionsportout.rejected
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
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

portout.rejected
{
  "type": "portout.rejected",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portOutRequestReference": "P7Q2M9XB",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32495708013",
    "status": "requested",
    "answer": {
      "decision": "approved",
      "answeredBy": "client",
      "answeredAt": "2026-01-15T09:30:00Z"
    },
    "details": {
      "country": "BE"
    },
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z",
    "completedAt": "2026-01-15T09:30:00Z",
    "cancelledAt": "2026-01-15T09:30:00Z"
  }
}

Port-Out Cancelled

portout.cancelledExperimental

Triggered when the recipient cancelled the port-out; the number stays.

Payload

typestring
Optionsportout.cancelled
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
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

portout.cancelled
{
  "type": "portout.cancelled",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portOutRequestReference": "P7Q2M9XB",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32495708013",
    "status": "requested",
    "answer": {
      "decision": "approved",
      "answeredBy": "client",
      "answeredAt": "2026-01-15T09:30:00Z"
    },
    "details": {
      "country": "BE"
    },
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z",
    "completedAt": "2026-01-15T09:30:00Z",
    "cancelledAt": "2026-01-15T09:30:00Z"
  }
}

Port-Out Completed

portout.completedExperimental

Triggered when the number left for the recipient. The SIM is terminated with it, and esim.lifecycle.terminated follows. It can follow portout.rejected or portout.cancelled when the number left after all.

Payload

typestring
Optionsportout.completed
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
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

portout.completed
{
  "type": "portout.completed",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portOutRequestReference": "P7Q2M9XB",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32495708013",
    "status": "requested",
    "answer": {
      "decision": "approved",
      "answeredBy": "client",
      "answeredAt": "2026-01-15T09:30:00Z"
    },
    "details": {
      "country": "BE"
    },
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z",
    "completedAt": "2026-01-15T09:30:00Z",
    "cancelledAt": "2026-01-15T09:30:00Z"
  }
}

Port-Out Failed

portout.failedExperimental

Triggered when the network reports that the port-out could not be carried out; the number stays.

Payload

typestring
Optionsportout.failed
timestampstring · date-time

When the event was recorded. This can be later than the change it reports: usage reported by the network can describe consumption that happened earlier.

dataobject
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

portout.failed
{
  "type": "portout.failed",
  "timestamp": "2026-01-24T14:30:00Z",
  "data": {
    "portOutRequestReference": "P7Q2M9XB",
    "profileReference": "1234567890123456",
    "esimReference": "123456000000000001",
    "msisdn": "32495708013",
    "status": "requested",
    "answer": {
      "decision": "approved",
      "answeredBy": "client",
      "answeredAt": "2026-01-15T09:30:00Z"
    },
    "details": {
      "country": "BE"
    },
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z",
    "completedAt": "2026-01-15T09:30:00Z",
    "cancelledAt": "2026-01-15T09:30:00Z"
  }
}