Developers

Clients

A Client is someone a Business invoices. On this page: the fields of a Client, how to page through a Business’s Clients and search them, and how to read, create and update one — held to the same rules as the Client form in Essentio.

The Client model

A Client as the API answers it. A field that is null has not been filled in in Essentio.

Properties

  • Name
    id
    Type
    integer
    Description

    The Client’s identifier.

  • Name
    name
    Type
    string
    Description

    The name the Business knows the Client by.

  • Name
    legal_name
    Type
    string or null
    Description

    The Client’s legal name.

  • Name
    contact_person
    Type
    string or null
    Description

    The person to address at the Client.

  • Name
    email
    Type
    string or null
    Description

    Where the Business sends the Client its documents.

  • Name
    phone
    Type
    string or null
    Description

    The Client’s phone number.

  • Name
    address
    Type
    string or null
    Description

    The street address, one or two lines.

  • Name
    city
    Type
    string or null
    Description

    The city.

  • Name
    postal_code
    Type
    string or null
    Description

    The postal code.

  • Name
    country
    Type
    string
    Description

    The country, as an ISO 3166-1 alpha-2 code: CY, GR, DE.

  • Name
    vat_number
    Type
    string or null
    Description

    The Client’s VAT number.

  • Name
    vat_verified
    Type
    boolean
    Description

    Whether VIES confirmed the VAT number.

  • Name
    account_code
    Type
    string or null
    Description

    The Client’s account code in the Business’s books.

  • Name
    currency
    Type
    string
    Description

    The currency the Client is invoiced in, as an ISO 4217 code: EUR.

  • Name
    payment_terms
    Type
    integer
    Description

    Days a document is due after it is issued.

  • Name
    is_active
    Type
    boolean
    Description

    Whether the Client is active in Essentio.

  • Name
    created_at
    Type
    timestamp
    Description

    When the Client was created, in UTC.

  • Name
    updated_at
    Type
    timestamp
    Description

    When the Client last changed, in UTC.

  • Name
    credit_limit
    Type
    string or null
    Description

    How much the Business lets the Client owe, in the Client’s currency, as an exact decimal string: 1500.00. Never a number, so no amount is rounded on its way. null when none is set.

  • Name
    notes
    Type
    string or null
    Description

    The Business’s own notes about the Client.

  • Name
    preferred_bank_account_ids
    Type
    array of integers
    Description

    The Business’s bank accounts this Client pays into, by id, ascending; empty when none is preferred. A document created for the Client can pass them as its bank_account_ids.

Paging through Clients

A list answers one page at a time, oldest first. Each page carries next_cursor: send it back as cursor for the next page, and stop when it is null. A walk from the first page to the last meets every Client exactly once, whatever is created or deleted while it runs — a Client created during the walk comes at its end.

  • limit: how many Clients a page holds, 1 to 100. Not sent: 25.
  • cursor: the next_cursor of the page before. Not sent: the first page. Treat it as opaque — never build or read one; a cursor this API did not give is refused.

The next page

curl -G https://api.essentio.pro/v1/clients \
  -H "Authorization: Bearer ess_your_api_key" \
  -d limit=100 \
  -d cursor=eyJhZnRlciI6NDJ9

Retrying a create safely

A network can fail after Essentio created a Client but before your program heard the answer. Send an Idempotency-Key header with a create — any string of 1 to 255 printable characters with no space that names this one request, such as a UUID or your order id — and retry with the same key:

  • The same key and the same body within 24 hours: the answer is the first request’s, byte for byte, with the header Idempotent-Replayed: true. Nothing is created again.
  • The same key with another body: refused with a 422 of type idempotency. Nothing is done. Use a new key for a new request.
  • A create that was refused or failed keeps no key: correct it and send it again under the same key.
  • Two requests with the same key at once: one is performed; the other waits for it and answers its result.

A key belongs to the API key that sent it: another key of the same Business never meets it. After 24 hours it is forgotten, and the same key starts a new request.

A create that may be retried

curl https://api.essentio.pro/v1/clients \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: order-10427" \
  -H "Content-Type: application/json" \
  -d '{"name": "Northwind Studio", "email": "accounts@northwind.example", "country": "CY"}'
GET/v1/clients

List Clients

Lists the Business’s Clients a page at a time, oldest first (see Paging through Clients). Every Role may read them, a Viewer’s key included.

Query parameters

  • Name
    limit
    Type
    integer
    Description

    How many Clients a page holds: 1 to 100. Not sent: 25.

  • Name
    cursor
    Type
    string
    Description

    The next_cursor of the page before. Not sent: the first page.

  • Name
    search
    Type
    string
    Description

    Only the Clients whose name, legal name, email, VAT number or account code contains this text, in any case. Send the same search with every page.

Answers

  • Name
    200
    Type
    ClientList
    Description

    data: the page’s Clients. next_cursor: where the next page starts, or null on the last.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    403
    Type
    Error
    Description

    The key’s Role may not do this.

  • Name
    422
    Type
    Error
    Description

    A limit out of range, or a cursor this API did not give.

Request

GET/v1/clients
curl -G https://api.essentio.pro/v1/clients \
  -H "Authorization: Bearer ess_your_api_key" \
  -d search=northwind

Response

