Packages

Remove a package

Removes a package from an eSIM. The package status will be set to 'removed'.

delete/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}

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)

packageReferencestringrequired

Package reference identifier (23-character 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

Responses

200Package removed successfully (idempotent - returns same result if already removed)application/json

Show response body

dataobject

Show properties

packageReferencestring

Package reference identifier (23-character opaque token)

statusstring

Optionsactivethrottledexhaustedexpiredremoved

updatedAtstring · date-time

401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 409Request with this idempotency key is still being processed 422Idempotency key was previously used with a different request body 429Rate limit exceeded 500Internal server error

Request

curl 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Idempotency-Key: <x-idempotency-key>'

fetch('https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key': '<x-idempotency-key>'
  }
})

requests.delete(
    "https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Idempotency-Key": "<x-idempotency-key>"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://connect.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ]
]);

package main

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

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

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

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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}/packages/{packageReference}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Idempotency-Key: <x-idempotency-key>'

fetch('https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key': '<x-idempotency-key>'
  }
})

requests.delete(
    "https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Idempotency-Key": "<x-idempotency-key>"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('DELETE', 'https://connect.test.firsty.app/api/v3/profiles/{profileReference}/esims/{esimReference}/packages/{packageReference}', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
    'X-Idempotency-Key' => '<x-idempotency-key>'
  ]
]);

package main

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

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

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

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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": {
    "packageReference": "C123456XYZDUSR_A1B2C3D4",
    "status": "active",
    "updatedAt": "2026-01-15T09:30:00Z"
  }
}

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