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

# La base de contacts

> Une personne, une fiche : e-mail, numéro, adresse et consentements.

Chaque projet a **une seule base de contacts**. Une personne y a une fiche, quelle que soit la liste par laquelle elle est arrivée : ses listes, ses consentements et son activité s’y lisent au même endroit.

| Champ | Description |
| - | - |
| `firstName`, `lastName`, `name` | Prénom, nom, ou nom complet. |
| `email` | Unique dans le projet. |
| `phone` | Unique dans le projet, ramené au format international. |
| `address` | `line`, `city`, `country` (facultatif). |
| `attributes` | Vos champs libres (`ville`, `segment`, `dateNaissance`…), utilisables comme [variables](https://docs.dexnotify.com/campagnes/personnalisation.md). |
| `tags` | Des étiquettes. |
| `listIds` | Les [listes](https://docs.dexnotify.com/contacts/listes.md) du contact. |
| `subscriptions` | Le consentement **par canal** : `email` et `sms`, chacun `subscribed`, `unsubscribed` ou `unknown`. |

Il faut au moins un e-mail **ou** un numéro.

## Créer un contact

```bash theme={null}
curl -X POST https://api.dexnotify.com/api/v1/contacts \
  -H "x-api-key: $DEXNOTIFY_CLE" -H "content-type: application/json" \
  -d '{
    "firstName": "Awa",
    "lastName": "Diop",
    "email": "awa.diop@exemple.sn",
    "phone": "77 123 45 67",
    "attributes": { "ville": "Dakar" },
    "listIds": ["6702…"],
    "subscriptions": { "email": "subscribed", "sms": "subscribed" }
  }'
```

Si l’e-mail ou le numéro est déjà connu : `409 CONFLICT`. Modifiez alors la fiche existante (`PATCH /api/v1/contacts/{id}`).

Portées : `contact:write` pour écrire, `contact:read` pour lire.

## Lire et chercher

| Route | Rend |
| - | - |
| `GET /api/v1/contacts?listId=&has=&unsubscribed=&q=` | les contacts, filtrés par liste, par canal présent (`email`, `phone`), par désinscription ou par recherche |
| `GET /api/v1/contacts/{id}` | une fiche |
| `GET /api/v1/contacts/{id}/activity` | les derniers SMS et e-mails reçus |

## Actions groupées

```json theme={null}
POST /api/v1/contacts/bulk
{ "action": "add_to_list", "contactIds": ["…", "…"], "listId": "6702…" }
```

`action` vaut `add_to_list`, `remove_from_list` ou `delete`.

## Consentement

Une campagne ne vise que les contacts **joignables** sur son canal : une adresse ou un numéro présent, et un consentement qui n’est pas `unsubscribed`. Un lien de désinscription ou une réponse STOP met à jour `subscriptions` d’elle-même. Voir [Désinscription](https://docs.dexnotify.com/campagnes/desabonnement.md).

> [!NOTE]
>
> Les contacts sont distincts des **utilisateurs** des applications mobiles (push, in-app), qui se gèrent par leur External ID. Voir [Utilisateurs et appareils](https://docs.dexnotify.com/push/utilisateurs.md).


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