# Apostille Requirement Lookup (US state x destination country) (`kevinserver24/apostille-requirement-lookup`) Actor

For a US document going to a specific country: apostille only, or full consular legalization? Computed live against the 1961 Hague Convention's real membership, plus the issuing US state's fee and processing time. Covers 10 states today.

- **URL**: https://apify.com/kevinserver24/apostille-requirement-lookup.md
- **Developed by:** [Kevin](https://apify.com/kevinserver24) (community)
- **Categories:** Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$100.00 / 1,000 lookup delivereds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Apostille Requirement Lookup (US state x destination country)

*An independent tool. It is not affiliated with, endorsed by, or operated by
any US state government, the Hague Conference on Private International Law
(HCCH), or any state Secretary of State. State fees and processing times are
each read from that state's own official page; Apostille Convention
membership is read from HCCH's own public status table, the treaty's
depositary.*

**A periodically refreshed bundle, not a live fetch per run.** A state
changes its apostille fee once a year at most; joining `data/states.json`
against `data/countries.json` happens live, on every run, against each
country's real entry-into-force date — so a country's accession that takes
effect between refreshes still flips this Actor's answer correctly the day
it happens, with no republish required. See `witnesses.py` for how drift in
either bundle is actually caught.

***

### Why this exists

A person or company preparing a US document for use abroad faces one binary
question with real financial consequences if answered wrong: does the
destination country accept a simple apostille (fast, cheap, one office), or
does it require full consular legalization (the apostille step, then US
federal authentication, then that country's own embassy or consulate — often
weeks longer and hundreds of dollars more)? No free aggregator answers this
for a specific (state, country) pair today — see `DOSSIER.md`, "WHY IT IS
RELEVANT". This Actor answers it, and adds the issuing state's own current
fee and processing time for the apostille step itself.

### What you get per row

| Field | Meaning |
|---|---|
| `state`, `state_name` | The 2-letter code and full name of the state you asked about |
| `country_requested`, `country_matched` | What you typed, and the canonical HCCH name it resolved to (`null` if no match) |
| `found` | Whether this pair resolved to real bundled data at all |
| `authentication_path` | `apostille_only` or `legalization_required` |
| `hague_member`, `hague_member_since` | Whether the destination is currently inside the 1961 Apostille Convention, and since when |
| `hague_pending_future_entry` | Set when the country has a FUTURE accession date that has not taken effect yet (e.g. Viet Nam, Thailand — see below) |
| `federal_dos_authentication_required`, `consulate_legalization_required` | The two extra steps a non-Hague destination requires beyond the state's own apostille |
| `state_issuing_agency` | The state office that issues the apostille |
| `state_fee_usd` | That office's current fee per document |
| `state_mailin_days_min/max`, `state_walkin_available`, `state_walkin_days_min/max`, `state_walkin_requires_appointment` | That state's own published processing time and submission options |
| `state_source_url`, `country_source_url` | Direct links to verify both halves yourself |
| `charged` / `not_charged_reason` | Whether this row cost you anything, and why not if it did not |

### Coverage — read this before you rely on it

**v1 covers 10 states: CA, TX, FL, NY, PA, IL, GA, OH, NC, MI** — the ten
most populous, together the large majority of US apostille demand. A state
outside this list resolves to `found: false`, delivered free, never
invented. **`document_type` is not modeled in v1** — a small number of
states waive or reduce the fee for specific document categories (e.g. Texas
for adoption paperwork); this Actor reports the general per-document fee
only. Country coverage is the full 130-member Hague Apostille Convention,
computed live against each member's real entry-into-force date, so it
self-corrects as new accessions take effect without a republish.

**What this Actor does NOT do:** for a `legalization_required` destination,
it tells you that federal authentication and consulate legalization are
both required, but it does not carry a specific consulate's own fee or
processing time — those vary by embassy and are not yet bundled.

***

### Input

```json
{
  "lookups": [
    {"state": "CA", "country": "France"},
    {"state": "TX", "country": "United Arab Emirates"}
  ]
}
```

Up to 20 pairs per run. Malformed entries (missing state or country) are
dropped silently rather than guessed at.

### Output

```json
{
  "state": "CA",
  "state_name": "California",
  "country_requested": "France",
  "country_matched": "France",
  "found": true,
  "state_issuing_agency": "California Secretary of State",
  "state_fee_usd": 20.0,
  "state_mailin_days_min": 21,
  "state_mailin_days_max": 42,
  "state_walkin_available": true,
  "state_walkin_days_min": 1,
  "state_walkin_days_max": 2,
  "state_walkin_requires_appointment": false,
  "state_source_url": "https://www.sos.ca.gov/notary/request-apostille",
  "state_data_as_of": "2026-08-29",
  "hague_member": true,
  "hague_member_since": "1965-01-24",
  "hague_pending_future_entry": null,
  "country_source_url": "https://www.hcch.net/en/instruments/conventions/status-table/?cid=41",
  "country_data_as_of": "2026-08-29",
  "authentication_path": "apostille_only",
  "federal_dos_authentication_required": false,
  "consulate_legalization_required": false,
  "charged": true,
  "not_charged_reason": ""
}
```

A `SUMMARY.json` lands in the key-value store with how many pairs were
requested, found, charged and free.

# Actor input Schema

## `lookups` (type: `array`):

Each item: the 2-letter US state that will issue the apostille (CA, TX, FL, NY, PA, IL, GA, OH, NC or MI -- the 10 states this Actor covers today) and the country the document is going to. Up to 20 pairs per run.

## Actor input object example

```json
{
  "lookups": [
    {
      "state": "CA",
      "country": "France"
    },
    {
      "state": "TX",
      "country": "United Arab Emirates"
    }
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

One row per requested pair, with the full joined answer.

## `resultsCsv` (type: `string`):

The same rows as a spreadsheet.

## `summary` (type: `string`):

How many pairs were requested, found, charged and free.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "lookups": [
        {
            "state": "CA",
            "country": "France"
        },
        {
            "state": "TX",
            "country": "United Arab Emirates"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("kevinserver24/apostille-requirement-lookup").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "lookups": [
        {
            "state": "CA",
            "country": "France",
        },
        {
            "state": "TX",
            "country": "United Arab Emirates",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("kevinserver24/apostille-requirement-lookup").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "lookups": [
    {
      "state": "CA",
      "country": "France"
    },
    {
      "state": "TX",
      "country": "United Arab Emirates"
    }
  ]
}' |
apify call kevinserver24/apostille-requirement-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kevinserver24/apostille-requirement-lookup"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/LGZVG2eE5jf7TrJsr/builds/fgiue7H6b91DiNPBV/openapi.json