REST Countries

Summary

REST Countries is a read-only JSON API for normalized country data: ISO codes, official and common names, capitals, currencies, languages, calling codes, time zones, flags, borders, political memberships, and related fields. Tealfabric has exercised the v5 HTTP interface against restapi-generic-1.1.0 (operation: receive, method: GET). It is a suitable supplemental source when a tenant needs richer or more frequently updated country records than the platform’s built-in Countries table.

Subscribe and obtain an API key from REST Countries. Tealfabric does not issue those keys and does not meter their quota.

Why use it with Tealfabric

The platform already stores a compact global Countries table (country_id, name, ISO_code, phone_prefix, cctld, full_data, serviceable) for forms, tenants, and billing. That table is enough for many workflows. REST Countries is useful when you also need:

• Currencies, time zones, official names in multiple languages, or flag assets
• Membership flags (EU, NATO, OECD, and similar)
• Capitals, coordinates, and border lists for logistics or risk scoring
• A vendor-maintained refresh cycle instead of a one-off import

Typical pattern: keep Tealfabric as the system of record for your entities and processes; pull REST Countries when a step, WebApp, or agent needs extra geography attributes. Tenant processes can read Countries; only the /root tenant can write that global table. Everyone else should persist extras in DataPool or entity-information.

What the API provides

The Countries API is GET-only. There is no create/update/delete surface. Responses are JSON. Authentication is a single bearer token in the Authorization header.

Current production base path:

https://api.restcountries.com/countries/v5

One country record exposes 90+ fields grouped into names, codes, geography, currencies, languages, flags, leaders, memberships, and locale conventions. Static fields are reviewed against ISO and UN sources. Dynamic fields such as population (and paid-plan fields such as current leaders) refresh on a multi-hour cadence.

Useful request patterns:

The vendor documents JSON:API-style envelopes: success payloads under data (with data.objects and data.meta for lists), failures under errors. Tealfabric’s generic REST connector wraps that JSON in its usual receive envelope (data, message_count, http_status). Unwrap one extra layer in step code.

Edge cases such as Kosovo, Taiwan, and Palestine are present, with recognition status and the ISO codes the standards bodies publish or omit. REST Countries exposes the facts; your process decides how to treat them.

Platform compatibility

We have run REST Countries v5 through Tealfabric’s generic REST connector. The combination that works:

Keep this integration GET / receive only. Do not set method to POST. On restapi-generic-1.1.0, a write verb remaps receive to send and changes the response envelope.

Paging belongs in the query argument (object or limit=25&offset=0 string), not in a request body. GET requests must not carry a body.

Create a separate read integration if you later add other REST Countries products. Leave executable_by_ai_agents off until you explicitly want Trace AI to call it.

Connector details: Generic REST API connector.

Connect from a process step

Replace YOUR_INTEGRATION_ID with the integration you created. The examples page the catalog until meta.more is false.

const integrationId = "YOUR_INTEGRATION_ID";
const PAGE_LIMIT = 25;

const countries: unknown[] = [];
let offset = 0;

while (true) {
  const result = (await integration.executeSync(integrationId, {
    operation: "receive",
    query: { limit: String(PAGE_LIMIT), offset: String(offset) },
  })) as Record<string, unknown>;

  if (!result?.success) {
    const err = result?.error;
    const message =
      typeof err === "string"
        ? err
        : err && typeof err === "object"
          ? String((err as Record<string, unknown>).message ?? "REST Countries receive failed")
          : "REST Countries receive failed";
    throw new Error(message);
  }

  const envelope = (result.data ?? {}) as Record<string, unknown>;
  let apiRoot: unknown = envelope.data;
  if (Array.isArray(apiRoot) && apiRoot.length === 1) {
    apiRoot = apiRoot[0];
  }
  const apiRootObj =
    apiRoot && typeof apiRoot === "object" && !Array.isArray(apiRoot)
      ? (apiRoot as Record<string, unknown>)
      : null;
  const payload =
    (apiRootObj?.data as Record<string, unknown> | undefined) ?? apiRootObj;
  const objects = Array.isArray(payload?.objects) ? payload.objects : [];
  const meta =
    payload?.meta && typeof payload.meta === "object"
      ? (payload.meta as Record<string, unknown>)
      : {};

  countries.push(...objects);
  if (meta.more !== true || objects.length === 0) {
    break;
  }
  offset = Number(meta.offset ?? offset) + Number(meta.limit ?? PAGE_LIMIT);
}

return { success: true, data: { countries, countries_count: countries.length } };

Single-country lookup (ISO alpha-2):

const result = await integration.executeSync(integrationId, {
  operation: "receive",
  path: "codes.alpha_2/FI",
});

Example use cases with Tealfabric

Cache a tenant country catalog in DataPool. A scheduled ProcessFlow pages /countries/v5, then upserts rows keyed by codes.alpha_2. Store names.common, codes.alpha_3, calling_codes, tlds, currencies, and memberships in a DataPool schema your WebApps and later steps can query without hitting the vendor on every form load.

Refresh the global Countries table (platform /root only). Map codes.alpha_2 → country_id, names.common → name, codes.alpha_3 → ISO_code, calling_codes → phone_prefix, tlds → cctld, and keep the vendor object in full_data. Tenant processes cannot write this table.

Enrich customer and entity records. When a CRM or entities row has only a country code, a step can receive with path: "codes.alpha_2/FI" (or the code from the record), then write currencies, calling codes, and official names onto entity-information or a DataPool schema used by billing and notifications.

WebApp country pickers. A WebApp that registers tenants or shipping addresses can call the same GET integration (or a process that caches the list in DataPool) so dropdowns show localized names and dialing prefixes without embedding a static JSON file.

Trade-bloc routing. Filter with memberships.eu=1 (or other membership fields), then branch ProcessFlow: VAT handling, restricted-goods checks, or which notification template to send.

KYC and onboarding. Combine the ISO code from a signup form with REST Countries recognition and official-name fields before creating a tenant or legal entity. Keep the decision in your step code; the API only supplies the reference data.

Agent lookup. Enable executable_by_ai_agents on the read integration so Trace AI can answer “what is the calling code for Namibia?” without granting write access to anything else. Point the integration description at https://restcountries.com/docs/countries so the agent sees the real query surface.

Flags and presentation. Country records include flag emoji and image URLs. WebApps and notification templates can use those URLs rather than storing image files in the tenant document store.

Pricing and accounts

Create an account and choose a plan on the vendor site: REST Countries plans.

Plans are usage-based. There is a free tier (hundreds of requests per month, slower sync, a small number of API keys) and paid tiers that raise monthly request caps, objects per response, sync frequency, SLA, and support. Yearly billing is discounted relative to month-to-month. Business-tier options include EU-region endpoints, webhooks on data changes, and team seats. REST Countries publishes the current numbers on that plans page; treat this paragraph as orientation, not a quote.

Quota and invoices stay with REST Countries. In Tealfabric you only store the bearer token on the integration (or in ProcessFlow Keystore if you prefer to inject it at runtime).

Limits to keep in mind

• The API is read-only. Do not treat it as a write-back target for Countries.
• Free-plan limit max is 100 (paid plans up to 500). Page with offset instead of requesting the catalog in one call.
• restapi-generic-1.1.0 receive is GET. Query parameters only.
• Do not send the REST Countries key to the browser. Call it from a process step or a server-side WebApp callback.
• Demo keys on restcountries.com are for exploration. Production integrations need your own key.

See also

• Partner services
• Generic REST API connector
• REST Countries documentation
• REST Countries plans
• Trace AI Agent
• ProcessFlow Keystore