Customers

List customers

The customers of the company, with their type and price list. The credit limit and the balance are only returned to clients that hold the customers:financial permission.

needs customers:read Catalog and parties

Endpoints#

List: GET/api/v1/customers One record: GET/api/v1/customers/{id}

Example request#

List with a page size and a sort:

bash

curl "https://votre-entreprise.evyooht.com/api/v1/customers?per_page=5&sort=-name" \
  -H "Authorization: Bearer evy_at_votre_jeton"

powershell

$headers = @{ Authorization = "Bearer evy_at_votre_jeton" }
Invoke-RestMethod -Uri "https://votre-entreprise.evyooht.com/api/v1/customers?per_page=5&sort=-name" -Headers $headers

javascript

const response = await fetch("https://votre-entreprise.evyooht.com/api/v1/customers?per_page=5&sort=-name", {
  headers: { Authorization: "Bearer evy_at_votre_jeton" },
});
const data = await response.json();
console.log(data);

php

$ch = curl_init("https://votre-entreprise.evyooht.com/api/v1/customers?per_page=5&sort=-name");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer evy_at_votre_jeton"],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data);

python

import requests

response = requests.get(
    "https://votre-entreprise.evyooht.com/api/v1/customers",
    params={"per_page": 5, "sort": "-name"},
    headers={"Authorization": "Bearer evy_at_votre_jeton"},
)
print(response.json())

One record by its identifier:

bash

curl "https://votre-entreprise.evyooht.com/api/v1/customers/58" \
  -H "Authorization: Bearer evy_at_votre_jeton"

powershell

$headers = @{ Authorization = "Bearer evy_at_votre_jeton" }
Invoke-RestMethod -Uri "https://votre-entreprise.evyooht.com/api/v1/customers/58" -Headers $headers

javascript

const response = await fetch("https://votre-entreprise.evyooht.com/api/v1/customers/58", {
  headers: { Authorization: "Bearer evy_at_votre_jeton" },
});
const data = await response.json();
console.log(data);

php

$ch = curl_init("https://votre-entreprise.evyooht.com/api/v1/customers/58");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer evy_at_votre_jeton"],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data);

python

import requests

response = requests.get(
    "https://votre-entreprise.evyooht.com/api/v1/customers/58",
    headers={"Authorization": "Bearer evy_at_votre_jeton"},
)
print(response.json())

Query parameters of the list#

All filters can be combined: they add up (AND). An unknown parameter or an invalid value is refused with a 400 error, never ignored.

Parameter	Type	Description
`page`	integer	Page number, starting at 1. A page beyond the data is empty, not an error. At most 10000 pages: filter instead of paging deeper. Default: `1`.
`per_page`	integer	Results per page, from 1 to 100. Default: `25`.
`sort`	string	Sort fields, separated by commas, with `-` in front for descending order. Up to 3 fields. Sortable fields: `id`, `name`, `code`, `updated_at`. Default: `name`. Default: `name`.
`status`	string	active or inactive. Allowed values: `active`, `inactive`.
`customer_type_id`	integer	Only customers of this type.
`price_list_id`	integer	Only customers on this price list.
`search`	string	Text contained in the name, the code, the company name, the phone or the e-mail.
`updated_since`	string	Only records modified since this date (YYYY-MM-DD) or date and time (YYYY-MM-DDTHH:MM:SS).

Response fields#

The list and the detail route return these fields. A field is null when the value is not recorded. A field marked needs permission is absent (not empty) unless your client holds that permission.

Field	Type	Description
`id`	integer	Unique identifier. Use it in the detail route.
`code`	string\| null	Customer code.
`name`	string\| null	Full name, as displayed in the screens.
`first_name`	string\| null	First name.
`last_name`	string\| null	Last name.
`company_name`	string\| null	Company name.
`alt_name`	string\| null	Alternative name.
`phone`	string\| null	Main phone number.
`phone2`	string\| null	Second phone number.
`email`	string\| null	E-mail address. May contain several addresses.
`address`	string\| null	Street address.
`city`	string\| null	City.
`zip`	string\| null	Postal code.
`currency`	string\| null	Preferred currency.
`payment_term`	string\| null	Payment term.
`status`	"active"\| "inactive" \| null	active or inactive.
`customer_type_id`	integer\| null	Identifier of the customer type (see the customer-types resource).
`customer_type`	string\| null	Name of the customer type.
`price_list_id`	integer\| null	Identifier of the price list applied to this customer.
`discount_level`	number\| null	Discount level granted to this customer.
`discount_type`	string\| null	Kind of discount.
`credit_limit` needs customers:financial	number\| null	Credit limit. Requires customers:financial.
`balance` needs customers:financial	number\| null	Current account balance. Requires customers:financial.
`created_at`	string(date-time, local) \| null	When the record was created (local time, no time zone).
`updated_at`	string(date-time, local) \| null	When the record was last modified (local time, no time zone). Use it with the updated_since filter to synchronize.

Example response: list#

json

{
  "data": [
    {
      "id": 58,
      "code": "CUS-0058",
      "name": "Marie Dupont",
      "first_name": "Marie",
      "last_name": "Dupont",
      "company_name": "",
      "alt_name": "",
      "phone": "+509 3700 0000",
      "phone2": "",
      "email": "contact@example.com",
      "address": "12 Rue Capois",
      "city": "Port-au-Prince",
      "zip": "HT6110",
      "currency": "USD",
      "payment_term": "Net 30",
      "status": "active",
      "customer_type_id": 2,
      "customer_type": "Wholesale",
      "price_list_id": 1,
      "discount_level": 0,
      "discount_type": "",
      "credit_limit": 5000,
      "balance": 320,
      "created_at": "2026-03-15T14:30:00",
      "updated_at": "2026-03-15T14:30:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}

Example response: one record#

json

{
  "data": {
    "id": 58,
    "code": "CUS-0058",
    "name": "Marie Dupont",
    "first_name": "Marie",
    "last_name": "Dupont",
    "company_name": "",
    "alt_name": "",
    "phone": "+509 3700 0000",
    "phone2": "",
    "email": "contact@example.com",
    "address": "12 Rue Capois",
    "city": "Port-au-Prince",
    "zip": "HT6110",
    "currency": "USD",
    "payment_term": "Net 30",
    "status": "active",
    "customer_type_id": 2,
    "customer_type": "Wholesale",
    "price_list_id": 1,
    "discount_level": 0,
    "discount_type": "",
    "credit_limit": 5000,
    "balance": 320,
    "created_at": "2026-03-15T14:30:00",
    "updated_at": "2026-03-15T14:30:00"
  }
}

Errors#

The error format and the full list of codes are described in Errors.

Status	When
`400`	A query parameter is invalid or unknown. Every fault is reported at once in `error.details`. Nothing is ignored silently.
`401`	The token is missing, malformed, expired or revoked (`missing_token` or `invalid_token`). Ask for a new token.
`403`	Your token does not carry the permission this route needs (`insufficient_scope`), or the request was not made over HTTPS (`https_required`).
`429`	Too many requests this minute. Wait for the number of seconds in the `Retry-After` header.

Une erreur, une question, un point pas clair ? Écrivez-nous. Si vous écrivez à propos d'une erreur de l'API, joignez son request_id.