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

Experimental. This event is still settling — its payload may change without a deprecation cycle.

Triggered when a port-in has been submitted to the network provider.

Payload

typestringrequired

Optionsportin.submitted

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

portInRequestReferencestringrequired

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

profileReferencestringrequired

esimReferencestringrequired

msisdnstringrequired

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

statusstringrequired

requested: Accepted by Firsty; provider submission in progress
approved: Donor/provider accepted the port
scheduled: Port scheduled for a future date (reserved for future markets)
cancelling: Cancellation requested, awaiting provider confirmation
completed: Number ported — the eSIM activates with the ported number
rejected: Donor rejected the request (see reason)
failed: Port failed (see reason)
cancelled: Cancellation confirmed

Optionsrequestedapprovedscheduledcancellingcompletedrejectedfailedcancelled

reasonobject | null

Failure/rejection detail, present when status is rejected or failed

Show properties

codestringrequired

Normalized failure/rejection code

messagestring | null

Human-readable detail when available

scheduledDatestring | null · date

Planned porting date when known (reserved for future markets)

portin.submitted

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

Port-In Approved

portin.approved

Experimental. This event is still settling — its payload may change without a deprecation cycle.

Triggered when the donor operator approved the port-in.

Payload

typestringrequired

Optionsportin.approved

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

portInRequestReferencestringrequired

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

profileReferencestringrequired

esimReferencestringrequired

msisdnstringrequired

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

statusstringrequired

requested: Accepted by Firsty; provider submission in progress
approved: Donor/provider accepted the port
scheduled: Port scheduled for a future date (reserved for future markets)
cancelling: Cancellation requested, awaiting provider confirmation
completed: Number ported — the eSIM activates with the ported number
rejected: Donor rejected the request (see reason)
failed: Port failed (see reason)
cancelled: Cancellation confirmed

Optionsrequestedapprovedscheduledcancellingcompletedrejectedfailedcancelled

reasonobject | null

Failure/rejection detail, present when status is rejected or failed

Show properties

codestringrequired

Normalized failure/rejection code

messagestring | null

Human-readable detail when available

scheduledDatestring | null · date

Planned porting date when known (reserved for future markets)

portin.approved

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

Port-In Rejected

portin.rejected

Experimental. This event is still settling — its payload may change without a deprecation cycle.

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

Payload

typestringrequired

Optionsportin.rejected

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

portInRequestReferencestringrequired

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

profileReferencestringrequired

esimReferencestringrequired

msisdnstringrequired

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

statusstringrequired

requested: Accepted by Firsty; provider submission in progress
approved: Donor/provider accepted the port
scheduled: Port scheduled for a future date (reserved for future markets)
cancelling: Cancellation requested, awaiting provider confirmation
completed: Number ported — the eSIM activates with the ported number
rejected: Donor rejected the request (see reason)
failed: Port failed (see reason)
cancelled: Cancellation confirmed

Optionsrequestedapprovedscheduledcancellingcompletedrejectedfailedcancelled

reasonobject | null

Failure/rejection detail, present when status is rejected or failed

Show properties

codestringrequired

Normalized failure/rejection code

messagestring | null

Human-readable detail when available

scheduledDatestring | null · date

Planned porting date when known (reserved for future markets)

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_account_mismatch",
      "message": "MSISDN/Account number mismatch"
    },
    "scheduledDate": "2026-01-15"
  }
}

Port-In Completed

portin.completed

Experimental. This event is still settling — its payload may change without a deprecation cycle.

Triggered when the port completed — the ported number is now live on the eSIM and the eSIM activates.

Payload

typestringrequired

Optionsportin.completed

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

portInRequestReferencestringrequired

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

profileReferencestringrequired

esimReferencestringrequired

msisdnstringrequired

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

statusstringrequired

requested: Accepted by Firsty; provider submission in progress
approved: Donor/provider accepted the port
scheduled: Port scheduled for a future date (reserved for future markets)
cancelling: Cancellation requested, awaiting provider confirmation
completed: Number ported — the eSIM activates with the ported number
rejected: Donor rejected the request (see reason)
failed: Port failed (see reason)
cancelled: Cancellation confirmed

Optionsrequestedapprovedscheduledcancellingcompletedrejectedfailedcancelled

reasonobject | null

Failure/rejection detail, present when status is rejected or failed

Show properties

codestringrequired

Normalized failure/rejection code

messagestring | null

Human-readable detail when available

scheduledDatestring | null · date

Planned porting date when known (reserved for future markets)

portin.completed

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

Port-In Failed

portin.failed

Experimental. This event is still settling — its payload may change without a deprecation cycle.

Triggered when the port-in failed. Submit a corrected request or abandon.

Payload

typestringrequired

Optionsportin.failed

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

portInRequestReferencestringrequired

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

profileReferencestringrequired

esimReferencestringrequired

msisdnstringrequired

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

statusstringrequired

requested: Accepted by Firsty; provider submission in progress
approved: Donor/provider accepted the port
scheduled: Port scheduled for a future date (reserved for future markets)
cancelling: Cancellation requested, awaiting provider confirmation
completed: Number ported — the eSIM activates with the ported number
rejected: Donor rejected the request (see reason)
failed: Port failed (see reason)
cancelled: Cancellation confirmed

Optionsrequestedapprovedscheduledcancellingcompletedrejectedfailedcancelled

reasonobject | null

Failure/rejection detail, present when status is rejected or failed

Show properties

codestringrequired

Normalized failure/rejection code

messagestring | null

Human-readable detail when available

scheduledDatestring | null · date

Planned porting date when known (reserved for future markets)

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_account_mismatch",
      "message": "MSISDN/Account number mismatch"
    },
    "scheduledDate": "2026-01-15"
  }
}

Port-In Cancelled

portin.cancelled

Experimental. This event is still settling — its payload may change without a deprecation cycle.

Triggered when a requested cancellation was confirmed by the provider.

Payload

typestringrequired

Optionsportin.cancelled

timestampstring · date-timerequired

When the event occurred

dataobjectrequired

Show properties

portInRequestReferencestringrequired

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

profileReferencestringrequired

esimReferencestringrequired

msisdnstringrequired

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

statusstringrequired

requested: Accepted by Firsty; provider submission in progress
approved: Donor/provider accepted the port
scheduled: Port scheduled for a future date (reserved for future markets)
cancelling: Cancellation requested, awaiting provider confirmation
completed: Number ported — the eSIM activates with the ported number
rejected: Donor rejected the request (see reason)
failed: Port failed (see reason)
cancelled: Cancellation confirmed

Optionsrequestedapprovedscheduledcancellingcompletedrejectedfailedcancelled

reasonobject | null

Failure/rejection detail, present when status is rejected or failed

Show properties

codestringrequired

Normalized failure/rejection code

messagestring | null

Human-readable detail when available

scheduledDatestring | null · date

Planned porting date when known (reserved for future markets)

portin.cancelled

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