ProfileExperimental

List profiles

Retrieves a paginated list of the profiles belonging to the authenticated client, newest first. A profile is the identity every eSIM, package and usage record hangs off, so this is the entry point for building an index of your customers.

Pass externalProfileId to look up the profile you created for one of your own customer records, profileReference to confirm a reference you already hold, or iccid / esimReference to find the profile an eSIM currently belongs to. esimReference resolves the owner of an eSIM you only know from a balance webhook, which carries no profileReference.

Every filter matches exactly and combines with AND, so a profileReference and an iccid that point at different profiles return an empty list. Each filter narrows the profile rather than the eSIM, so an iccid and an esimReference naming two eSIMs of the same profile still match that profile. A filter that matches nothing is a 200 with data: [], never a 404.

Each profile carries its esim. lifecycleStatus returns the profiles whose esim has that lifecycle status.

get/profiles

Authorization

Authorization: Bearer {token} — an OAuth2 access token from the client-credentials flow. How authentication works

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.

lifecycleStatusstring

Return only the profiles whose esim has this lifecycle status

Optionspreactiveactivesuspendedterminatedfaultedstale

externalProfileIdstring

Return only the profiles carrying this external identifier

profileReferencestring

Return only the profile carrying this reference

iccidstring

Return only the profile that currently owns the eSIM with this ICCID. An eSIM reassigned to another profile is found under its new owner only.

esimReferencestring

Return only the profile that currently owns this eSIM. An eSIM reassigned to another profile is found under its new owner only.

Responses

200List of profilesapplication/json

Show response body

dataarray of ProfileSummaryoptional

Show properties

profileReferencestring

Profile reference identifier (16-digit opaque token)

externalProfileIdstring | null

Your own identifier for this profile, supplied when the eSIM was ordered

communicationLanguageCodestring | null

The language the customer is messaged in, as an ISO 639-1 code. null when none is set, in which case messages use the client's default language.

esimobject

The profile's eSIM: the one it is on, or its last one once every eSIM is terminated. During a swap it stays the addressed eSIM until the switch.

Show properties

profileReferencestring

externalProfileIdstring | null

The client's external profile ID if provided

esimReferencestring

eSIM reference identifier (18-digit opaque token)

iccidstring

eidstring | null

The eUICC Identifier (EID) if available

esimVariantstring | null

The eSIM's variant (e.g. 'travel'), or null if it has none.

statusstring

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

lifecycleStatusstring

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

createdAtstring · date-time

When the eSIM was assigned to the profile

updatedAtstring · date-time

createdAtstring · date-time

updatedAtstring · date-time

paginationobjectoptional

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

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

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

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.firsty.app/api/v3/profiles', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/profiles"

	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"))
    .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 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

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

$client = new GuzzleHttp\Client();

$response = $client->request('GET', 'https://connect.test.firsty.app/api/v3/profiles', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/profiles"

	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"))
    .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": "1234560000000001",
      "externalProfileId": "my-customer-123",
      "communicationLanguageCode": "nl",
      "esim": {
        "profileReference": "1234567890123456",
        "externalProfileId": "my-customer-123",
        "esimReference": "123456000000000001",
        "iccid": "89012345678901234567",
        "eid": "89049032000000000000000000000001",
        "esimVariant": "travel",
        "status": "released",
        "lifecycleStatus": "preactive",
        "createdAt": "2026-01-15T09:30:00Z",
        "updatedAt": "2026-01-15T09:30:00Z"
      },
      "createdAt": "2026-01-15T09:30:00Z",
      "updatedAt": "2026-01-15T09:30:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "MjAyNC0wMS0xNVQxMDowMDowMC4wMDBaOjQy"
  }
}

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