Create Customer
POST /api/v1/customers
Create a new customer record.
Description
Registers a new individual or business customer with optional address details. Returns the created customer object with an assigned ID.
Path Parameters
None.
Query Parameters
None.
Request Headers
| Header | Value | Description |
|---|---|---|
Authorization |
Bearer <access_token> |
OAuth 2.0 Bearer token |
Content-Type |
application/json |
Request body format |
Accept |
application/json |
Response format |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
customer[company] |
String | No | Company name (for business customers) |
customer[email] |
String | Yes | Email address |
customer[customer_type] |
String | Yes | individual or business |
customer[phone] |
String | No | Phone number (with country code) |
customer[phone_country] |
String | No | ISO country code (e.g., za) |
customer[currency] |
String | No | Preferred currency (e.g., USD, ZAR) |
customer[website] |
String | No | Website URL |
customer[notes] |
String | No | Internal notes |
customer[address_attributes][line] |
String | No | Address line 1 |
customer[address_attributes][line2] |
String | No | Address line 2 |
customer[address_attributes][post_code] |
String | No | Postal code |
customer[address_attributes][city] |
String | No | City |
customer[address_attributes][country] |
String | No | Country name or ISO code |
Request Example
curl -X POST https://koteshen.com/api/v1/customers \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "customer": { "company": "Texas Instruments", "email": "procurement@texas.com", "customer_type": "business", "phone": "+27675711214", "phone_country": "za", "currency": "zar", "website": "https://texas.com", "notes": "notesy", "address_attributes": { "line": "1 Mahem Pl", "line2": "Unit 23", "post_code": "5256", "city": "East London", "country": "South Africa" } } }'
Response
- Status Code:
201 Created - Content-Type:
application/json
Success Response Body
{ "id": 14, "name": "Texas Instruments", "company": "Texas Instruments", "customer_type": "business", "phone": "+27675711214", "phone_country": "za", "currency": "zar", "email": "procurement@texas.com", "website": "https://texas.com", "business_id": 1, "notes": "notesy", "created_at": "2025-10-21T10:00:00.000Z", "updated_at": "2025-10-21T10:00:00.000Z", "address": { "id": 27, "line": "1 Mahem Pl", "line2": "Unit 23", "post_code": "5256", "city": "East London", "country": "South Africa", "created_at": "2025-10-21T10:00:00.100Z", "updated_at": "2025-10-21T10:00:00.100Z" }, "url": "https://koteshen.com/api/v1/customers/14.json" }
Error Responses
- 401 Unauthorized:
{ "error": "Unauthorized" } - 422 Unprocessable Entity:
{ "errors": { "email": ["has already been taken"] } }(validation errors)
Usage Notes
- Email must be unique across customers.
- Currency defaults to account’s primary if omitted.
- Use immediately after creation to link to invoices.