eSIM

List eSIM status history

Experimental. This endpoint is still settling — its request and response shape may change without a deprecation cycle.

Retrieves the recorded status changes for an eSIM, newest first. Each entry names the status the eSIM moved to and the one it came from, so the current status returned by the eSIM endpoint is the status of the first entry.

reason is carried only by a faulted entry, where it states why the profile failed to reach the device using the same normalized cause as the esim.faulted webhook. That makes the cause recoverable after the fact, independently of whether the webhook delivery was processed. Every other entry carries reason: null: what happened is already given by status and previousStatus.

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

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.

Responses

200eSIM status historyapplication/json

Show response body

dataarray of EsimUpdaterequired

Status changes, newest first

Show properties

profileReferencestringrequired

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

statusstringrequired

The status the eSIM moved to. Current values are released, downloaded, installed, enabled, disabled, deleted and faulted; entries recorded by earlier imports may carry other values, so treat it as an open set.

previousStatusstring | nullrequired

The status the eSIM came from; null for the entry that first recorded a status.

sourcestringrequired

What kind of actor recorded the change.

Optionsapiwebhooksyncmanualadmin

reasonstring | nullrequired

Normalized cause of the failure, carried only by a faulted entry and matching the reason of the esim.faulted webhook. null on every other entry, and on a faulted entry recorded before its cause was classified.

Optionsdownload_order_expireduser_rejecteddownload_faileddevice_out_of_memoryalready_installedinstall_interruptedinstall_failedunknownnull

changedAtstring · date-timerequired

paginationobjectrequired

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}/updates' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

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

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/updates', [
  '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/updates"

	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}/updates' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

requests.get(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/updates",
    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}/updates', [
  '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/updates"

	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": "1234567890123456",
      "esimReference": "123456000000000001",
      "status": "faulted",
      "previousStatus": "downloaded",
      "source": "webhook",
      "reason": "device_out_of_memory",
      "changedAt": "2026-09-10T16:49:32Z"
    },
    {
      "profileReference": "1234567890123456",
      "esimReference": "123456000000000001",
      "status": "downloaded",
      "previousStatus": "released",
      "source": "webhook",
      "reason": null,
      "changedAt": "2026-09-10T16:49:28Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "hasMore": false,
    "nextCursor": null
  }
}

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