eSIMExperimental

Update eSIM lifecycle

Changes the lifecycle of an eSIM.

Operations:

suspend: Suspends an active eSIM. Its packages stay active and their validity keeps running.
reactivate: Reactivates a suspended eSIM.
terminate: Permanently terminates an eSIM and ends the profile's packages outside a subscription. This cannot be undone.
activate: Activates a preactive eSIM or physical SIM for the first time.

Repeating suspend or reactivate on an eSIM already in that state changes nothing.

The change completes asynchronously: the response reports the eSIM's current lifecycleStatus, and the esim.lifecycle.* webhook reports the change once it is made.

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 by their JSON content. Object key order, including in nested objects, and whitespace do not affect matching. 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 request body matching

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)
activate: Activate a preactive eSIM or physical SIM for the first time

Optionssuspendreactivateterminateactivate

actionstring

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

Optionssuspendreactivateterminateactivate

Responses

200eSIM lifecycle operation completed successfullyapplication/json

Show response body

dataobjectoptional

Show properties

profileReferencestringoptional

esimReferencestringoptional

eSIM reference identifier (18-digit opaque token)

iccidstringoptional

statusstringoptional

Profile state on the device, as reported by the SM-DP+. A physical SIM has no download lifecycle and stays released; its service state is lifecycleStatus.

released: Ready for use; an eSIM profile in this state 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 failed to download or install on the device

Optionsreleaseddownloadedinstalledenableddisableddeletedfaulted

lifecycleStatusstringoptional

Network service state of the eSIM.

preactive: not live on the network yet
active: live on the network
suspended: temporarily without network service; can be reactivated
terminated: permanently without network service
faulted, stale: network service could not be set up; contact support

Optionspreactiveactivesuspendedterminatedfaultedstale

updatedAtstring · date-timeoptional

409The operation does not apply to the eSIM now: `invalid_state_transition`, `esim_terminated`, `esim_not_provisioned`, `esim_change_pending`, `esim_swap_pending` or `port_in_pending`.application/problem+json

Show response body

typestring · uri

URI reference to error documentation

titlestring

Short, consistent error summary

statusinteger

HTTP status code

detailstring

Human-readable explanation specific to this occurrence

codestring

Extensible enum. Machine-readable error slug. This is the field clients should branch on. The URI in type documents the code. Handle an unknown code by its HTTP status.

Examplesbad_requestvalidation_failedunauthorizedpayment_requiredfeature_not_enabledforbiddenbalance_not_foundesim_not_foundnot_foundnumber_registration_not_foundport_in_not_foundprofile_not_foundscheduled_action_not_foundsubscription_not_foundsubscription_plan_not_foundwebhook_endpoint_not_foundbalance_not_availablebalance_update_pendingconcurrent_modificationconflictesim_change_pendingesim_not_activeesim_not_provisionedesim_suspendedesim_swap_cooldownesim_swap_pendingesim_terminatedinvalid_state_transitionlimit_reachedno_esim_availablenumber_registration_pendingport_in_pendingservices_change_pendingservices_not_availablebalance_not_supportedbalance_operation_not_supportedbalance_update_refusedclient_transaction_id_reusedesim_variant_not_allowedesim_variant_not_swappableidempotency_key_reusedinsufficient_balancenumber_not_availablenumber_registration_not_supportedport_in_cancel_refusedporting_not_supportedservices_change_refusedservices_not_changeableservices_not_supportedsim_refused_by_networkunprocessable_entitylockedrate_limit_exceededinternal_errorbad_gatewayservice_unavailable

400Bad request - invalid parameters 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}/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/{profileReference}/esims/{esimReference}/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/lifecycle"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "<x-idempotency-key>")
    .method("PATCH", HttpRequest.BodyPublishers.ofString("{\n  \"operation\": \"suspend\",\n  \"action\": \"suspend\"\n}"))
    .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}/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/{profileReference}/esims/{esimReference}/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/lifecycle"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "<x-idempotency-key>")
    .method("PATCH", HttpRequest.BodyPublishers.ofString("{\n  \"operation\": \"suspend\",\n  \"action\": \"suspend\"\n}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.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/validation_failed",
  "code": "validation_failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "errors": [
    {
      "field": "planReference",
      "detail": "Must be a valid 14-character plan reference"
    }
  ]
}

{
  "type": "https://developers.firsty.app/errors/invalid_state_transition",
  "code": "invalid_state_transition",
  "title": "Conflict",
  "status": 409,
  "detail": "eSIM lifecycle is active; reactivate does not apply"
}