> For the complete documentation index, see [llms.txt](https://docs.abby.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abby.fr/reference-de-lapi/clients.md).

# Contacts

Créez et gérez les contacts, les clients particuliers de votre société.

Un client Abby est soit un **contact** (une personne), soit une **organisation** (une entreprise qui regroupe plusieurs contacts). Les routes de facturation attendent un `customerId` : c'est l'identifiant d'un contact ou celui d'une organisation. Les deux se créent séparément et s'utilisent de la même façon pour facturer.

Cette page traite des contacts. Pour les entreprises et leurs contacts, voir [Organisations](https://docs.abby.fr/reference-de-lapi/organisations.md).

{% hint style="info" %}
Chaque contact porte un booléen `test`. Il est en lecture seule : aucune route de création ou de mise à jour ne l'accepte. Les documents de facturation d'un contact de test héritent de cet indicateur.
{% endhint %}

## Créer un contact

`firstname` et `lastname` sont les seuls champs obligatoires. Le corps accepte aussi les adresses (`billingAddress`, `deliveryAddress`), les coordonnées bancaires (`bankInformations`) et les préférences (`preferences`). Gardez l'`id` renvoyé : c'est le `customerId` à passer ensuite aux routes de facturation (voir [Facturer un client](https://docs.abby.fr/guides/facturer-un-client.md)).

```bash
curl -X POST https://api.abby.fr/contact \
  -H "Authorization: Bearer $ABBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "emails": ["john.doe@example.com"],
    "phone": "+33123456789",
    "jobTitle": "Software Engineer",
    "notes": "Prefers email communication"
  }'
```

## POST /contact

> Create a new contact

```json
{"openapi":"3.0.0","info":{"title":"Abby Public API","version":"1.130.0+66756885474b"},"servers":[{"url":"https://api.abby.fr","description":"Production server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication. Pass your API key as a Bearer token."}},"schemas":{"CreateContactDto":{"type":"object","properties":{"firstname":{"type":"string","description":"The first name of the contact"},"lastname":{"type":"string","description":"The last name of the contact"},"phone":{"type":"string","description":"The phone number of the contact"},"jobTitle":{"type":"string","description":"The job title of the contact"},"emails":{"description":"The email addresses of the contact","type":"array","items":{"type":"string"}},"notes":{"type":"string","description":"Additional notes about the contact"},"billingAddress":{"description":"The billing address of the contact","allOf":[{"$ref":"#/components/schemas/ClientAddressDto"}]},"deliveryAddress":{"description":"The delivery address of the contact","allOf":[{"$ref":"#/components/schemas/ClientAddressDto"}]},"bankInformations":{"description":"The bank information of the contact","allOf":[{"$ref":"#/components/schemas/BankInformationsDto"}]},"preferences":{"description":"The preferences of the contact","allOf":[{"$ref":"#/components/schemas/ClientPreferencesDto"}]}},"required":["firstname","lastname"]},"ClientAddressDto":{"type":"object","properties":{"address":{"type":"string","description":"The street address of the client","nullable":true},"complement":{"type":"string","description":"Additional address information","nullable":true},"city":{"type":"string","description":"The city of the address","nullable":true},"zipCode":{"type":"string","description":"The zip code or postal code of the address","nullable":true},"state":{"type":"string","description":"The state or province of the address"},"country":{"description":"The country of the address","allOf":[{"$ref":"#/components/schemas/CountryCode"}]}},"required":["address","city","zipCode","country"]},"CountryCode":{"type":"string","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AN","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KR","XK","KP","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"],"description":"Country code of the address"},"BankInformationsDto":{"type":"object","properties":{"iban":{"type":"string","description":"International Bank Account Number"},"bic":{"type":"string","description":"Bank Identifier Code"},"holder":{"type":"string","description":"Name of the account holder"}},"required":["iban","bic","holder"]},"ClientPreferencesDto":{"type":"object","properties":{"language":{"description":"The client's preferred language for billing","allOf":[{"$ref":"#/components/schemas/BillingLocale"}]},"currency":{"description":"The client's preferred currency for transactions","allOf":[{"$ref":"#/components/schemas/CurrencyCode"}]},"paymentMethods":{"type":"array","description":"The client's preferred payment methods","items":{"$ref":"#/components/schemas/PaymentMethod"}}}},"BillingLocale":{"type":"string","enum":["fr","en","de","it","nl","pt","es"]},"CurrencyCode":{"type":"string","enum":["EUR","GBP","CHF","USD","AUD","CAD","JPY","CNH","CZK","DKK","BGN","PLN","HUF","RON","SEK","NOK","TRY","BRL","HKD","ILS","INR","KRW","MXN","XPF","XOF","XAF"],"description":"Preferred currency of the customer"},"PaymentMethod":{"type":"string","enum":["transfer","direct_debit","credit_card","cheque","universal_employment_service_cheque","cash","paypal","stripe","other"]},"ReadContactDto":{"type":"object","properties":{"id":{"type":"string","description":"Contact ID"},"emails":{"description":"Contact email addresses","type":"array","items":{"type":"string"}},"organization":{"description":"Organization information","allOf":[{"$ref":"#/components/schemas/ContactOrganizationDto"}]},"defaultContact":{"type":"boolean","description":"Whether this is the default contact"},"createdAt":{"type":"number","description":"Contact creation timestamp"},"archivedAt":{"type":"number","description":"Contact archival timestamp"},"hasBillings":{"type":"boolean","description":"Whether the contact has billings"},"test":{"type":"boolean","description":"Whether this is a test contact"},"phone":{"type":"string","description":"Contact phone number"},"firstname":{"type":"string","description":"Contact first name"},"lastname":{"type":"string","description":"Contact last name"},"billingAddress":{"description":"Billing address","allOf":[{"$ref":"#/components/schemas/ClientAddressDto"}]},"deliveryAddress":{"description":"Delivery address","allOf":[{"$ref":"#/components/schemas/ClientAddressDto"}]},"jobTitle":{"type":"string","description":"Contact job title"},"bankInformations":{"description":"Bank information","allOf":[{"$ref":"#/components/schemas/BankInformationsDto"}]},"hasTiersPrestation":{"type":"boolean","description":"Whether the contact has third-party services"},"notes":{"type":"string","description":"Additional notes about the contact"},"language":{"description":"Contact language preference","allOf":[{"$ref":"#/components/schemas/BillingLocale"}]},"currency":{"description":"Preferred currency","allOf":[{"$ref":"#/components/schemas/CurrencyCode"}]},"paymentMethods":{"type":"array","description":"Accepted payment methods","items":{"$ref":"#/components/schemas/PaymentMethod"}}},"required":["id","createdAt","hasBillings","test","firstname","lastname","hasTiersPrestation"]},"ContactOrganizationDto":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Organization name"},"archivedAt":{"type":"number","description":"Organization archival timestamp"}},"required":["id","name"]}}},"paths":{"/contact":{"post":{"operationId":"ContactController_createContact","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContactDto"}}}},"responses":{"201":{"description":"The contact has been successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadContactDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"}},"summary":"Create a new contact","tags":["contact"]}}}}
```

## Lire un contact

```bash
curl https://api.abby.fr/contact/$CONTACT_ID \
  -H "Authorization: Bearer $ABBY_API_KEY"
```

## GET /contact/{id}

> Get a contact by ID

```json
{"openapi":"3.0.0","info":{"title":"Abby Public API","version":"1.130.0+66756885474b"},"servers":[{"url":"https://api.abby.fr","description":"Production server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication. Pass your API key as a Bearer token."}},"schemas":{"ReadContactDto":{"type":"object","properties":{"id":{"type":"string","description":"Contact ID"},"emails":{"description":"Contact email addresses","type":"array","items":{"type":"string"}},"organization":{"description":"Organization information","allOf":[{"$ref":"#/components/schemas/ContactOrganizationDto"}]},"defaultContact":{"type":"boolean","description":"Whether this is the default contact"},"createdAt":{"type":"number","description":"Contact creation timestamp"},"archivedAt":{"type":"number","description":"Contact archival timestamp"},"hasBillings":{"type":"boolean","description":"Whether the contact has billings"},"test":{"type":"boolean","description":"Whether this is a test contact"},"phone":{"type":"string","description":"Contact phone number"},"firstname":{"type":"string","description":"Contact first name"},"lastname":{"type":"string","description":"Contact last name"},"billingAddress":{"description":"Billing address","allOf":[{"$ref":"#/components/schemas/ClientAddressDto"}]},"deliveryAddress":{"description":"Delivery address","allOf":[{"$ref":"#/components/schemas/ClientAddressDto"}]},"jobTitle":{"type":"string","description":"Contact job title"},"bankInformations":{"description":"Bank information","allOf":[{"$ref":"#/components/schemas/BankInformationsDto"}]},"hasTiersPrestation":{"type":"boolean","description":"Whether the contact has third-party services"},"notes":{"type":"string","description":"Additional notes about the contact"},"language":{"description":"Contact language preference","allOf":[{"$ref":"#/components/schemas/BillingLocale"}]},"currency":{"description":"Preferred currency","allOf":[{"$ref":"#/components/schemas/CurrencyCode"}]},"paymentMethods":{"type":"array","description":"Accepted payment methods","items":{"$ref":"#/components/schemas/PaymentMethod"}}},"required":["id","createdAt","hasBillings","test","firstname","lastname","hasTiersPrestation"]},"ContactOrganizationDto":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Organization name"},"archivedAt":{"type":"number","description":"Organization archival timestamp"}},"required":["id","name"]},"ClientAddressDto":{"type":"object","properties":{"address":{"type":"string","description":"The street address of the client","nullable":true},"complement":{"type":"string","description":"Additional address information","nullable":true},"city":{"type":"string","description":"The city of the address","nullable":true},"zipCode":{"type":"string","description":"The zip code or postal code of the address","nullable":true},"state":{"type":"string","description":"The state or province of the address"},"country":{"description":"The country of the address","allOf":[{"$ref":"#/components/schemas/CountryCode"}]}},"required":["address","city","zipCode","country"]},"CountryCode":{"type":"string","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AN","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KR","XK","KP","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"],"description":"Country code of the address"},"BankInformationsDto":{"type":"object","properties":{"iban":{"type":"string","description":"International Bank Account Number"},"bic":{"type":"string","description":"Bank Identifier Code"},"holder":{"type":"string","description":"Name of the account holder"}},"required":["iban","bic","holder"]},"BillingLocale":{"type":"string","enum":["fr","en","de","it","nl","pt","es"]},"CurrencyCode":{"type":"string","enum":["EUR","GBP","CHF","USD","AUD","CAD","JPY","CNH","CZK","DKK","BGN","PLN","HUF","RON","SEK","NOK","TRY","BRL","HKD","ILS","INR","KRW","MXN","XPF","XOF","XAF"],"description":"Preferred currency of the customer"},"PaymentMethod":{"type":"string","enum":["transfer","direct_debit","credit_card","cheque","universal_employment_service_cheque","cash","paypal","stripe","other"]}}},"paths":{"/contact/{id}":{"get":{"operationId":"ContactController_getContact","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The contact has been successfully retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadContactDto"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Contact not found"}},"summary":"Get a contact by ID","tags":["contact"]}}}}
```

## Retrouver un contact par son ancien identifiant

Cette route sert à retrouver un contact à partir d'un identifiant issu de l'ancien modèle de données (`legacyId`). Utilisez-la seulement si vous avez conservé de tels identifiants. Elle renvoie le même objet que la lecture par `id`, ou une erreur 404 si aucun contact ne correspond.

```bash
curl https://api.abby.fr/contact/by-legacy/$LEGACY_ID \
  -H "Authorization: Bearer $ABBY_API_KEY"
```

## GET /contact/by-legacy/{legacyId}

> Get a contact by legacy ID

```json
{"openapi":"3.0.0","info":{"title":"Abby Public API","version":"1.130.0+66756885474b"},"servers":[{"url":"https://api.abby.fr","description":"Production server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication. Pass your API key as a Bearer token."}},"schemas":{"ReadContactDto":{"type":"object","properties":{"id":{"type":"string","description":"Contact ID"},"emails":{"description":"Contact email addresses","type":"array","items":{"type":"string"}},"organization":{"description":"Organization information","allOf":[{"$ref":"#/components/schemas/ContactOrganizationDto"}]},"defaultContact":{"type":"boolean","description":"Whether this is the default contact"},"createdAt":{"type":"number","description":"Contact creation timestamp"},"archivedAt":{"type":"number","description":"Contact archival timestamp"},"hasBillings":{"type":"boolean","description":"Whether the contact has billings"},"test":{"type":"boolean","description":"Whether this is a test contact"},"phone":{"type":"string","description":"Contact phone number"},"firstname":{"type":"string","description":"Contact first name"},"lastname":{"type":"string","description":"Contact last name"},"billingAddress":{"description":"Billing address","allOf":[{"$ref":"#/components/schemas/ClientAddressDto"}]},"deliveryAddress":{"description":"Delivery address","allOf":[{"$ref":"#/components/schemas/ClientAddressDto"}]},"jobTitle":{"type":"string","description":"Contact job title"},"bankInformations":{"description":"Bank information","allOf":[{"$ref":"#/components/schemas/BankInformationsDto"}]},"hasTiersPrestation":{"type":"boolean","description":"Whether the contact has third-party services"},"notes":{"type":"string","description":"Additional notes about the contact"},"language":{"description":"Contact language preference","allOf":[{"$ref":"#/components/schemas/BillingLocale"}]},"currency":{"description":"Preferred currency","allOf":[{"$ref":"#/components/schemas/CurrencyCode"}]},"paymentMethods":{"type":"array","description":"Accepted payment methods","items":{"$ref":"#/components/schemas/PaymentMethod"}}},"required":["id","createdAt","hasBillings","test","firstname","lastname","hasTiersPrestation"]},"ContactOrganizationDto":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Organization name"},"archivedAt":{"type":"number","description":"Organization archival timestamp"}},"required":["id","name"]},"ClientAddressDto":{"type":"object","properties":{"address":{"type":"string","description":"The street address of the client","nullable":true},"complement":{"type":"string","description":"Additional address information","nullable":true},"city":{"type":"string","description":"The city of the address","nullable":true},"zipCode":{"type":"string","description":"The zip code or postal code of the address","nullable":true},"state":{"type":"string","description":"The state or province of the address"},"country":{"description":"The country of the address","allOf":[{"$ref":"#/components/schemas/CountryCode"}]}},"required":["address","city","zipCode","country"]},"CountryCode":{"type":"string","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AN","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KR","XK","KP","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"],"description":"Country code of the address"},"BankInformationsDto":{"type":"object","properties":{"iban":{"type":"string","description":"International Bank Account Number"},"bic":{"type":"string","description":"Bank Identifier Code"},"holder":{"type":"string","description":"Name of the account holder"}},"required":["iban","bic","holder"]},"BillingLocale":{"type":"string","enum":["fr","en","de","it","nl","pt","es"]},"CurrencyCode":{"type":"string","enum":["EUR","GBP","CHF","USD","AUD","CAD","JPY","CNH","CZK","DKK","BGN","PLN","HUF","RON","SEK","NOK","TRY","BRL","HKD","ILS","INR","KRW","MXN","XPF","XOF","XAF"],"description":"Preferred currency of the customer"},"PaymentMethod":{"type":"string","enum":["transfer","direct_debit","credit_card","cheque","universal_employment_service_cheque","cash","paypal","stripe","other"]}}},"paths":{"/contact/by-legacy/{legacyId}":{"get":{"operationId":"ContactController_getContactByLegacyId","parameters":[{"name":"legacyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The contact has been successfully retrieved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadContactDto"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Contact not found"}},"summary":"Get a contact by legacy ID","tags":["contact"]}}}}
```

## Modifier un contact

`PUT` attend le contact complet : `firstname` et `lastname` restent obligatoires, et `emails`, `phone` ou `jobTitle` absents du corps sont effacés. Renvoyez donc aussi les valeurs que vous voulez conserver.

Deux différences avec la création : `notes` n'est pas accepté ici, et `bankInformations` est refusé (erreur 400) pour un contact rattaché à une organisation.

```bash
curl -X PUT https://api.abby.fr/contact/$CONTACT_ID \
  -H "Authorization: Bearer $ABBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "emails": ["john.doe@example.com", "johnd@work.com"],
    "billingAddress": {
      "address": "123 Main Street",
      "zipCode": "75001",
      "city": "Paris",
      "country": "FR"
    }
  }'
```

## PUT /contact/{id}

> Update a contact

```json
{"openapi":"3.0.0","info":{"title":"Abby Public API","version":"1.130.0+66756885474b"},"servers":[{"url":"https://api.abby.fr","description":"Production server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication. Pass your API key as a Bearer token."}},"schemas":{"UpdateContactDto":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"phone":{"type":"string"},"jobTitle":{"type":"string"},"emails":{"type":"array","items":{"type":"string"}},"billingAddress":{"$ref":"#/components/schemas/ClientAddressDto"},"deliveryAddress":{"$ref":"#/components/schemas/ClientAddressDto"},"bankInformations":{"$ref":"#/components/schemas/BankInformationsDto"},"preferences":{"$ref":"#/components/schemas/ClientPreferencesDto"},"notes":{"type":"string","nullable":true}},"required":["firstname","lastname"]},"ClientAddressDto":{"type":"object","properties":{"address":{"type":"string","description":"The street address of the client","nullable":true},"complement":{"type":"string","description":"Additional address information","nullable":true},"city":{"type":"string","description":"The city of the address","nullable":true},"zipCode":{"type":"string","description":"The zip code or postal code of the address","nullable":true},"state":{"type":"string","description":"The state or province of the address"},"country":{"description":"The country of the address","allOf":[{"$ref":"#/components/schemas/CountryCode"}]}},"required":["address","city","zipCode","country"]},"CountryCode":{"type":"string","enum":["AF","AX","AL","DZ","AS","AD","AO","AI","AQ","AG","AN","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BQ","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CW","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GG","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IM","IL","IT","JM","JP","JE","JO","KZ","KE","KI","KR","XK","KP","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MK","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","ME","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","BL","SH","KN","LC","MF","PM","VC","WS","SM","ST","SA","SN","RS","SC","SL","SG","SX","SK","SI","SB","SO","ZA","GS","SS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW"],"description":"Country code of the address"},"BankInformationsDto":{"type":"object","properties":{"iban":{"type":"string","description":"International Bank Account Number"},"bic":{"type":"string","description":"Bank Identifier Code"},"holder":{"type":"string","description":"Name of the account holder"}},"required":["iban","bic","holder"]},"ClientPreferencesDto":{"type":"object","properties":{"language":{"description":"The client's preferred language for billing","allOf":[{"$ref":"#/components/schemas/BillingLocale"}]},"currency":{"description":"The client's preferred currency for transactions","allOf":[{"$ref":"#/components/schemas/CurrencyCode"}]},"paymentMethods":{"type":"array","description":"The client's preferred payment methods","items":{"$ref":"#/components/schemas/PaymentMethod"}}}},"BillingLocale":{"type":"string","enum":["fr","en","de","it","nl","pt","es"]},"CurrencyCode":{"type":"string","enum":["EUR","GBP","CHF","USD","AUD","CAD","JPY","CNH","CZK","DKK","BGN","PLN","HUF","RON","SEK","NOK","TRY","BRL","HKD","ILS","INR","KRW","MXN","XPF","XOF","XAF"],"description":"Preferred currency of the customer"},"PaymentMethod":{"type":"string","enum":["transfer","direct_debit","credit_card","cheque","universal_employment_service_cheque","cash","paypal","stripe","other"]},"ReadContactDto":{"type":"object","properties":{"id":{"type":"string","description":"Contact ID"},"emails":{"description":"Contact email addresses","type":"array","items":{"type":"string"}},"organization":{"description":"Organization information","allOf":[{"$ref":"#/components/schemas/ContactOrganizationDto"}]},"defaultContact":{"type":"boolean","description":"Whether this is the default contact"},"createdAt":{"type":"number","description":"Contact creation timestamp"},"archivedAt":{"type":"number","description":"Contact archival timestamp"},"hasBillings":{"type":"boolean","description":"Whether the contact has billings"},"test":{"type":"boolean","description":"Whether this is a test contact"},"phone":{"type":"string","description":"Contact phone number"},"firstname":{"type":"string","description":"Contact first name"},"lastname":{"type":"string","description":"Contact last name"},"billingAddress":{"description":"Billing address","allOf":[{"$ref":"#/components/schemas/ClientAddressDto"}]},"deliveryAddress":{"description":"Delivery address","allOf":[{"$ref":"#/components/schemas/ClientAddressDto"}]},"jobTitle":{"type":"string","description":"Contact job title"},"bankInformations":{"description":"Bank information","allOf":[{"$ref":"#/components/schemas/BankInformationsDto"}]},"hasTiersPrestation":{"type":"boolean","description":"Whether the contact has third-party services"},"notes":{"type":"string","description":"Additional notes about the contact"},"language":{"description":"Contact language preference","allOf":[{"$ref":"#/components/schemas/BillingLocale"}]},"currency":{"description":"Preferred currency","allOf":[{"$ref":"#/components/schemas/CurrencyCode"}]},"paymentMethods":{"type":"array","description":"Accepted payment methods","items":{"$ref":"#/components/schemas/PaymentMethod"}}},"required":["id","createdAt","hasBillings","test","firstname","lastname","hasTiersPrestation"]},"ContactOrganizationDto":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Organization name"},"archivedAt":{"type":"number","description":"Organization archival timestamp"}},"required":["id","name"]}}},"paths":{"/contact/{id}":{"put":{"operationId":"ContactController_updateContact","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContactDto"}}}},"responses":{"200":{"description":"The contact has been successfully updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadContactDto"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Contact not found"}},"summary":"Update a contact","tags":["contact"]}}}}
```

## Supprimer un contact

Un contact qui a déjà des documents de facturation (`hasBillings` à `true`) ne peut pas être supprimé : l'API répond 400.

```bash
curl -X DELETE https://api.abby.fr/contact/$CONTACT_ID \
  -H "Authorization: Bearer $ABBY_API_KEY"
```

## DELETE /contact/{id}

> Delete a contact

```json
{"openapi":"3.0.0","info":{"title":"Abby Public API","version":"1.130.0+66756885474b"},"servers":[{"url":"https://api.abby.fr","description":"Production server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication. Pass your API key as a Bearer token."}}},"paths":{"/contact/{id}":{"delete":{"operationId":"ContactController_deleteContact","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"401":{"description":"Unauthorized"},"404":{"description":"Contact not found"},"default":{"description":"The contact has been successfully deleted."}},"summary":"Delete a contact","tags":["contact"]}}}}
```

## Lister les contacts

La liste est paginée sous forme d'enveloppe : le tableau `docs` contient les contacts sous une forme réduite (`id`, `fullname`, `emails`, `organization`, etc.), accompagné de `totalDocs`, `page`, `limit`, `totalPages`, `hasNextPage`, `hasPrevPage`, `nextPage`, `prevPage` et `countWithoutFilters`. Voir [Pagination](https://docs.abby.fr/concepts/pagination.md).

Paramètres de requête :

| Paramètre        | Type                  | Rôle                                                                                               |
| ---------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
| `page`           | entier                | Numéro de page, à partir de 1.                                                                     |
| `limit`          | entier                | Nombre d'éléments par page, 100 au maximum.                                                        |
| `search`         | texte                 | Terme cherché dans le prénom et le nom du contact, et dans le nom de son organisation.             |
| `orderBy`        | `name` ou `createdAt` | Champ de tri.                                                                                      |
| `orderDirection` | `ASC` ou `DESC`       | Sens du tri.                                                                                       |
| `archived`       | booléen               | `true` : seulement les contacts archivés. Absent ou `false` : seulement les contacts non archivés. |
| `forCertificate` | booléen               | Déclaré dans la spec, sans description.                                                            |

{% hint style="warning" %}
La spécification déclare `page` et `limit` facultatifs, mais la validation du serveur attend un entier pour chacun. Envoyez-les toujours. Les autres paramètres sont facultatifs.
{% endhint %}

```bash
curl "https://api.abby.fr/contacts?page=1&limit=20&orderBy=createdAt&orderDirection=DESC" \
  -H "Authorization: Bearer $ABBY_API_KEY"
```

## Retrieve contacts

> Get a paginated list of contacts for the current company

```json
{"openapi":"3.0.0","info":{"title":"Abby Public API","version":"1.130.0+66756885474b"},"servers":[{"url":"https://api.abby.fr","description":"Production server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication. Pass your API key as a Bearer token."}},"schemas":{"ContactOrderBy":{"type":"string","enum":["name","createdAt"]},"OrderDirection":{"type":"string","enum":["ASC","DESC"]},"ReadContactsDto":{"type":"object","properties":{"countWithoutFilters":{"type":"number"},"totalDocs":{"type":"number"},"limit":{"type":"number"},"totalPages":{"type":"number"},"hasNextPage":{"type":"boolean"},"hasPrevPage":{"type":"boolean"},"nextPage":{"type":"number"},"page":{"type":"number"},"prevPage":{"type":"number"},"docs":{"type":"array","items":{"$ref":"#/components/schemas/ReadContactListItemDto"}}},"required":["countWithoutFilters","totalDocs","limit","totalPages","hasNextPage","hasPrevPage","nextPage","page","prevPage","docs"]},"ReadContactListItemDto":{"type":"object","properties":{"archivedAt":{"type":"number","description":"Contact archival timestamp"},"createdAt":{"type":"number","description":"Contact creation timestamp"},"test":{"type":"boolean","description":"Whether this is a test contact"},"defaultContact":{"type":"boolean","description":"Whether this is the default contact"},"emails":{"description":"Contact email addresses","type":"array","items":{"type":"string"}},"hasBillings":{"type":"boolean","description":"Whether the contact has billings"},"id":{"type":"string","description":"Contact ID"},"fullname":{"type":"string","description":"Contact full name"},"organization":{"description":"Organization information","allOf":[{"$ref":"#/components/schemas/ContactListOrganizationDto"}]},"tiersPrestation":{"description":"Third-party service information","allOf":[{"$ref":"#/components/schemas/TiersPrestationDto"}]}},"required":["createdAt","test","hasBillings","id","fullname"]},"ContactListOrganizationDto":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID"},"name":{"type":"string","description":"Organization name"},"archivedAt":{"type":"number","description":"Organization archival timestamp"}},"required":["id","name"]},"TiersPrestationDto":{"type":"object","properties":{"state":{"description":"Client state","allOf":[{"$ref":"#/components/schemas/ClientState"}]}},"required":["state"]},"ClientState":{"type":"string","enum":["synced","pending","end_user_action_required","error"],"description":"Current client state"}}},"paths":{"/contacts":{"get":{"description":"Get a paginated list of contacts for the current company","operationId":"ContactsController_retrieveContacts","parameters":[{"name":"page","required":false,"in":"query","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}},{"name":"search","required":false,"in":"query","schema":{"type":"string"}},{"name":"orderBy","required":false,"in":"query","schema":{"$ref":"#/components/schemas/ContactOrderBy"}},{"name":"orderDirection","required":false,"in":"query","schema":{"$ref":"#/components/schemas/OrderDirection"}},{"name":"archived","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"forCertificate","required":false,"in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successfully retrieved contacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadContactsDto"}}}},"401":{"description":""},"500":{"description":""}},"summary":"Retrieve contacts","tags":["contact"]}}}}
```

## Voir aussi

* [Organisations](https://docs.abby.fr/reference-de-lapi/organisations.md)
* [Pagination](https://docs.abby.fr/concepts/pagination.md)
* [Facturer un client, du brouillon au paiement](https://docs.abby.fr/guides/facturer-un-client.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.abby.fr/reference-de-lapi/clients.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
