# Clients

Clients are the customers of your organization. Service jobs, invoices and payments all point to a client.

| Ability | Endpoints |
| --- | --- |
| `clients:read` | `GET /v1/clients`, `GET /v1/clients/{id}` |
| `clients:create` | `POST /v1/clients` |
| `clients:update` | `PUT /v1/clients/{id}` |
| `clients:delete` | `DELETE /v1/clients` |

Client ids are UUIDs. Use them in paths and in the `client_id` field of other endpoints.

## Create a client

<span class="ep"><b>POST</b> /v1/clients</span>

```bash
curl -X POST https://api.invoicing.proradius.co/v1/clients \
  -H "Authorization: Bearer $PRORADIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demo Client",
    "username": "demo-client",
    "phone_number": "+961 70 000 000",
    "email": "demo.client@example.com",
    "address": "Main street, building 4",
    "external_ref": "crm-1001"
  }'
```

- `name` is required.
- `username` is required unless the organization generates usernames automatically. It must be unique in the
  organization.
- `email` must be unique.
- `external_ref` is your own id for the client, up to 191 characters, unique in the organization.

The answer is `201` with the new client. The [API reference](/api/) lists every field, including address, branch,
collector and services.

## Link clients to your system

Store your id in `external_ref` when you create or update a client. You can then open service jobs for that client
without knowing its PROradius id:

```json
{ "title": "Router keeps rebooting", "board_id": "4c6e8a0b-1d3f-4a5c-9e7b-2f4a6c8e0b1d", "client_external_ref": "crm-1001", "priority": "medium", "type": "support" }
```

Service job endpoints also accept `client_phone` and `client_isp_username`. Phone numbers are normalised before they
are compared. See [Identify the client](/guides/service-jobs/#identify-the-client).

## Find clients

<span class="ep"><b>GET</b> /v1/clients</span>

| Parameter | Notes |
| --- | --- |
| `query` | Free-text search, at least 3 characters. Partial match on name, username, email, phone number (as stored), address, city, zone, street, building, box, reference, code and disjunctor. |
| `status` | `active` or `inactive`. |
| `date_from`, `date_to` | Creation date range, `YYYY-MM-DD`. |
| `branch_id` | Clients of one branch. |
| `external_ref` | Exact match on your own reference. |
| `phone` | Exact phone match in any format. Spaces, dashes and the `+961`, `00961` or leading `0` prefixes are normalised on both sides. |
| `pageIndex`, `pageSize` | See [Pagination](/concepts/pagination/#clients). `pageSize` is 1 to 100. |

Every client response, single or in a list, includes `external_ref`.

Find one client by your own id or by phone:

```bash
curl "https://api.invoicing.proradius.co/v1/clients?external_ref=crm-1001" \
  -H "Authorization: Bearer $PRORADIUS_API_KEY"

curl "https://api.invoicing.proradius.co/v1/clients?phone=%2B961%2070%20000%20000" \
  -H "Authorization: Bearer $PRORADIUS_API_KEY"
```

No match returns an empty page (`"data": []`), not an error.

## Update a client

<span class="ep"><b>PUT</b> /v1/clients/&#123;id&#125;</span>

`username` and `name` are required on every update. `external_ref` changes only when you send it. Read the client
first and send back the values you want to keep.

## Delete clients

<span class="ep"><b>DELETE</b> /v1/clients</span>

```json
{ "id": ["b8f2a1c4-7d39-4e52-9a06-1f4c8b3d5e27"] }
```

The body lists the ids to delete. Every id must belong to your organization.

## Webhooks

Subscribe to `client.created` and `client.updated` to hear about changes made in the PROradius apps or through the API. The key needs
`clients:read`. See [Webhooks](/guides/webhooks/).