eSIM

Update eSIM lifecycle

Manages the lifecycle of a specific eSIM by performing the specified operation.

Available operations:

suspend: Suspends an active eSIM. The eSIM can be reactivated later.
reactivate: Reactivates a suspended eSIM.
terminate: Permanently terminates an eSIM. This action cannot be undone.

terminated is terminal: once an eSIM reaches it, every operation returns 409, including a repeated terminate. A terminated eSIM cannot be suspended or reactivated, and no esim.lifecycle.* webhook is emitted for such a request.

patch/profiles/{profileReference}/esims/{esimReference}/lifecycle

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)

Headers

X-Idempotency-Keystring

Optional idempotency key for mutating requests (POST, PATCH). If provided, duplicate requests with the same key within 48 hours will return the cached original response without duplicating side effects.

Behavior:

Same key + same request body → returns cached response (prevents duplicate operations)
Same key + different request body → returns 422 error
Same key + in-flight request → returns 409 error with Retry-After header
Keys expire after 48 hours

Request Body Matching: Request bodies are compared using a deterministic fingerprint. The fingerprint is computed by canonicalizing the JSON (sorting object keys recursively) and hashing with SHA-256. This means:

{"a":1,"b":2} and {"b":2,"a":1} are treated as identical ✓
Whitespace differences are ignored ✓
URL parameters and headers are NOT included in the fingerprint

Best Practices:

Use UUIDs or client-generated unique strings
Store keys on your side to support retries
Don't reuse keys across different operations

Request body

application/json · required

operationstring

The lifecycle operation to perform. Either operation or action must be provided.

suspend: Temporarily suspend the eSIM (can be reactivated)
reactivate: Reactivate a suspended eSIM
terminate: Permanently terminate the eSIM (cannot be undone)

Optionssuspendreactivateterminate

actionstring

Alias for operation. Either operation or action must be provided.

Optionssuspendreactivateterminate

Responses

200eSIM lifecycle operation completed successfullyapplication/json

Show response body

dataobject

Show properties

profileReferencestring

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

statusstring

SM-DP+ profile state on the device.

released: Profile is available for download (QR code ready)
downloaded: Profile has been downloaded to the device
installed: Profile is installed on the eSIM chip
enabled: Profile is active on the device
disabled: Profile is installed but disabled on the device
deleted: Profile has been removed from the device
faulted: Profile encountered a provisioning or operational failure

Optionsreleaseddownloadedinstalledenableddisableddeletedfaulted

lifecycleStatusstring | null

IMSI connectivity lifecycle status. Null when the eSIM has not yet been assigned to a profile.

preactive: IMSI is provisioned but not yet active on the network
active: IMSI is active and connected to the network
suspended: IMSI is temporarily suspended from the network
terminated: IMSI has been permanently terminated
faulted: IMSI encountered a provisioning failure
stale: IMSI has a configuration mismatch (e.g., wrong base plan)

Optionspreactiveactivesuspendedterminatedfaultedstalenull

updatedAtstring · date-time

400Invalid operation or eSIM cannot transition to requested stateapplication/problem+json

Show response body

typestring · urirequired

URI reference to error documentation

titlestringrequired

Short, consistent error summary

statusintegerrequired

HTTP status code

detailstringrequired

Human-readable explanation specific to this occurrence

409Invalid state transitionapplication/problem+json

Show response body

typestring · urirequired

URI reference to error documentation

titlestringrequired

Short, consistent error summary

statusintegerrequired

HTTP status code

detailstringrequired

Human-readable explanation specific to this occurrence

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}/lifecycle' \
  --request PATCH \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "operation": "suspend",
  "action": "suspend"
}'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/lifecycle', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '<x-idempotency-key>'
  },
  body: JSON.stringify({
    operation: 'suspend',
    action: 'suspend'
  })
})

requests.patch(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/lifecycle",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "operation": "suspend",
      "action": "suspend"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/lifecycle', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'operation' => 'suspend',
    'action' => 'suspend'
  ]
]);

package main

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

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

	payload := strings.NewReader(`{
  "operation": "suspend",
  "action": "suspend"
}`)

	req, _ := http.NewRequest("PATCH", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")

	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}/lifecycle' \
  --request PATCH \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '{
  "operation": "suspend",
  "action": "suspend"
}'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/lifecycle', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': '<x-idempotency-key>'
  },
  body: JSON.stringify({
    operation: 'suspend',
    action: 'suspend'
  })
})

requests.patch(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/lifecycle",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json",
      "X-Idempotency-Key": "<x-idempotency-key>"
    },
    json={
      "operation": "suspend",
      "action": "suspend"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/lifecycle', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ],
  'json' => [
    'operation' => 'suspend',
    'action' => 'suspend'
  ]
]);

package main

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

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

	payload := strings.NewReader(`{
  "operation": "suspend",
  "action": "suspend"
}`)

	req, _ := http.NewRequest("PATCH", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")

	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",
    "esimReference": "123456000000000001",
    "iccid": "string",
    "status": "released",
    "lifecycleStatus": "preactive",
    "updatedAt": "2026-01-15T09:30:00Z"
  }
}

{
  "type": "https://developers.firsty.app/errors/bad-request",
  "title": "Bad request",
  "status": 400,
  "detail": "Invalid action. Must be one of: suspend, reactivate, terminate"
}

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

{
  "type": "https://developers.firsty.app/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "eSIM cannot be suspended from current state (currently active)"
}