{
  "data": [
    {
      "id": 42,
      "name": "Northwind Studio",
      "legal_name": "Northwind Studio Ltd",
      "contact_person": null,
      "email": "accounts@northwind.example",
      "phone": null,
      "address": "12 Harbour Street",
      "city": "Limassol",
      "postal_code": "3036",
      "country": "CY",
      "vat_number": "CY10000000X",
      "vat_verified": true,
      "account_code": "C0042",
      "currency": "EUR",
      "payment_terms": 30,
      "is_active": true,
      "created_at": "2026-09-01T09:30:00+00:00",
      "updated_at": "2026-09-01T09:30:00+00:00",
      "credit_limit": "5000.00",
      "notes": "Pays on the 5th of the month.",
      "preferred_bank_account_ids": [3]
    }
  ],
  "next_cursor": null
}
GET/v1/clients/{client}

Retrieve a Client

One Client of the Business, by its id. Every Role may read it. A Client of another Business is not found.

Answers

  • Name
    200
    Type
    Client
    Description

    The Client.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    403
    Type
    Error
    Description

    The key’s Role may not do this.

  • Name
    404
    Type
    Error
    Description

    The Business has no Client with this id.

Request

GET/v1/clients/42
curl https://api.essentio.pro/v1/clients/42 \
  -H "Authorization: Bearer ess_your_api_key"
POST/v1/clients

Create a Client

Creates a Client of the Business, held to the same rules as the Client form in Essentio. An Admin’s or Member’s key may create; a Viewer’s may not. Send an Idempotency-Key to retry safely (see Retrying a create safely).

Body

  • Name
    email
    Type
    string
    Description

    Required. Where the Business sends the Client its documents.

  • Name
    country
    Type
    string
    Description

    Required. ISO 3166-1 alpha-2: CY.

  • Name
    name
    Type
    string
    Description

    Required unless legal_name is sent. Blank, the Client takes its legal_name as its name; a Client with neither is refused.

  • Name
    legal_name
    Type
    string
    Description

    The Client’s legal name.

  • Name
    contact_person, phone, address, city, postal_code
    Type
    string
    Description

    Optional, as on the form.

  • Name
    vat_number
    Type
    string
    Description

    Checked with VIES; vat_verified in the answer says whether VIES confirmed it.

  • Name
    account_code
    Type
    string
    Description

    Not sent or blank: the next code of the Business’s pattern. A code another Client holds, or one that does not fit the pattern, is refused.

  • Name
    currency
    Type
    string
    Description

    ISO 4217. Not sent: the Business’s currency.

  • Name
    payment_terms
    Type
    integer
    Description

    Days a document is due after it is issued. Not sent: 30.

  • Name
    credit_limit
    Type
    string
    Description

    A decimal string, at least 0, stored to two decimals: "1500.00". Send a string, never a float.

  • Name
    notes
    Type
    string
    Description

    The Business’s own notes about the Client.

  • Name
    preferred_bank_account_ids
    Type
    array of integers
    Description

    The Business’s bank accounts the Client pays into, by id. Each must be one of this Business’s own: another Business’s is refused at its index (preferred_bank_account_ids.0).

Answers

  • Name
    201
    Type
    Client
    Description

    The Client created — or, for a retry under the same Idempotency-Key, the one the first request created.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    403
    Type
    Error
    Description

    A Viewer’s key.

  • Name
    422
    Type
    Error
    Description

    A field the rules refused (invalid_request, each field in errors), or an Idempotency-Key sent with another body (idempotency).

Request

POST/v1/clients
curl https://api.essentio.pro/v1/clients \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Idempotency-Key: 5f1c7a0e-8d2b-4b6a-9c1e-2f3a4b5c6d7e" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Northwind Studio Ltd",
    "email": "accounts@northwind.example",
    "country": "CY",
    "payment_terms": 14,
    "credit_limit": "1500.00",
    "preferred_bank_account_ids": [3]
  }'

Response: 201

{
  "id": 43,
  "name": "Northwind Studio Ltd",
  "legal_name": "Northwind Studio Ltd",
  "contact_person": null,
  "email": "accounts@northwind.example",
  "phone": null,
  "address": null,
  "city": null,
  "postal_code": null,
  "country": "CY",
  "vat_number": null,
  "vat_verified": false,
  "account_code": "C0043",
  "currency": "EUR",
  "payment_terms": 14,
  "is_active": true,
  "created_at": "2026-09-27T10:15:00+00:00",
  "updated_at": "2026-09-27T10:15:00+00:00",
  "credit_limit": "1500.00",
  "notes": null,
  "preferred_bank_account_ids": [3]
}
PATCH/v1/clients/{client}

Update a Client

Changes the fields sent and nothing else, held to the same rules as a create. An Admin’s or Member’s key may update; a Viewer’s may not.

  • A blank name takes the legal_name: send the legal_name with it. A Client left with neither is refused.
  • A blank account_code keeps the code the Client has.
  • currency and payment_terms may be changed, not cleared.
  • A changed VAT number or country is checked with VIES again; a cleared VAT number is removed.
  • is_active: false makes the Client inactive.
  • credit_limit and notes: null clears them.
  • preferred_bank_account_ids: a list replaces the Client’s preferred accounts, [] clears them, and not sending it (or null) keeps them. Each must be one of the Business’s own.

Answers

  • Name
    200
    Type
    Client
    Description

    The Client as it now stands.

  • Name
    401
    Type
    Error
    Description

    No API key, an unknown one or a revoked one.

  • Name
    403
    Type
    Error
    Description

    A Viewer’s key.

  • Name
    404
    Type
    Error
    Description

    The Business has no Client with this id.

  • Name
    422
    Type
    Error
    Description

    A field the rules refused; each is named in errors.

Request

PATCH/v1/clients/42
curl -X PATCH https://api.essentio.pro/v1/clients/42 \
  -H "Authorization: Bearer ess_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"city": "Paphos", "payment_terms": 45}'