API

REST API with per-unit unlocks. Searches never return contact data.

OpenAPI 3.1 (JSON)

Authentication

Create a key in your account (Test or Live). Send it as Authorization: Bearer ibd_…. Keys are shown once; we store only a hash.

Endpoints

• POST /companies/search — basic data and availability
• POST /contacts/reveal — reveal email/phone; 3 API credits per email and 4 per phone delivered
• POST /contacts/bulk-reveal → GET /jobs/{id} — async batches
• GET /balance, GET /usage

Billing rules

• The API uses its own API credits, bought in API packs and separate from web credits. API prices
• Each delivered email costs 3 API credits and each phone 4. Only delivered fields are charged.
• Missing data is never charged. Re-requesting a field you already own is free (web and API share permissions).
• Name resolution with several matches returns candidates (HTTP 300) without charging.
• Later updates of a purchased field do not trigger a new charge (policy configurable before launch).

cURL

curl -X POST https://iberiadata.com/api/v1/contacts/reveal \
  -H "Authorization: Bearer ibd_test_xxxxxxxx_..." \
  -H "Content-Type: application/json" \
  -d '{"id":"<record_id>","fields":["email","phone"]}'

JavaScript

const r = await fetch("https://iberiadata.com/api/v1/contacts/reveal", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.IBERIADATA_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Panadería Ejemplo SL", province: "28", fields: ["email"] }),
});
const data = await r.json();
if (r.status === 300) console.log("candidates:", data.candidates); // varias coincidencias: no se cobra
else console.log(data.delivered, data.consumed, data.balance);

Python

import os, requests
r = requests.post("https://iberiadata.com/api/v1/contacts/reveal",
    headers={"Authorization": f"Bearer {os.environ['IBERIADATA_KEY']}"},
    json={"id": "<record_id>", "fields": ["phone"]})
print(r.status_code, r.json())

Connect from Clay (HTTP API action)

1. In Clay, add an enrichment column → “HTTP API”.
2. Method: POST · URL: https://iberiadata.com/api/v1/contacts/reveal
3. Headers: Authorization: Bearer {{API key}} · Content-Type: application/json
4. Body: {"name": "{{Company name}}", "province": "{{Province code}}", "fields": ["email"]}
5. Map delivered.email to a column. Handle status 300 (candidates) and 402 (balance).

This is a generic HTTP integration guide; there is no official partnership with Clay.

Licence of use

Data obtained through the API are licensed for the internal use of the account holder's organisation only. Reselling, sublicensing, redistributing or incorporating them into products offered to third parties is prohibited and leads to immediate key revocation. Terms, clause 3.

Limits

Per key and per account: per minute, day and month; batch size and concurrent jobs. Responses include X-Request-Id. 429 includes Retry-After.