Number

List number assignments

Retrieves all phone numbers allocated to a specific eSIM by its eSIM reference.

get/number/{profileReference}/assignments

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)

Query parameters

esimReferencestringrequired

eSIM reference identifier (18-digit opaque token)

Responses

200List of numbers for the serviceapplication/json

Show response body

dataarray of object

Show properties

assignmentIdinteger

Unique identifier for the number assignment

profileReferencestring

msisdnstring

countryCodestring

typestring

local: Local/landline number
mobile: Mobile number
tollfree: Toll-free number

Optionslocalmobiletollfree

statusstring

active: Number is active and operational
suspended: Number is temporarily suspended
released: Number has been released

Optionsactivesuspendedreleased

isPrimaryboolean

sourcestring

Source of the number (from pool or porting)

Optionspoolporting

createdAtstring · date-time

updatedAtstring · date-time

401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 404Resource not found 429Rate limit exceeded 500Internal server error

Request

curl 'https://connect.firsty.app/api/v3/number/{profileReference}/assignments?esimReference=123456000000000001' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.firsty.app/api/v3/number/{profileReference}/assignments?esimReference=123456000000000001', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.get(
    "https://connect.firsty.app/api/v3/number/{profileReference}/assignments",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    },
    params={
      "esimReference": "123456000000000001"
    }
)

$client = new GuzzleHttp\Client();

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

package main

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

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/number/%7BprofileReference%7D/assignments?esimReference=123456000000000001"

	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/number/{profileReference}/assignments?esimReference=123456000000000001' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.test.firsty.app/api/v3/number/{profileReference}/assignments?esimReference=123456000000000001', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

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

$client = new GuzzleHttp\Client();

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

package main

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

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/number/%7BprofileReference%7D/assignments?esimReference=123456000000000001"

	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": [
    {
      "assignmentId": 12345,
      "profileReference": "1234567890123456",
      "msisdn": "+14155551234",
      "countryCode": "US",
      "type": "local",
      "status": "active",
      "isPrimary": true,
      "source": "pool",
      "createdAt": "2026-01-15T09:30:00Z",
      "updatedAt": "2026-01-15T09:30:00Z"
    }
  ]
}

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