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 PackagePlanoptional

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

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

Examplesdatasmsvoice

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)

validityobject

How long a package of this plan stays valid.

Show properties

unitstring

Extensible enum. minute, day (24 hours) or month, a calendar month that ends on the same day of the month, or on the last day of a shorter month.

Examplesdaymonth

countinteger

renewalobject | null

How often a recurring plan's allowance renews. Null for a non-recurring plan.

Show properties

unitstring

Extensible enum. minute, day (24 hours) or month, a calendar month that ends on the same day of the month, or on the last day of a shorter month.

Examplesdaymonth

countinteger

alignmentstring

Extensible enum. Where the plan's validity and renewal boundaries fall. relative: every boundary is counted from the moment the package's validity starts. calendar: every boundary falls on the 1st of the month.

Examplesrelativecalendar

validityMinutesinteger

Use validity. The validity in minutes, a month counted as 30 days.

countryCodestring

Country or region code for this plan (e.g. 'NL', 'EU', 'global')

recurringboolean

Whether this plan auto-renews when it expires

renewalPeriodMinutesinteger | null

Use renewal. The renewal cycle in minutes, a month counted as 30 days; null for a non-recurring plan.

paginationobjectoptional

Show properties

limitinteger

Maximum items per page

hasMoreboolean

Whether there are more items after this page

nextCursorstring | null

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

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/catalog/packages"))
    .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/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))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/catalog/packages"))
    .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": [
    {
      "planReference": "C123456XYZDUSR",
      "name": "5GB - 30 Days - US",
      "type": "data",
      "capacityMb": 5120,
      "speedKbps": 100000,
      "throttleCapacityMb": 1024,
      "throttleSpeedKbps": 512,
      "smsCount": 100,
      "voiceSeconds": 3600,
      "validity": {
        "unit": "day",
        "count": 30
      },
      "renewal": {
        "unit": "day",
        "count": 30
      },
      "alignment": "relative",
      "validityMinutes": 43200,
      "countryCode": "US",
      "recurring": false,
      "renewalPeriodMinutes": null
    }
  ],
  "pagination": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "MjAyNC0wMS0xNVQxMDowMDowMC4wMDBaOjQy"
  }
}

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