eSIMExperimental

List eSIM status history

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.

Every failure is its own faulted entry, so a failure on an eSIM that is already faulted carries previousStatus: faulted.

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 EsimUpdate

Status changes, newest first

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

statusstring

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

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

sourcestring

What kind of actor recorded the change.

Optionsapiwebhooksyncmanualadmin

reasonstring | null

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_interruptedprofile_rejecteddevice_unspecified_errorinstall_failedunknownnull

changedAtstring · date-time

paginationobject

Show properties

limitinteger

Maximum items per page

hasMoreboolean

Whether there are more items after this page

nextCursorstring | null

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. A `429` can also arrive without these headers or this body; handle it by its status code.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/{profileReference}/esims/{esimReference}/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/updates"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.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/{profileReference}/esims/{esimReference}/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/updates"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.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",
  "code": "unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing bearer token"
}