Profile

List profiles

Experimental. This endpoint is still settling — its request and response shape may change without a deprecation cycle.

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.

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.

statusstring

Filter by profile status

Optionsactivesuspendedterminated

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 ProfileSummary

Show properties

profileReferencestring

Profile reference identifier (16-digit opaque token)

externalProfileIdstring | null

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

statusstring

Lifecycle state of the profile.

Optionsactivesuspendedterminated

createdAtstring · date-time

updatedAtstring · date-time

paginationobject

Show properties

limitintegerrequired

Maximum items per page

hasMorebooleanrequired

Whether there are more items after this page

nextCursorstring | nullrequired

Opaque cursor token for the next page. Null when there are no more results.

401Unauthorized - missing or invalid API key 429Rate limit exceeded 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))

}

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

}

Response

{
  "data": [
    {
      "profileReference": "1234560000000001",
      "externalProfileId": "my-customer-123",
      "status": "active",
      "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",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing bearer token"
}