Number

Release a number

Releases a phone number from a service. The number status will be set to 'released' and it will no longer be associated with the service.

delete/number/{profileReference}/{numberId}

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)

numberIdintegerrequired

The phone number assignment's unique identifier (positive integer)

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

204Number released successfully

400Bad request - invalid parameters 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/number/{profileReference}/{numberId}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Idempotency-Key: <x-idempotency-key>'

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

requests.delete(
    "https://connect.firsty.app/api/v3/number/{profileReference}/{numberId}",
    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/number/{profileReference}/{numberId}', [
  '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/number/%7BprofileReference%7D/%7BnumberId%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/number/{profileReference}/{numberId}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Idempotency-Key: <x-idempotency-key>'

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

requests.delete(
    "https://connect.test.firsty.app/api/v3/number/{profileReference}/{numberId}",
    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/number/{profileReference}/{numberId}', [
  '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/number/%7BprofileReference%7D/%7BnumberId%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

{
  "type": "https://developers.firsty.app/errors/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Request contains invalid fields",
  "errors": [
    {
      "field": "planReference",
      "detail": "Must be a valid 14-character plan reference"
    }
  ]
}