---
**📚 Main Documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)
This is an individual endpoint documentation file. For the complete API reference, see the main documentation above.
---
# (PUT) Update customers
Update existing customers by ID or external ID.
**Category:** Customers
## Endpoint

PUT /api/customers

Update one or more existing customers in a single request. Entries with `id` update that customer. Entries without `id` use `externalId` to find an existing active customer. This endpoint does not create customers.

**Endpoint**

```text
PUT /api/customers
```

## Authentication

Requires authentication with an API key that has the customersWrite scope.

## Request Body

The request body must be an array of customer objects.

| Parameter  | Type          | Required       | Location | Description                                                                                                                                        |
| ---------- | ------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| id         | string (UUID) | No             | body     | Existing customer ID. When provided, the entry updates that customer.                                                                              |
| externalId | string        | Yes without id | body     | External customer identifier. Without `id`, this identifies the existing customer to update. With `id`, it can update the customer's external ID. |
| name       | string/null   | No             | body     | Customer display name. Send null to clear.                                                                                                         |
| email      | string/null   | No             | body     | Customer email address. Send null to clear.                                                                                                        |
| phone      | string/null   | No             | body     | Customer phone number. Send null to clear.                                                                                                         |
| avatar     | string/null   | No             | body     | HTTPS avatar image URL. Send null to clear.                                                                                                        |

Entries with `id` must include at least one mutable field. Entries without `id` must include `externalId` for an existing customer and at least one customer field (`name`, `email`, `phone`, or `avatar`).

## Status Codes

### 200

Customers updated successfully.

**Request**

```bash
curl -X PUT "https://hoko.to/api/customers" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "externalId": "customer_123",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "avatar": "https://example.com/jane.png"
    }
  ]'
```

**Response**

```json
[
	{
		"id": "550e8400-e29b-41d4-a716-446655440000",
		"externalId": "customer_123",
		"name": "Jane Doe",
		"email": "jane@example.com",
		"phone": null,
		"avatar": "https://example.com/jane.png",
		"createdAt": "2024-01-01T00:00:00Z",
		"updatedAt": "2024-01-01T00:00:00Z"
	}
]
```

### 400

Invalid JSON, invalid customer IDs, duplicate IDs or external IDs in the request, or a customer that does not belong to the workspace.

### 401

Invalid or missing API key.

### 403

API key does not have the required customersWrite scope.

### 429

Rate limit exceeded. Check X-RateLimit-\* headers for details.

### 500

Unexpected server error.

---

**Back to main documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)