Catalog

List available package plans

Returns a paginated list of available package plans. Each plan is specific to a region and has a recurring setting. Optionally filter by region to see only plans for that destination.

get/catalog/packages

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.

countryCodestring

ISO 3166-1 alpha-2 region code to filter plans by region

Responses

200List of package plansapplication/json

Show response body

dataarray of PackagePlan

Show properties

planReferencestring

Unique plan reference. Format: {C/S}{6 chars}{3 random}{type}{country}{renewable}. C = client-specific, S = shared. Type: D = data, M = SMS, V = voice. Last char: R = recurring, N = non-recurring.

namestring

typestring

Package type: data for mobile data, sms for text messaging, voice for calls

Optionsdatasmsvoice

capacityMbinteger | null

Data capacity in megabytes (for data packages, null for SMS/voice)

speedKbpsinteger | null

Speed cap in kilobits per second (for data packages, null for SMS/voice)

throttleCapacityMbinteger | null

Throttled data capacity in megabytes after main capacity is exhausted (null if no throttling)

throttleSpeedKbpsinteger | null

Throttled speed cap in kilobits per second after main capacity is exhausted (null if no throttling)

smsCountinteger | null

Number of SMS messages included (for SMS packages)

voiceSecondsinteger | null

Voice call seconds included (for voice packages)

validityMinutesinteger

Validity period in minutes

countryCodestring

Country or region code for this plan (e.g. 'US', 'NL', 'global_special')

recurringboolean

Whether this plan auto-renews when it expires

renewalPeriodMinutesinteger | null

Renewal cycle duration in minutes (null for non-recurring plans)

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.

400Bad request - invalid parameters 401Unauthorized - missing or invalid API key 403Forbidden - client does not have access to this resource 429Rate limit exceeded 500Internal server error

Request

curl https://connect.firsty.app/api/v3/catalog/packages \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

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

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

$client = new GuzzleHttp\Client();

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

package main

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

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

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

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

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

$client = new GuzzleHttp\Client();

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

package main

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

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

	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": [
    {
      "planReference": "C123456XYZDUSR",
      "name": "5GB - 30 Days - US",
      "type": "data",
      "capacityMb": 5120,
      "speedKbps": 100000,
      "throttleCapacityMb": 1024,
      "throttleSpeedKbps": 512,
      "smsCount": 100,
      "voiceSeconds": 3600,
      "validityMinutes": 43200,
      "countryCode": "US",
      "recurring": false,
      "renewalPeriodMinutes": 0
    }
  ],
  "pagination": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "MjAyNC0wMS0xNVQxMDowMDowMC4wMDBaOjQy"
  }
}

{
  "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"
    }
  ]
}