ProfileExperimental

Get profile

Retrieves one of your profiles by its reference. A profile carries the identity an eSIM hangs off — your own externalProfileId — and its esim, whose lifecycle status is the profile's.

get/profiles/{profileReference}

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)

Responses

200The profileapplication/json

Show response body

dataobjectoptional

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

401Unauthorized - missing or invalid API key 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}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

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

$client = new GuzzleHttp\Client();

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

package main

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

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

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

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

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

$client = new GuzzleHttp\Client();

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

package main

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

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

	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/{profileReference}"))
    .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"
  }
}

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