Firsty

Search...

Search...

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

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 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 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 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 the client moved it; 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 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

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 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 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 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 the client moved it; null when the porting provider 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

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

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 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 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 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 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.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 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 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 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"
  }
}