Country Phone Codes API Documentation

V1

/api/v1

First stable version for country phone code lookups.

GET /api/v1/country-phone-codes Auth Required

List Country Phone Codes

Returns country calling codes with optional filters for country name, ISO 3166-1 alpha-2 code, and calling code.

Authentication

X-Api-Key: your_api_key

Query Parameters

Name	Type	Required	Example	Description
`q`	string	optional	`turkey`	Keyword search in country name, ISO code, and calling code.
`iso2`	string	optional	`TR`	ISO 3166-1 alpha-2 country code filter.
`calling_code`	string	optional	`+90`	International calling code filter. A leading plus sign is optional.
`per_page`	integer	optional	`10`	Page size between 1 and 250.

Request Example

GET /api/v1/country-phone-codes?q=turkey&per_page=10

Response Example

{
    "success": true,
    "message": "Country phone codes fetched successfully.",
    "data": {
        "items": [
            {
                "id": 1,
                "name": "Turkey",
                "iso2": "TR",
                "calling_code": "+90",
                "calling_code_digits": "90",
                "area_codes": null,
                "national_prefix": null,
                "priority": 0
            }
        ],
        "count": 1,
        "total": 1,
        "current_page": 1,
        "last_page": 1,
        "per_page": 10,
        "filters": {
            "q": "turkey",
            "iso2": null,
            "calling_code": null
        }
    }
}

Error Response

{
    "success": false,
    "message": "Invalid API key.",
    "error_code": "INVALID_API_KEY"
}

GET /api/v1/country-phone-codes/all Auth Required

List All Country Phone Codes

Returns the full country calling code list without pagination.

Authentication

X-Api-Key: your_api_key

Request Example

GET /api/v1/country-phone-codes/all

Response Example

{
    "success": true,
    "message": "All country phone codes fetched successfully.",
    "data": {
        "countries": [
            {
                "id": 1,
                "name": "Turkey",
                "iso2": "TR",
                "calling_code": "+90",
                "calling_code_digits": "90",
                "area_codes": null,
                "national_prefix": null,
                "priority": 0
            },
            {
                "id": 2,
                "name": "United States",
                "iso2": "US",
                "calling_code": "+1",
                "calling_code_digits": "1",
                "area_codes": null,
                "national_prefix": null,
                "priority": 0
            }
        ],
        "count": 244
    }
}

Error Response

{
    "success": false,
    "message": "Invalid API key.",
    "error_code": "INVALID_API_KEY"
}

GET /api/v1/country-phone-codes/{iso2} Auth Required

Get Country Phone Code

Returns one country phone code record by ISO 3166-1 alpha-2 code. Example: /country-phone-codes/TR

Authentication

X-Api-Key: your_api_key

Path Parameters

Name	Type	Required	Example	Description
`iso2`	string	required	`TR`	ISO 3166-1 alpha-2 country code.

Request Example

GET /api/v1/country-phone-codes/TR

Response Example

{
    "success": true,
    "message": "Country phone code fetched successfully.",
    "data": {
        "id": 1,
        "name": "Turkey",
        "iso2": "TR",
        "calling_code": "+90",
        "calling_code_digits": "90",
        "area_codes": null,
        "national_prefix": null,
        "priority": 0
    }
}

Error Response

{
    "success": false,
    "message": "Country phone code not found.",
    "error_code": "COUNTRY_PHONE_CODE_NOT_FOUND"
}