Countries

`GET /api/v1/countries`

Returns all active countries with ISO 3166 codes and dialing prefixes.

Request

curl {{host}}/api/v1/countries \
  -H "Authorization: Bearer <token>"

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type Country struct {
    ID            int    `json:"id"`
    Name          string `json:"name"`
    OfficialName  string `json:"official_name"`
    Alpha2        string `json:"alpha_2"`
    Alpha3        string `json:"alpha_3"`
    NumericCode   string `json:"numeric_code"`
    DialingPrefix string `json:"dialing_prefix"`
}

func main() {
    req, _ := http.NewRequest("GET", "{{host}}/api/v1/countries", nil)
    req.Header.Set("Authorization", "Bearer <token>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var countries []Country
    json.NewDecoder(resp.Body).Decode(&countries)

    for _, c := range countries {
        fmt.Printf("%s (%s)\n", c.Name, c.Alpha2)
    }
}

No query parameters.

Response

[
  {
    "id": 1,
    "name": "United States",
    "official_name": "United States of America",
    "alpha_2": "US",
    "alpha_3": "USA",
    "numeric_code": "840",
    "dialing_prefix": "+1"
  }
]

Response Fields

Key	Type	Description
`id`	integer	Unique country identifier
`name`	string	Common country name
`official_name`	string	Official country name
`alpha_2`	string	ISO 3166-1 alpha-2 code (2 characters, e.g. `US`)
`alpha_3`	string	ISO 3166-1 alpha-3 code (3 characters, e.g. `USA`)
`numeric_code`	string	ISO 3166-1 numeric code (e.g. `840`)
`dialing_prefix`	string	International dialing prefix (e.g. `+1`)

Errors

401 Unauthorized — Missing or invalid JWT token.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Authorization header required"
  }
}

403 Forbidden — Request IP not in whitelist.

{
  "error": {
    "name": "ForbiddenError",
    "code": "FORBIDDEN",
    "message": "IP address not authorized"
  }
}

500 Internal Server Error — Database query failed.

{
  "error": {
    "name": "InternalServerError",
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Failed to retrieve countries"
  }
}

`GET /api/v1/countries/:id`

Returns a single country by its ID.

Request

curl {{host}}/api/v1/countries/1 \
  -H "Authorization: Bearer <token>"

req, _ := http.NewRequest("GET", "{{host}}/api/v1/countries/1", nil)
req.Header.Set("Authorization", "Bearer <token>")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    panic(err)
}
defer resp.Body.Close()

var country Country
json.NewDecoder(resp.Body).Decode(&country)

fmt.Printf("%s (%s)\n", country.Name, country.Alpha2)

Request Parameters

Key	Type	Required	Description
`id`	integer	Yes	Country ID (path parameter). Must be between 1 and 2,147,483,647.

Response

{
  "id": 1,
  "name": "United States",
  "official_name": "United States of America",
  "alpha_2": "US",
  "alpha_3": "USA",
  "numeric_code": "840",
  "dialing_prefix": "+1"
}

Response fields are identical to the list endpoint above.

Errors

400 Bad Request — ID is not a valid integer or out of range.

{
  "error": {
    "name": "BadRequestError",
    "code": "BAD_REQUEST",
    "message": "Invalid country ID"
  }
}

404 Not Found — No country exists with this ID.

{
  "error": {
    "name": "NotFoundError",
    "code": "NOT_FOUND",
    "message": "Country not found"
  }
}

401 Unauthorized — Missing or invalid JWT token.

{
  "error": {
    "name": "UnauthorizedError",
    "code": "UNAUTHORIZED",
    "message": "Authorization header required"
  }
}

403 Forbidden — Request IP not in whitelist.

{
  "error": {
    "name": "ForbiddenError",
    "code": "FORBIDDEN",
    "message": "IP address not authorized"
  }
}

On this page