---
title: "Créer ou mettre à jour un client (upsert par SIRET)"
method: POST
path: "/clients"
tags: ["Clients"]
---

# Créer ou mettre à jour un client (upsert par SIRET)

`POST /clients`

## Request

- Base URL: `https://api.swipify.fr/api/v1`
- URL: `https://api.swipify.fr/api/v1/clients`
- Auth: API key in header `X-API-Key`

Crée un client ; si son SIRET/TVA/e-mail est déjà connu, met à jour la fiche au lieu d'en créer un doublon. Seuls les champs envoyés changent : un champ absent garde la valeur de la fiche, un champ envoyé vide l'efface. Scope requis : `clients:write`.

## Headers

- `Idempotency-Key` string

## Request body

- Customer: Client d'un document ou de `POST /clients`. Quand son SIRET, son numéro de TVA ou son e-mail (particulier) désigne une fiche connue, l'appel la met à jour champ par champ : un champ absent garde la valeur de la fiche, un champ envoyé vide (chaîne vide ou `null`) l'efface. Les quatre champs d'adresse suivent la même règle, sur l'adresse par défaut du client. Le reste de la fiche (autres contacts, notes, autres adresses) n'est pas touché.
  - `type` 'company' | 'individual', required
  - `name` string, nullable
  - `firstName` string, required
  - `lastName` string, required
  - `email` string, email, nullable: Sans accent avant l'arobase ; un domaine accentué est accepté.
  - `phone` string, nullable: Numéro français (06…, +33…, outre-mer compris) ou étranger avec son indicatif, 8 à 15 chiffres en tout, comme +32 470 12 34 56.
  - `address` string, nullable
  - `zipCode` string, nullable
  - `city` string, nullable
  - `country` string, nullable
  - `siret` string, nullable
  - `vatNumber` string, nullable: Numéro de TVA intracommunautaire, français (FR, clé de deux caractères, SIREN) ou d'un autre pays (les deux lettres du pays puis 2 à 13 caractères, dont au moins un chiffre), comme FR32123456789 ou BE0123456789. Espaces, points et tirets sont acceptés, le numéro est enregistré sans eux.
  - `formeJuridique` string, nullable

## Response `201`

Client créé ou mis à jour

- Client
  - `id` integer
  - `type` 'company' | 'individual'
  - `name` string
  - `email` string, nullable
  - `phone` string, nullable
  - `address` string, nullable
  - `siret` string, nullable
  - `vatNumber` string, nullable

## Other responses

- `400`: Données invalides
- `401`: Échec d'authentification : clé API manquante (`missing_api_key`) ou invalide/révoquée/expirée (`invalid_api_key`). Le client doit présenter une clé valide.
- `403`: Clé authentifiée mais non autorisée : scope insuffisant pour cette route (`scope_required`), ou organisation sans abonnement Pro actif (`pro_required`). `GET /me` reste accessible sans Pro pour diagnostiquer la clé.
- `409`: Conflit (ressource déjà existante, limite atteinte ; sur les routes idempotentes, Idempotency-Key déjà en cours)
- `422`: Idempotency-Key déjà utilisée pour une AUTRE requête (méthode/chemin divergents)
- `429`: Trop de requêtes (quota de la clé API, ou de l'organisation pour les analyses de document, dépassé pour la fenêtre courante)

---

[API](https://skmtc.dev/swipify/apis/swipify-api-publique.md) · [All operations](https://skmtc.dev/swipify/apis/swipify-api-publique/llms.txt) · [OpenAPI document](https://skmtc.dev/swipify/apis/swipify-api-publique/revisions/44c17201b479?raw)