## Authentication
All API requests require authentication via Bearer token:
```
Authorization: Bearer {your-api-token}
Content-Type: application/json
```
## 1. Create a New Client
### Endpoint
```
POST /api/v1/clients
```
### Minimum Required Fields
Only the `name` field is mandatory:
```json
{
"name": "Acme Corporation Ltd"
}
```
### Complete Example with All Address Fields
```json
{
"name": "Acme Corporation Ltd",
"address1": "123 Business Park",
"address2": "Suite 400",
"address3": "Building A",
"town": "London",
"county": "Greater London",
"postcode": "SW1A 1AA",
"country": "United Kingdom",
"email": "[email protected]",
"telephone": "020 7946 0958",
"mobile": "07700 900123",
"website": "www.acmecorp.com",
"notes": "Preferred supplier - Net 30 payment terms",
"account_reference": "ACME001"
}
```
### Example with Custom Fields
```json
{
"name": "Tech Solutions Inc",
"address1": "456 Innovation Drive",
"town": "Manchester",
"postcode": "M1 2AB",
"country": "United Kingdom",
"email": "[email protected]",
"telephone": "0161 123 4567",
"custom_fields": [
{
"label": "Industry",
"value": "Technology"
},
{
"label": "Account Manager",
"value": "Sarah Jones"
},
{
"label": "Annual Revenue",
"value": "£500,000"
}
]
}
```
### Example with Contacts
```json
{
"name": "Global Trading Ltd",
"address1": "789 High Street",
"town": "Birmingham",
"postcode": "B1 1BB",
"country": "United Kingdom",
"email": "[email protected]",
"telephone": "0121 456 7890",
"contacts": [
{
"name": "John Smith",
"email": "[email protected]",
"telephone": "0121 234 5678",
"job_title": "Finance Director"
},
{
"name": "Emma Wilson",
"email": "[email protected]",
"mobile": "07700 900456",
"job_title": "Operations Manager"
}
]
}
```
### Success Response
```json
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Corporation Ltd",
"address1": "123 Business Park",
"address2": "Suite 400",
"address3": "Building A",
"town": "London",
"county": "Greater London",
"postcode": "SW1A 1AA",
"country": "United Kingdom",
"email": "[email protected]",
"telephone": "020 7946 0958",
"mobile": "07700 900123",
"website": "www.acmecorp.com",
"notes": "Preferred supplier - Net 30 payment terms",
"account_reference": "ACME001",
"created": "2024-07-20T15:30:00Z",
"last_updated": "2024-07-20T15:30:00Z"
}
```
### Error Response (Duplicate Name)
```json
{
"error": "\"Acme Corporation Ltd\" already exists. Id is \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\""
}
```
---
## 2. Update an Existing Client
### Endpoint
```
PATCH /api/v1/clients
```
### Required Fields
The `id` field is mandatory for updates.
### Partial Update - Postcode & Email Only
```json
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"postcode": "EC1A 1BB",
"email": "[email protected]"
}
```
### Update Address Details
```json
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"address1": "999 New Office Street",
"address2": "Floor 5",
"address3": "",
"town": "Leeds",
"county": "West Yorkshire",
"postcode": "LS1 4AP",
"country": "United Kingdom"
}
```
### Update with Custom Fields
```json
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Corporation (UK) Ltd",
"telephone": "020 7946 1234",
"custom_fields": [
{
"label": "VIP Status",
"value": "Gold"
},
{
"label": "Credit Limit",
"value": "£50,000"
}
]
}
```
### Success Response
Returns the updated client object with all current values:
```json
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Acme Corporation (UK) Ltd",
"address1": "999 New Office Street",
"address2": "Floor 5",
"town": "Leeds",
"county": "West Yorkshire",
"postcode": "LS1 4AP",
"country": "United Kingdom",
"telephone": "020 7946 1234",
"last_updated": "2024-07-20T16:45:00Z"
}
```
### Error Response (Invalid ID)
```json
{
"error": "Id \"invalid-id\" is not a valid id format"
}
```
### Error Response (Not Found)
```json
{
"error": "Id \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\" not found"
}
```
---
## Field Reference
### Standard Fields
| Field | Type | Required | Max Length | Description |
|-------|------|----------|------------|-------------|
| name | string | Yes (Create) | 200 | Client name (unique per account) |
| address1 | string | No | - | Address line 1 |
| address2 | string | No | - | Address line 2 |
| address3 | string | No | - | Address line 3 |
| town | string | No | - | City/Town |
| county | string | No | - | County/State |
| postcode | string | No | - | Postal/ZIP code |
| country | string | No | - | Country name |
| email | string | No | - | Primary email address |
| telephone | string | No | - | Primary phone number |
| mobile | string | No | - | Mobile phone number |
| website | string | No | - | Website URL |
| notes | string | No | - | Internal notes |
| account_reference | string | No | - | External system reference (e.g., Sage account code) |
### Custom Fields
Custom fields are account-specific. Use the `/getcustomfields` endpoint to discover available fields.
```json
"custom_fields": [
{
"label": "Field Label",
"value": "Field Value"
}
]
```
### Contact Fields
When creating a client with contacts:
```json
"contacts": [
{
"name": "Contact Name",
"email": "[email protected]",
"telephone": "Phone Number",
"mobile": "Mobile Number",
"job_title": "Job Title"
}
]
```
---
## Code Examples
### cURL Example - Create Client
```bash
curl -X POST "https://your-api-domain.com/api/v1/clients" \
-H "Authorization: Bearer your-api-token" \
-H "Content-Type: application/json" \
-d '{
"name": "Example Client Ltd",
"address1": "123 High Street",
"town": "London",
"postcode": "SW1A 1AA",
"country": "United Kingdom",
"email": "[email protected]",
"telephone": "020 1234 5678"
}'
```
### cURL Example - Update Client
```bash
curl -X PATCH "https://your-api-domain.com/api/v1/clients" \
-H "Authorization: Bearer your-api-token" \
-H "Content-Type: application/json" \
-d '{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"postcode": "EC1A 1BB",
"telephone": "020 9876 5432"
}'
```
---
## HTTP Status Codes
| Code | Description |
|------|-------------|
| 200 | Success |
| 204 | No Content (Client not found or deleted) |
| 400 | Bad Request (Invalid parameters) |
| 401 | Unauthorized (Invalid or missing API token) |
| 404 | Not Found |
| 409 | Conflict (Duplicate client name) |
| 500 | Internal Server Error |
---