Countries

Retrieve the list of countries supported by the Stream API.

Endpoint

GET /countries

Description

Fetch all available countries that can be used in address fields throughout the API. Each country has a unique ID that should be used when specifying country information in addresses.

Query Parameters

Parameter	Type	Required	Description
show_all	boolean	No	Set to true to not paginate the results and return all countries

Request Example

curl -X GET \
  "https://orders-production.vatit-stream.com/client_api/v2/countries?show_all=true" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Success Response (200 OK)

[
  {
    "id": 1,
    "name": "Afghanistan",
    "iso_code_2": "AF"
  },
  {
    "id": 2,
    "name": "Albania",
    "iso_code_2": "AL"
  },
  {
    "id": 3,
    "name": "Algeria",
    "iso_code_2": "DZ"
  },
  {
    "id": 70,
    "name": "United Kingdom",
    "iso_code_2": "GB"
  },
  {
    "id": 226,
    "name": "South Africa",
    "iso_code_2": "ZA"
  },
  {
    "id": 254,
    "name": "United States",
    "iso_code_2": "US"
  }
]

Response Fields

Field	Type	Description
id	integer	Unique identifier for the country (use this in address objects)
name	string	Full name of the country
iso_code_2	string	Two-letter ISO country code

Usage in Other Endpoints

The country id returned from this endpoint should be used in the following places:

Address Objects

When creating addresses for orders and quotes:

{
  "origin_address": {
    "name": "John Doe",
    "address_1": "123 Main Street",
    "city": "Johannesburg",
    "province": "Gauteng",
    "postal_code": "2196",
    "country_id": 226,
    "email": "john@example.com",
    "phone": "+27123456789"
  }
}

HS Codes

When specifying country of origin for goods:

{
  "hs_codes": [
    {
      "code": "100322",
      "cost": "100",
      "description": "networking equipment",
      "quantity": 5,
      "weight": 1.1,
      "country_id": 5
    }
  ]
}

Important Notes

• Country IDs: Always use the country id (integer) in API requests, not the ISO code or name
• Address Validation: Using the correct country ID is essential for address validation and shipping calculations
• Shipping Coverage: Not all countries may be available for all shipping services - check with your Stream representative for coverage details
• Import/Export Codes: Different countries require different import/export codes (e.g., EIN for USA, EORI for UK, Import/Export numbers for South Africa)
• Pagination: By default, the response is paginated. Use show_all=true to get all countries in a single response

Common Country IDs

Here are some commonly used country IDs for quick reference:

Country	ID	ISO Code
South Africa	226	ZA
United Kingdom	70	GB
United States	254	US
Germany	81	DE
France	76	FR
Australia	14	AU
Canada	39	CA

Error Responses

401 Unauthorized

Access token is missing or invalid.

Caching Recommendations

Since country data rarely changes, consider caching this data in your application to reduce API calls. Update your cache periodically (e.g., daily or weekly) to ensure you have the latest country information.