Packages

List packages for an eSIM

Retrieves a paginated list of packages assigned to a specific eSIM. Results are sorted by creation date (newest first).

get/profiles/{profileReference}/esims/{esimReference}/packages

Authorization

Authorization: Bearer {token} — an OAuth2 access token from the client-credentials flow. How authentication works

Path parameters

profileReferencestringrequired

The eSIM's profile reference (16-digit numeric string)

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

Query parameters

limitinteger

Maximum number of items to return (1-100)

Default20

cursorstring

Opaque cursor token for fetching the next page. Pass the nextCursor value from a previous response.

statusstring

Filter by package status

Optionsactivethrottledexhaustedexpiredremoved

Responses

200List of packagesapplication/json

Show response body

dataobject

Show properties

profileReferencestring

The eSIM profile reference

externalProfileIdstring | null

The client's external profile ID if provided

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

The eSIM ICCID

packagesarray of PackageSummary

Show properties

packageReferencestring

Package reference identifier (23-character opaque token)

externalTransactionIdstring | null

The client's external transaction ID if provided

planReferencestring

Plan reference identifier (14-character opaque token)

typestring

Package type: data for mobile data, sms for text messaging, voice for calls

Optionsdatasmsvoice

countryCodestring

statusstring

Optionsactivethrottledexhaustedexpiredremoved

recurringboolean

Whether this package will auto-renew

activatedAtstring | null · date-time

expiresAtstring | null · date-time

createdAtstring · date-time

paginationobject

Show properties

limitintegerrequired

Maximum items per page

hasMorebooleanrequired

Whether there are more items after this page

nextCursorstring | nullrequired

Opaque cursor token for the next page. Null when there are no more results.

401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 429Rate limit exceeded 500Internal server error

Request

curl 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/profiles/%7BprofileReference%7D/esims/%7BesimReference%7D/packages"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

curl 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/profiles/%7BprofileReference%7D/esims/%7BesimReference%7D/packages"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

{
  "data": {
    "profileReference": "string",
    "externalProfileId": "my-customer-123",
    "esimReference": "123456000000000001",
    "iccid": "89012345678901234567",
    "packages": [
      {
        "packageReference": "C123456XYZDUSR_A1B2C3D4",
        "externalTransactionId": "order-12345",
        "planReference": "C123456XYZDUSR",
        "type": "data",
        "countryCode": "US",
        "status": "active",
        "recurring": true,
        "activatedAt": "2026-01-15T09:30:00Z",
        "expiresAt": "2026-01-15T09:30:00Z",
        "createdAt": "2026-01-15T09:30:00Z"
      }
    ]
  },
  "pagination": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "MjAyNC0wMS0xNVQxMDowMDowMC4wMDBaOjQy"
  }
}

{
  "type": "https://developers.firsty.app/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing bearer token"
}