> ## Documentation Index
> Fetch the complete documentation index at: https://docs.urbanora.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Recherche asynchrone, facturation au succès, aucun nom de fournisseur.

L'identification (qualify) donne l'entité et la personne. La mise en relation est un service **à la demande**, scope `contacts`.

**Facturation à l'aboutissement uniquement.** Une recherche sans canal exploitable n'est pas facturée. Un contact déjà livré n'est pas recompté. Les montants sont dans votre contrat.

Les traitements sont réalisés dans l'Union européenne, sur la base de sous-traitants sous accord de traitement des données.

## Canaux

| Canal API | Sens |
| - | - |
| `work_email` | E-mail professionnel nominatif |
| `mobile` | Ligne mobile |
| `linkedin` | URL de profil |
| `personal_email` | E-mail personnel |

D'autres canaux (téléphone d'établissement, site, adresse postale) peuvent apparaître dans le ledger une fois livrés. La référence OpenAPI liste les champs du canal (`type`, `state`, `visibility`, `reliability`, `value`).

## Soumettre une recherche

`POST /v1/contacts/find` — waterfall interne, asynchrone. Header **`Idempotency-Key` obligatoire**.

```bash curl theme={null}
curl -sS https://partner.urbanora.fr/v1/contacts/find \
  -H "X-Api-Key: $URBANORA_API_KEY" \
  -H "Idempotency-Key: 8f3c1a2e-4b91-4c0a-9e2d-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "company_default",
    "siren": "552032534",
    "channels": ["work_email", "mobile"]
  }'
```

```ts TypeScript theme={null}
const res = await fetch("https://partner.urbanora.fr/v1/contacts/find", {
  method: "POST",
  headers: {
    "X-Api-Key": process.env.URBANORA_API_KEY!,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    intent: "company_default",
    siren: "552032534",
    channels: ["work_email", "mobile"],
  }),
});
const { job_id, status, results } = await res.json();
```

`intent` : `company_default` (SIREN / raison sociale) ou `person` (nom, prénom, éventuellement `linkedin_url`). Vous pouvez rattacher un `imb_code` ou une `building_address` pour le contexte immeuble.

La réponse initiale peut déjà contenir des `results` (`mode: "already"` si le ledger connaît le contact). Sinon, gardez `job_id`.

## Suivre le job

`GET /v1/contacts/jobs/{jobId}` — `pending` · `running` · `succeeded` · `empty` · `failed` · `canceled`.

Un job d'une autre organisation → `404`. `empty` / `failed` : **0 €**.

## Ledger de la période

`GET /v1/contacts/delivered` — canaux livrés de la période en cours, sans nommer d'intermédiaire.

```bash theme={null}
curl -sS https://partner.urbanora.fr/v1/contacts/delivered \
  -H "X-Api-Key: $URBANORA_API_KEY"
```

Webhook de livraison : hors v1. Interrogez le job ou le ledger.

> [!WARNING]
>
> N'attendez pas, et n'exposez pas, le nom d'un fournisseur de contacts dans vos logs ou vos écrans. L'API ne le renvoie pas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.