Documentation

API Reference

Everything you need to integrate with the Ambect API.

Authentication

All requests require an API key sent as a Bearer token in the Authorization header.

Authorization: Bearer en_your_api_key_here

API keys are prefixed with en_. Get a free key →

Endpoints

Base URL: https://api.ambect.com

POST

/v1/normalize/company

Normalize a company name through the full normalization pipeline.

POST

/v1/normalize/address

Parse and normalize a postal address. Optional geocoding on Growth and Business plans.

POST

/v1/normalize/phone

Parse and normalize a phone number to E.164, national, and international formats.

POST

/v1/normalize/email

Normalize an email address or URL. Detects disposable email domains.

POST

/v1/normalize/identifier

Normalize and validate a business identifier: SSN, EIN, EU VAT, SIC code, or stock ticker.

Company endpoint

Request

Send JSON with Content-Type: application/json.

POST /v1/normalize/company

{
  "name": "Berkshire Hathaway Inc.",  // required, 1–512 chars
  "country": "us"                     // optional, ISO 3166-1 alpha-2
}

Field	Type	Required	Description
name	string	Yes	The company name to normalize. Max 512 characters.
country	string	No	ISO 3166-1 alpha-2 country code. Enables country-specific pipeline rules.

Response

200 OK

{
  "data": {
    "canonical": "berkshire hathaway",
    "legal_type": "inc",
    "tokens": ["berkshire", "hathaway"]
  },
  "meta": {
    "pipeline": ["lowercase", "punctuation", "legal_suffix"],
    "country": "us",
    "confidence": 0.99,
    "ms": 1.3
  },
  "error": null
}

Pipeline stages

Runs up to 13 discrete stages. Only stages relevant to the input fire. The meta.pipeline array tells you exactly what ran.

transliterate

Convert non-Latin scripts to Latin equivalents by country.

lowercase

Normalize all characters to lowercase.

punctuation

Strip punctuation and special characters.

whitespace

Collapse and trim whitespace.

legal_suffix

Strip and record the legal entity suffix (LLC, Inc., Ltd., etc.) separately from the canonical name.

acronym_expand

Expand known acronyms to canonical long forms.

stop_words

Remove noise tokens by entity type and country.

synonym_map

Map synonyms to canonical tokens (3,000+ mappings).

sort_tokens

Sort remaining tokens for order-invariant matching.

Address endpoint

Request

POST /v1/normalize/address

{
  "address": "10 Downing Street, London, SW1A 2AA",  // required, 1–1024 chars
  "country": "gb",                                    // optional, ISO 3166-1 alpha-2
  "geocode": false                                    // optional, Growth+ only
}

Field	Type	Required	Description
address	string	Yes	Raw address string. Max 1,024 characters.
country	string	No	ISO 3166-1 alpha-2 hint. Improves parse accuracy for ambiguous addresses.
geocode	boolean	No	Request lat/lng geocoding. Defaults to `false`. Requires Growth or Business plan.

Response

200 OK

{
  "data": {
    "components": {
      "house_number": "10",
      "street": "Downing Street",
      "unit": null,
      "city": "London",
      "region": null,
      "postal_code": "SW1A 2AA",
      "country": "GB"
    },
    "normalized": "10 Downing Street London SW1A 2AA GB",
    "geocode": null
  },
  "meta": {
    "pipeline": ["validate_input", "parse", "normalize_components",
                 "country_context", "build_normalized"],
    "country": "GB",
    "confidence": 0.95,
    "ms": 2.1
  },
  "error": null
}

When geocode: true, the data.geocode object contains lat, lng, place_id, and formatted. Passing geocode: true on a Free or Starter plan returns a 403 with error.code: "geocode_tier_required".

Pipeline stages

validate_input

Check for non-empty input and validate the country hint against ISO 3166-1.

parse

Parse the address string into structured components — house number, street, city, region, postal code, country — across 100+ countries and all writing scripts.

normalize_components

Expand street and region abbreviations, title-case city names, and normalize country to ISO alpha-2.

country_context

Apply country-specific postal code formatting and validation (60+ countries).

build_normalized

Assemble a canonical single-line address string from the structured components.

geocode

Look up lat/lng via Google Maps API. Results are cached for 30 days. Growth and Business plans only.

Phone endpoint

Request

POST /v1/normalize/phone

{
  "phone": "+1 (415) 555-0123",  // required, 1–30 chars
  "country": "US"                // optional, ISO 3166-1 alpha-2 region hint
}

Field	Type	Required	Description
phone	string	Yes	Raw phone number in any format. Max 30 characters.
country	string	No	ISO 3166-1 alpha-2 default region (e.g. `US`, `GB`). Required for local numbers without a country code prefix.

Response

200 OK

{
  "data": {
    "e164": "+14155550123",
    "national": "(415) 555-0123",
    "international": "+1 415-555-0123",
    "country_code": 1,
    "region": "US",
    "type": "FIXED_LINE_OR_MOBILE"
  },
  "meta": {
    "pipeline": ["validate_input", "parse", "validate_format", "format"],
    "ms": 0.8
  },
  "error": null
}

