countries DB logo

Documentation

Backend Validation API

Server-side validation endpoints to verify country and subdivision codes with relationship checking

Validate country and subdivision codes on your server to ensure data integrity. Our validation API provides fast, reliable validation with detailed error messages and relationship checking for complex scenarios like parent-child subdivisions and country redirections.

Validation Features

  • Comprehensive code validation with format checking
  • Relationship checking (parent/child subdivisions)
  • Follow-related and follow-upward validation
  • Fast response times (sub-100ms when cached)
  • Secure API key authentication
  • Usage tracking and analytics
  • Detailed error messages for debugging
  • Multi-language error messages

API Endpoints

Complete reference for all validation endpoints with authentication, parameters, and response formats.

Country Validation

Validate country codes and check for upward relationships. This endpoint ensures the country exists and validates follow-upward rules.

Requirements for API to Work:

This example uses the following configuration:

Required

Authentication

All validation endpoints require authentication using your private API key. Include the API key in the Authorization header as a Bearer token: Authorization: Bearer YOUR_API_KEY. The base URL for all validation endpoints is https://api.countriesdb.com.

REQUIRED
All

Recommended

Content-Type Header

Include the Content-Type header for POST requests: Content-Type: application/json

RECOMMENDED
All

Example

Parameters

Basic country validation accepts the following parameters:

Required Parameters

codeTwo-letter country code (ISO 3166-1 alpha-2)
Bash · cURL
curl -X POST https://api.countriesdb.com/api/validate/country \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "US"}'
Response
Success Response
HTTP/1.1 200 OK
Content-Type: application/json

{"valid": true}

Subdivision Validation

Validate subdivision codes and check for parent-child relationships and redirections. This endpoint handles complex validation scenarios including follow-related and allow-parent-selection rules.

Requirements for API to Work:

This example uses the following configuration:

Required

Authentication

All validation endpoints require authentication using your private API key. Include the API key in the Authorization header as a Bearer token: Authorization: Bearer YOUR_API_KEY. The base URL for all validation endpoints is https://api.countriesdb.com.

REQUIRED
All

Recommended

Content-Type Header

Include the Content-Type header for POST requests: Content-Type: application/json

RECOMMENDED
All

Example

Parameters

Basic subdivision validation accepts the following parameters:

Required Parameters

countryTwo-letter country code (ISO 3166-1 alpha-2)

Optional Parameters

codeSubdivision code in format COUNTRY-CODE (can be empty if country has no subdivisions)
Bash · cURL
curl -X POST https://api.countriesdb.com/api/validate/subdivision \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "US-CA", "country": "US"}'
Response
Success Response
HTTP/1.1 200 OK
Content-Type: application/json

{"valid": true}