Webhooks

Port-in events

Signed POST requests to your webhook endpoint for portin lifecycle events. See the Webhooks overview for signature verification.

Port-In Submitted

portin.submittedExperimental

Triggered when a port-in has been submitted to the network provider. 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

Public opaque port-in request reference (8-char uppercase base36)

profileReferencestring

esimReferencestring

msisdnstring

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

statusstring

Extensible enum.

requested: Accepted by Firsty; provider submission in progress
approved: The donor accepted the port; scheduledAt is when the number moves, once known, which can be days ahead. The port finishes at completed
cancelling: Cancellation requested, awaiting provider 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. 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
cancelled: Cancellation confirmed; the eSIM stays pre-active for a corrected request or abandon

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

Public opaque port-in request reference (8-char uppercase base36)

profileReferencestring

esimReferencestring

msisdnstring

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

statusstring

Extensible enum.

requested: Accepted by Firsty; provider submission in progress
approved: The donor accepted the port; scheduledAt is when the number moves, once known, which can be days ahead. The port finishes at completed
cancelling: Cancellation requested, awaiting provider 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. 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
cancelled: Cancellation confirmed; the eSIM stays pre-active for a corrected request or abandon

Examplesrequestedapprovedcancellingcompletedrejectedfailedcancelled

scheduledAtstring | null · date-time

When the number moves to this SIM, as the donor agreed; null when the porting provider 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 Rejected

portin.rejectedExperimental

Triggered when the donor operator rejected the port-in. Submit a corrected request with fixed donor details.

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

Public opaque port-in request reference (8-char uppercase base36)

profileReferencestring

esimReferencestring

msisdnstring

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

statusstring

Extensible enum.

requested: Accepted by Firsty; provider submission in progress
approved: The donor accepted the port; scheduledAt is when the number moves, once known, which can be days ahead. The port finishes at completed
cancelling: Cancellation requested, awaiting provider 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. 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
cancelled: Cancellation confirmed; the eSIM stays pre-active for a corrected request or abandon

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 for every porting provider. 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

Public opaque port-in request reference (8-char uppercase base36)

profileReferencestring

esimReferencestring

msisdnstring

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

statusstring

Extensible enum.

requested: Accepted by Firsty; provider submission in progress
approved: The donor accepted the port; scheduledAt is when the number moves, once known, which can be days ahead. The port finishes at completed
cancelling: Cancellation requested, awaiting provider 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. 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
cancelled: Cancellation confirmed; the eSIM stays pre-active for a corrected request or abandon

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.

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

Public opaque port-in request reference (8-char uppercase base36)

profileReferencestring

esimReferencestring

msisdnstring

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

statusstring

Extensible enum.

requested: Accepted by Firsty; provider submission in progress
approved: The donor accepted the port; scheduledAt is when the number moves, once known, which can be days ahead. The port finishes at completed
cancelling: Cancellation requested, awaiting provider 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. 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
cancelled: Cancellation confirmed; the eSIM stays pre-active for a corrected request or abandon

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

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 provider.

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

Public opaque port-in request reference (8-char uppercase base36)

profileReferencestring

esimReferencestring

msisdnstring

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

statusstring

Extensible enum.

requested: Accepted by Firsty; provider submission in progress
approved: The donor accepted the port; scheduledAt is when the number moves, once known, which can be days ahead. The port finishes at completed
cancelling: Cancellation requested, awaiting provider 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. 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
cancelled: Cancellation confirmed; the eSIM stays pre-active for a corrected request or abandon

Examplesrequestedapprovedcancellingcompletedrejectedfailedcancelled

portin.cancelled

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