> For the complete documentation index, see [llms.txt](https://support.ordereazi.com/central/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.ordereazi.com/central/developers/api-guides/clients-and-end-users.md).

# Clients and End Users

Read, create, and update clients, their addresses, and End Users with the OrderEazi API, to keep them in step with your CRM or accounting system.

When your CRM or accounting system holds your client list, OrderEazi needs the same clients, so Quotes and orders go to the right company. The OrderEazi API lets you read, create, and update clients and their addresses. You can also keep End Users in step: whoever actually receives a client's goods, such as a branch, a site, or the client's own customer.

### Before you start

You'll need:

* **Permissions:** **Read** on **For Clients** to read, and **Write** to create and change. See [Authentication](/central/developers/authentication.md).
* **Version 2.0:** Send `x-api-version: 2.0`. Client addresses and End Users are version 2.0 only, and only version 2.0 gives clients structured addresses.
* **Your system's IDs:** Send each client's ID in your system as its `ERPId`, so you can match the two.

### How to read clients

* **Every client:** `GET /api/client/list` returns every client, with its addresses.
* **One client:** `GET /api/client/lookup/id/{id}`, `/api/client/lookup/code/{code}`, or `/api/client/lookup/name/{name}` returns one client. Each needs an exact match.
* **By email or phone:** `GET /api/client/lookup/email/{email}` or `/api/client/lookup/number/{phone}` finds a client by email address or phone number. These also search the one-off contacts on projects (OrderEazi's records of orders), so a result may not be a client. Check its `ClientId`.

A client that doesn't exist returns a `404`.

### How to create a client

Send a POST to `/api/client/create`:

```json
{
  "Name": "Clientco (Pty) Ltd",
  "Code": "CLI001",
  "Email": "accounts@example.com",
  "Phone": "0215550100",
  "ContactName": "Thandi",
  "ContactSurname": "Nkosi",
  "TaxNumber": "4123456789",
  "CreditLimit": 50000,
  "ERPId": "CUST-0091",
  "PostalAddress": { "StreetAddress": "PO Box 12", "City": "Cape Town", "Province": "Western Cape", "Country": "ZAF", "StreetCode": "8000" },
  "ShippingAddress": { "BuildingFloorUnitCompany": "Unit 4", "StreetAddress": "10 Main Rd", "Suburb": "Observatory", "City": "Cape Town", "Province": "Western Cape", "Country": "ZAF", "StreetCode": "7925" }
}
```

* **Required fields:** You must send `Name` and `Email`.
* **Duplicates:** If a client with the same `Name` and `Code` already exists, you get "Client already exists." Email addresses don't have to be unique.
* **Currency:** Leave out `CurrencyId` to use the organisation's currency. Get currency IDs from `GET /api/currency/list`.

The response is the saved client, with its `ClientId`.

### How to update clients

Send a list of clients with `POST /api/client/update`. Each is matched by `ClientId`, or by `Code` when you leave the ID out.

> **Warning:** An update replaces the client's details. Fields you leave out, such as `Phone`, `CreditLimit`, and `CurrencyId`, are cleared, but `ERPId` is kept. Read the client first, change what you need, and send the whole client back.

### How to manage a client's addresses

A client can have several delivery and postal addresses.

* **List:** `GET /api/client/address/{clientId}` lists a client's addresses.
* **Add:** `POST /api/client/address` adds addresses. Send a list, each with its `ClientId`, `Type` (`0` for delivery, `1` for postal), `Address`, and `IsDefault`.
* **Change:** `PUT /api/client/address` changes an address, found by its `FinClientAddressId`.
* **Delete:** `DELETE /api/client/address/{finClientAddressId}` deletes an address. You can't delete the default address while the client has others of that type.

Give each address your system's ID as its `ErpId` (note the casing: clients use `ERPId`, addresses and End Users use `ErpId`). You can also send `Addresses` with the client on create and update. OrderEazi then keeps the addresses that have an `ErpId` in step with your list, and removes any you leave out.

### How to manage End Users

* **List:** `GET /api/end-user` lists End Users. Add `?includeDisabled=true` to include disabled ones.
* **Create:** `POST /api/end-user` creates End Users. Send a list, each with a `Name`, `ErpId`, and `"Enabled": true`. Without `Enabled`, a new End User is disabled, and doesn't show in the default list.
* **Change:** `PUT /api/end-user` changes an End User, found by its `EndUserId`.
* **Disable:** `DELETE /api/end-user/{endUserId}` disables the End User. It isn't deleted.
* **Addresses and contacts:** `/api/end-user/address` and `/api/end-user/contact` work like client addresses.

**Example:** Your CRM adds a new branch for Clientco. You create an End User called "Clientco Durban" with your CRM's ID as its `ErpId` and `"Enabled": true`, then add its delivery address with `POST /api/end-user/address`.

### Related pages

* [Receiving orders from a sales channel](/central/developers/api-guides/receiving-orders-from-a-sales-channel.md): send orders for these clients
* [Products and stock levels](/central/developers/api-guides/products-and-stock-levels.md): read a client's prices