Issue the eSIM package for a booking item

Hubby Partner API (5.20.0)

Every response of a matched route carries the header X-Hubby-Call-Id, the id of the call in Hubby's records. A request refused before it reaches a route carries no call id: an unknown path (404, code not_found), a method the path does not take (405, code method_not_allowed), or a query string PHP cannot parse whole (400, code malformed_query_string). Those two refusals, 405 and 400, can answer any path and are not listed per operation. Every 4xx refusal body carries a message and a code to branch on. A 5xx can carry a message alone: the issue call's 500 (POST /v1/bookings/{booking}/items/{item}/package) has no code; retry it with the same Idempotency-Key.

Download OpenAPI description

openapi.json

openapi.yaml

Servers

Production

https://core.hubbyesim.com/api/

Staging

https://core-staging.hubbyesim.com/api/

Analytics

Operations

Booking

Operations

BookingItemPackage

Operations

Issue the eSIM package for a booking item

Request

Creates the package on the network and, for a traveller with no Hubby eSIM yet, assigns one. The response holds everything the traveller needs to install. A traveller who already has a Hubby eSIM gets the new package on that same eSIM: the ICCID repeats and esim.installed_at is set once it is on their phone, so do not ask them to install again.

{booking} accepts the same identifiers as GET /v1/bookings/{id}; {item} is the item's id. Send an Idempotency-Key: a retry with the same key replays the first 201 unchanged, with Idempotent-Replayed: true, so retry blind after any timeout. The key is stored with a 201 only, so a 5xx answer is safe to retry with the same key. Once you terminate the package, its key is spent: sending it again answers 409 idempotency_key_spent, and issuing again needs a new key. Issuing calls the network provider inline and is rate limited per Partner; honour 429 and its Retry-After.

Path

bookingstringrequired

itemstringrequired

Headers

Idempotency-Keystringrequired

Required. A unique key for this issue, for example a UUID, reused across every retry of it. A retry with the same key replays the stored response for 24 hours, until you terminate the package it issued.

Bodyapplication/json

external_user_idstring or null<= 255 characters

Your id for the traveller who receives this package. Required when the item does not name a traveller yet; the traveller is then bound to the item exactly as at booking. When the item already names one, send the same id or leave it out.

curl -i -X POST \
  'https://core.hubbyesim.com/api/v1/bookings/{booking}/items/{item}/package' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Signature: YOUR_API_KEY_HERE' \
  -H 'X-Timestamp: YOUR_API_KEY_HERE' \
  -d '{
    "external_user_id": "string"
  }'

Responses

IssuedPackage

Headers

Idempotent-Replayedstring

Sent as true only when this answer is the stored answer to an earlier request with the same Idempotency-Key, replayed unchanged. Absent on the first answer.

X-Hubby-Call-Idstringrequired

The id of this call in Hubby's records. Quote it when you ask Hubby about a call.

Bodyapplication/json

dataobject(IssuedPackage)required

data.idstringrequired

data.statestring(PackageLifecycleState)required

Where this package is in its lifecycle: redeemed (issued, install material available), installed (the eSIM is on a phone), activated (live on the network, validity running), expired (the validity elapsed, or the provider ended the package after it activated; a package that used up its data stays activated until the provider ends it), terminated (ended before activation).

Enum"queued""unavailable""redeemed""installed""activated""expired""terminated""cancelled"

data.bundle_idstringrequired

The bundle this package was issued from.

data.issued_atstring or null(date-time)required

When the package was issued.

data.installed_atstring or null(date-time)required

When this package became installable on a phone: the eSIM's install, or the issue itself when the eSIM was already installed. Null until the eSIM is on a phone.

data.activated_atstring or null(date-time)required

When the package activated and its validity started: the time the connectivity provider reported the package activated. Hubby does not observe the network attach itself. Null until then.

data.expires_atstring or null(date-time)required

The latest moment this package can still be activated: the deadline the connectivity provider sets when the package is issued, after which an unused package can no longer be started. It is not when the package's validity ends: a package with a few days of validity is typically still activatable for about a year. Use valid_until for when the package stops working.

data.valid_untilstring or null(date-time)required

When this package's validity ends and its data stops working: the moment it activated plus its time allowance. Null until the package activates, because the clock starts at activation, not at issue. Also null for a package that carries no time allowance.

data.terminated_atstring or null(date-time)required

When the package ended: before activation (state is terminated), or after activation when the provider ended it (state is expired). Null while the package has not ended.

data.esimobject(EsimInstallMaterial)required

data.esim.iccidstringrequired

data.esim.installed_atstring or null(date-time)required

When this eSIM was first installed on a phone, whichever package it was installed for. Set for a repeat traveller: the eSIM is already on their phone, so skip the install screen and show that the new package is ready. Null until the eSIM is installed.

data.esim.lpastring or nullrequired

The activation string. Render it as a QR code for "install on another device".

data.esim.smdp_addressstring or nullrequired

The SM-DP+ address from lpa, for manual entry in the phone's settings.

data.esim.matching_idstring or nullrequired

The matching id (activation code) from lpa, for manual entry in the phone's settings.

data.esim.install_linksobjectrequired

One-tap install links. Open the one for the phone that will hold the eSIM; its own installer opens. Each is null when the activation string is not in the standard LPA:1$… form.

data.esim.install_links.iosstring or nullrequired

data.esim.install_links.androidstring or nullrequired

Response

application/json