The type field reflects the ITU-T line classification: MOBILE, FIXED_LINE, FIXED_LINE_OR_MOBILE, TOLL_FREE, VOIP, PREMIUM_RATE, and others.

Pipeline stages

validate_input

Reject empty or oversized input.

parse

Parse the raw string into a structured phone number, using the country hint as the default region when no international dialling prefix is present.

validate_format

Confirm the parsed number is structurally valid for its region.

format

Produce E.164, national, and international representations; classify line type (mobile, fixed, toll-free, VoIP, etc.).

Email endpoint

Accepts an email address or URL — the type is auto-detected. Returns a normalized form plus metadata.

Request

POST /v1/normalize/email

{
  "value": "User+Tag@GMAIL.COM"  // required, 1–512 chars — email or URL
}

Field	Type	Required	Description
value	string	Yes	Email address or URL to normalize. Max 512 characters.

Response — email

200 OK

{
  "data": {
    "normalized": "user+tag@gmail.com",
    "type": "email",
    "local": "user+tag",
    "domain": "gmail.com",
    "tld": "com",
    "disposable": false
  },
  "meta": {
    "pipeline": ["validate_input", "detect_type", "normalize", "enrich"],
    "ms": 0.5
  },
  "error": null
}

Response — URL

200 OK

{
  "data": {
    "normalized": "https://example.com/path",
    "type": "url",
    "scheme": "https",
    "host": "example.com",
    "path": "/path",
    "disposable": null
  },
  "meta": {
    "pipeline": ["validate_input", "detect_type", "normalize"],
    "ms": 0.3
  },
  "error": null
}

Pipeline stages

validate_input

Reject empty or oversized input.

detect_type

Classify input as email or URL based on structure.

normalize

Lowercase local part and domain; strip default ports and trailing slashes from URLs.

enrich

Email only — extract local part, domain, TLD, and flag disposable domains. Skipped for URLs.

Identifier endpoint

Normalizes and validates business identifiers. Supported types: us_ssn us_ein eu_vat us_sic ticker

Request

POST /v1/normalize/identifier

{
  "value": "045-85-7321",  // required, 1–64 chars
  "type": "us_ssn"         // optional — auto-detected if omitted
}

Field	Type	Required	Description
value	string	Yes	Raw identifier value. Max 64 characters.
type	string	No	Type hint. One of `us_ssn`, `us_ein`, `eu_vat`, `us_sic`, `ticker`. Auto-detected if omitted.

Response

200 OK — SSN

{
  "data": {
    "normalized": "045-85-7321",
    "type": "us_ssn",
    "valid": true,
    "country": null,
    "description": null
  },
  "meta": {
    "pipeline": ["validate_input", "detect_type", "validate_format", "format"],
    "ms": 0.4
  },
  "error": null
}

200 OK — EU VAT

{
  "data": {
    "normalized": "DE129273398",
    "type": "eu_vat",
    "valid": true,
    "country": "Germany",
    "description": null
  },
  "meta": {
    "pipeline": ["validate_input", "detect_type", "validate_format", "format"],
    "ms": 0.4
  },
  "error": null
}

200 OK — SIC code

{
  "data": {
    "normalized": "7372",
    "type": "us_sic",
    "valid": true,
    "country": null,
    "description": "Prepackaged Software"
  },
  "meta": {
    "pipeline": ["validate_input", "detect_type", "validate_format", "format"],
    "ms": 0.4
  },
  "error": null
}

Pipeline stages

validate_input

Reject empty or oversized input.

detect_type

Auto-detect identifier type (SSN, EIN, EU VAT, SIC, ticker) from structure, or accept an explicit type hint.

validate_format

Apply domain-specific validity rules (e.g. SSN area 000 invalid, EU VAT checksum must be valid for its country prefix).

format

Produce a canonical representation (e.g. dashed SSN, padded SIC, uppercase ticker) and attach contextual metadata: SIC industry description, EU VAT country name.

Rate limits

Two limits apply per API key across all endpoints. When either is exceeded, the request returns 429 Too Many Requests.

QPS (queries per second) — enforced via a token bucket with 5× burst capacity. Exceeding the sustained rate returns a Retry-After: 1 header.

Monthly cap — total requests per calendar month across all endpoints. See the Pricing page for overage options.

Plan	QPS	Monthly limit	Geocoding
Free	1 req/s	100 req / month	—
Starter	5 req/s	2,000 req / month	—
Growth	25 req/s	15,000 req / month	✓
Business	100 req/s	75,000 req / month	✓

Errors

400

Bad request — invalid or missing fields

401

Unauthorized — missing or invalid API key

403

Forbidden — feature not available on your plan

422

Validation error — input failed schema checks

429

Rate limit exceeded

500

Internal server error