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

searchstring

Case-insensitive text matched anywhere in a plan's name, plan reference, country code or region name. Empty matches every plan.

typesstring

Comma-separated package types to filter plans by, case-insensitive: data, sms, voice or voice_sms. Omit for every type.

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, or voice and SMS. Last char: R = recurring, N = non-recurring.

namestring

typestring

Extensible enum. Package type: data for mobile data, sms for text messaging, voice for calls, voice_sms for one allowance that calls and text messages both draw on.

Examplesdatasmsvoicevoice_sms

allowanceobject

What a package of the plan can use, for each renewal cycle of a recurring plan and for the whole validity of any other plan. Carries either count or unlimited, never both.

Show properties

unitstring

Extensible enum. Unit a package's amounts are expressed in, determined by the package type: mb for data, seconds for voice, sms for text messages and units for voice and SMS, where a call minute and a text message each count as one unit.

Examplesmbsecondssmsunits

countintegeroptional

The allowance in unit. Absent when the allowance is unlimited.

unlimitedbooleanoptional

Present, as true, when the allowance has no limit; count is then absent.

speedKbpsintegeroptional

Speed cap in kilobits per second. Absent when the speed is not capped.

throttleobjectoptional

Data the package keeps at a reduced speed once its allowance is used up. Carries either count or unlimited, never both. Absent when the plan has no reduced speed.

Show properties

countintegeroptional

The reduced-speed data, in the allowance's unit. Absent when it is unlimited.

unlimitedbooleanoptional

Present, as true, when the reduced-speed data has no limit; count is then absent.

speedKbpsinteger

The reduced speed in kilobits per second.

capacityMbinteger | nullDeprecated

Use allowance. The allowance of a data plan in megabytes; null for any other type or an unlimited plan.

speedKbpsinteger | nullDeprecated

Use allowance.speedKbps. Speed cap in kilobits per second; null when the speed is not capped.

throttleCapacityMbinteger | nullDeprecated

Use allowance.throttle. Reduced-speed data in megabytes once the allowance is used up; null when that data is unlimited or the plan has no reduced speed.

throttleSpeedKbpsinteger | nullDeprecated

Use allowance.throttle. Reduced speed in kilobits per second once the allowance is used up; null when the plan has no reduced speed.

smsCountinteger | nullDeprecated

Use allowance. The allowance of an SMS plan in messages; null for any other type or an unlimited plan.

voiceSecondsinteger | nullDeprecated

Use allowance. The allowance of a voice plan in seconds; null for any other type or an unlimited plan.

validityobject

How long a package of this plan stays valid; indefinite when its packages never expire.

Show properties

unitstring

Extensible enum. minute, day, month or indefinite. With relative alignment a day is 24 hours and a month ends on the same day of the month, or on the last day of a shorter month; with calendar alignment a day ends at midnight and a month at 00:00 on the 1st.

Examplesdaymonthindefinite

countinteger

renewalobject | null

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

Show properties

unitstring

Examplesdaymonthindefinite

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 at midnight, or at 00:00 on the 1st for a duration in months, in the local time of the plan's network; the first period is shorter and carries the plan's full allowance.

Examplesrelativecalendar

validityMinutesintegerDeprecated

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 | nullDeprecated

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

}

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(java.net.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 = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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

}

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
  .uri(java.net.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 = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "data": [
    {
      "planReference": "C123456XYZDUSR",
      "name": "5GB - 30 Days - US",
      "type": "data",
      "allowance": {
        "unit": "mb",
        "count": 5120,
        "speedKbps": 100000,
        "throttle": {
          "unlimited": true,
          "speedKbps": 512
        }
      },
      "capacityMb": 5120,
      "speedKbps": 100000,
      "throttleCapacityMb": null,
      "throttleSpeedKbps": 512,
      "smsCount": null,
      "voiceSeconds": null,
      "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"
    }
  ]
}