{
  "data": {
    "id": "string",
    "state": "queued",
    "bundle_id": "string",
    "issued_at": "2019-08-24T14:15:22Z",
    "installed_at": "2019-08-24T14:15:22Z",
    "activated_at": "2019-08-24T14:15:22Z",
    "expires_at": "2019-08-24T14:15:22Z",
    "valid_until": "2019-08-24T14:15:22Z",
    "terminated_at": "2019-08-24T14:15:22Z",
    "esim": { … }
  }
}

Read the package issued for a booking item

Request

Same body as the issue call, with the current state and timestamps. {booking} accepts the same identifiers as GET /v1/bookings/{id}; {item} is the item's id.

Path

bookingstringrequired

itemstringrequired

curl -i -X GET \
  'https://core.hubbyesim.com/api/v1/bookings/{booking}/items/{item}/package' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Signature: YOUR_API_KEY_HERE' \
  -H 'X-Timestamp: YOUR_API_KEY_HERE'

Responses

Headers

X-Hubby-Call-Idstringrequired

The id of this call in Hubby's records. Quote it when you ask Hubby about a call.

Bodyapplication/json

dataobject(IssuedPackage)required

data.idstringrequired

data.statestring(PackageLifecycleState)required

Enum"queued""unavailable""redeemed""installed""activated""expired""terminated""cancelled"

data.bundle_idstringrequired

The bundle this package was issued from.

data.issued_atstring or null(date-time)required

When the package was issued.

data.installed_atstring or null(date-time)required

When this package became installable on a phone: the eSIM's install, or the issue itself when the eSIM was already installed. Null until the eSIM is on a phone.

data.activated_atstring or null(date-time)required

When the package activated and its validity started: the time the connectivity provider reported the package activated. Hubby does not observe the network attach itself. Null until then.

data.expires_atstring or null(date-time)required

data.valid_untilstring or null(date-time)required

data.terminated_atstring or null(date-time)required

When the package ended: before activation (state is terminated), or after activation when the provider ended it (state is expired). Null while the package has not ended.

data.esimobject(EsimInstallMaterial)required

data.esim.iccidstringrequired

data.esim.installed_atstring or null(date-time)required

data.esim.lpastring or nullrequired

The activation string. Render it as a QR code for "install on another device".

data.esim.smdp_addressstring or nullrequired

The SM-DP+ address from lpa, for manual entry in the phone's settings.

data.esim.matching_idstring or nullrequired

The matching id (activation code) from lpa, for manual entry in the phone's settings.

data.esim.install_linksobjectrequired

One-tap install links. Open the one for the phone that will hold the eSIM; its own installer opens. Each is null when the activation string is not in the standard LPA:1$… form.

data.esim.install_links.iosstring or nullrequired

data.esim.install_links.androidstring or nullrequired

Response

application/json

{
  "data": {
    "id": "string",
    "state": "queued",
    "bundle_id": "string",
    "issued_at": "2019-08-24T14:15:22Z",
    "installed_at": "2019-08-24T14:15:22Z",
    "activated_at": "2019-08-24T14:15:22Z",
    "expires_at": "2019-08-24T14:15:22Z",
    "valid_until": "2019-08-24T14:15:22Z",
    "terminated_at": "2019-08-24T14:15:22Z",
    "esim": { … }
  }
}

Terminate the package issued for a booking item

Request

Ends, at once on the network, a package you issued that has not activated yet. Use it for a withdrawal, a changed plan, or a traveller who never received the install material. The item returns to queued, so you can issue it again or cancel the booking. Nothing is charged for a terminated package, and the traveller keeps their Hubby eSIM: a new issue puts the new package on the same eSIM. A package.terminated webhook follows.

Once the package has activated on the network it is consumed and cannot be terminated. A package the traveller redeemed in the Hubby app cannot be terminated here. {booking} accepts the same identifiers as GET /v1/bookings/{id}; {item} is the item's id.

Path

bookingstringrequired

itemstringrequired

Query

reasonPartnerTerminateReason (string) or null

Why you terminate the package: changed_plans, installation_failed, not_received or other. Optional; it is shown to Hubby support and sent back on the package.terminated webhook.

Any of:

Why you terminated a package you issued.

string(PartnerTerminateReason)

Why you terminated a package you issued.

Enum"changed_plans""installation_failed""not_received""other"

curl -i -X DELETE \
  'https://core.hubbyesim.com/api/v1/bookings/{booking}/items/{item}/package?reason=changed_plans' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Signature: YOUR_API_KEY_HERE' \
  -H 'X-Timestamp: YOUR_API_KEY_HERE'

Responses

No content

Headers

X-Hubby-Call-Idstringrequired

The id of this call in Hubby's records. Quote it when you ask Hubby about a call.

Response

No content

Bundle

Operations

CurrentPartner

Operations

Destination

Operations

DeviceCompatibility

Operations

Esim

Operations

RedirectToken

Operations

Hubby Partner API (5.20.0)

Analytics

Booking

BookingItemPackage

Issue the eSIM package for a booking item

Request

Responses

Was this helpful?

Read the package issued for a booking item

Request

Responses

Was this helpful?

Terminate the package issued for a booking item

Request

Responses

Was this helpful?

Bundle

CurrentPartner

Destination

DeviceCompatibility

Esim

RedirectToken

Hubby Partner API (5.20.0)

Analytics

Booking

BookingItemPackage

Issue the eSIM package for a booking item

Request

Responses

Was this helpful?

Read the package issued for a booking item

Request

Responses

Was this helpful?

Terminate the package issued for a booking item

RequestExpand all

Responses

Was this helpful?

Bundle

CurrentPartner

Destination

DeviceCompatibility

Esim

RedirectToken

Request