Developer docs
Guide · Clay · HTTP API

Use Taxora in Clay (HTTP API)

Find the EU VAT ID for every company in a Clay table. Clay sends company name, address and country to Taxora's reverse VAT lookup; Taxora returns the VAT ID, the registered name and address, the tax authority's verdict and a match score – ready to map into columns.

Before you start

  • Smart Enrichment must be active on your Taxora account. Without it, the lookup answers 403 (smart_enrichment_not_active).
  • An API key: Taxora app → Developer → API Keys. It is shown only once, so copy it straight away.
  • API credentials for Clay: Taxora app → Developer → Client ID + Secret. Create a separate one just for Clay.
  • A Clay table with at least a company name and a two-letter country code (ISO 3166-1, e.g. DE, FR, AT). Street, postal code and city are optional but improve the hit rate.

Get an access token (once)

Every lookup needs two headers: your API key and a Bearer token. Clay cannot log in by itself, so create the token once – with curl, Postman or a one-off HTTP API call in Clay – using your Clay credentials.

Request
POST https://api.taxora.io/v1/login
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "password": "YOUR_CLIENT_SECRET",
  "device_name": "clay",
  "remember": true
}
Response
{
  "success": true,
  "data": {
    "access_token": "123|AbCdEf…",
    "token_type": "Bearer",
    "expires_in": null
  }
}

With "remember": true the token does not expire (expires_in is null), so you can paste it into Clay once. Without it, the token is only valid for 60 minutes. Treat the token like a password.

Add an HTTP API column for the lookup

In your Clay table, add an enrichment column of type HTTP API and fill it in like this:

  • SettingMethod
    ValuePOST
  • SettingEndpoint
    Valuehttps://api.taxora.io/v1/smart-enrichment
  • SettingHeaders
    Valuex-api-key: YOUR_API_KEY
    Authorization: Bearer YOUR_ACCESS_TOKEN
    Content-Type: application/json
Body (JSON)
{
  "companyName": "{{Company Name}}",
  "street": "{{Street}}",
  "postalCode": "{{Postal Code}}",
  "city": "{{City}}",
  "country": "{{Country Code}}"
}

Replace each placeholder in double curly braces with a reference to the matching column of your Clay table. companyName and country are required; leave out street, postalCode or city if you don't have them. Optional: add "mode": "complex" for hard cases – two independent searches cross-checked against the tax authority, higher hit rate, counts as two checks by default.

Read the answer

If Taxora can answer from data it has already verified, you get the result straight away with HTTP 200:

Response 200 – result right away (shortened)
{
  "jobId": "9b2f6c1e-4d7a-4b8e-a3c5-1f2e3d4c5b6a",
  "status": "found",
  "vatNumber": "ATU12345678",
  "vatValid": true,
  "confidence": 96,
  "nameMatch": "ok",
  "officialName": "Example Company GmbH",
  "officialAddress": {
    "street": "Hauptstraße 10",
    "postal_code": "1010",
    "city": "Wien",
    "country": "AT"
  },
  "matchedCompanyName": "Example Company GmbH",
  "matchedAddress": "Hauptstraße 10, 1010 Wien, AT",
  "country": "AT",
  "sourceUrl": "https://www.example.at/impressum",
  "mode": "default"
}

Otherwise Taxora researches the company and confirms the number with the tax authority. Then you get HTTP 202 with a jobId and the status processing. Keep the jobId in its own column.

Response 202 – still processing
{
  "jobId": "9b2f6c1e-4d7a-4b8e-a3c5-1f2e3d4c5b6a",
  "status": "processing"
}

Fetch processing results with a second column

Add a second HTTP API column that fetches the job by its jobId (same headers, method GET). For a single lookup it returns the same flat result as above.

Request
GET https://api.taxora.io/v1/smart-enrichment/{{jobId}}
x-api-key: YOUR_API_KEY
Authorization: Bearer YOUR_ACCESS_TOKEN

Let this column run only for rows whose status is processing or queued. A lookup usually takes a few seconds per row; run the column again for rows that are still processing.

Map the fields to Clay columns

Pick these fields from the JSON response and add them as columns:

  • Response fieldvatNumber
    Clay columnVAT ID
    MeaningThe VAT ID found, e.g. ATU12345678. Only set when status is found.
  • Response fieldstatus
    Clay columnLookup status
    Meaningfound, no_vat_exists, not_found or processing – see below.
  • Response fieldvatValid
    Clay columnValid (tax authority)
    MeaningThe tax authority's verdict on the number (VIES, BZSt, FinanzOnline or national register). Empty when no official check ran.
  • Response fieldofficialName
    Clay columnRegistered name
    MeaningThe name the register has the number under. Use matchedCompanyName where the register discloses no name.
  • Response fieldofficialAddress (street, postal_code, city, country)
    Clay columnRegistered address
    MeaningThe registered address, field by field. matchedAddress has it as one line.
  • Response fieldconfidence
    Clay columnMatch score
    Meaning0–100: how sure the match between your record and the company is.
  • Response fieldnameMatch
    Clay columnName check
    Meaningok = your name matches the register; mismatch = it does not (check registeredOwner, e.g. for sole proprietors).
  • Response fieldsourceUrl
    Clay columnSource
    MeaningThe page the VAT ID was read from, usually the company's legal notice.
  • Response fieldtaxNumber + taxNumberLabel
    Clay columnLocal tax number
    MeaningThe domestic number (SIREN, NIP, Partita IVA …) where there is one.

What the status means

  • statusfound
    MeaningA VAT ID was found and confirmed.
  • statusno_vat_exists
    MeaningThe company was identified but legitimately has no VAT ID. Not an error.
  • statusnot_found
    MeaningNo match was certain enough. Taxora returns not_found instead of guessing; rejectedCandidates lists numbers that were named but failed the official check.
  • statusprocessing / queued
    MeaningStill running – fetch it again with the jobId (step 4).
  • statusfailed
    MeaningThe job failed. Run the lookup again or contact support.

Errors you may see

  • HTTP401
    MeaningAPI key or token missing or wrong – check both headers. A sandbox key only works against sandbox.taxora.io, a live key only against api.taxora.io.
  • HTTP403
    MeaningSmart Enrichment is not active on your account (code smart_enrichment_not_active), or the API key is invalid.
  • HTTP422
    MeaningInvalid input, e.g. companyName missing or country not a two-letter code.
  • HTTP429
    MeaningYour monthly limit or start credit is used up (smart_enrichment_quota_exceeded, smart_enrichment_trial_exhausted).

Good to know

  • Country must be a two-letter code. If your table has country names ("Germany"), add a Clay formula column that turns them into codes first.
  • Every lookup counts as one check, whatever the result – found, no_vat_exists or not_found. Each run of the lookup column sends a new lookup, so run it only on rows that still need a VAT ID.
  • The full field list, including registerFacts for Spain and France and addressQuality, is in the OpenAPI reference on the developer page.
  • Testing first? Use the sandbox base URL https://sandbox.taxora.io/v1 with a sandbox API key and sandbox credentials. The sandbox runs real lookups.

Set it up in your account

Create your API key and Clay credentials under Developer in the Taxora app. See pricing. Questions? Write to [email protected].

Open Taxora