Overview The Customers API allows you to create, read, update, and manage customer records. Customers are the foundation for work orders, service contracts, and billing.
Endpoints List Customers Retrieve a list of customers.
Query Parameters: Parameter Type Description pageinteger Page number per_pageinteger Results per page (max: 100) searchstring Search by name or code statusstring Filter by status branch_idstring Filter by branch created_afterdate Filter by creation date
Example Request: curl -X GET "https://api.fentu.io/v1/customers?search=acme&per_page=25" \ -H "Authorization: Bearer YOUR_API_KEY"
Example Response: { "data" : [ { "id" : "cust-001" , "name" : "Acme Corporation" , "customer_number" : "C-10001" , "status" : "active" , "email" : "contact@acme.com" , "phone" : "+1-555-123-4567" , "address" : { "street" : "123 Main Street" , "city" : "New York" , "state" : "NY" , "postal_code" : "10001" , "country" : "US" }, "created_at" : "2023-06-15T10:30:00Z" } ], "meta" : { "current_page" : 1 , "total_pages" : 10 , "total_count" : 245 } }
Get Customer Retrieve a single customer with full details.
GET /api/v1/customers/{id}
Example Response: { "data" : { "id" : "cust-001" , "name" : "Acme Corporation" , "customer_number" : "C-10001" , "status" : "active" , "customer_type" : "commercial" , "email" : "contact@acme.com" , "phone" : "+1-555-123-4567" , "fax" : "+1-555-123-4568" , "website" : "https://acme.com" , "address" : { "street" : "123 Main Street" , "city" : "New York" , "state" : "NY" , "postal_code" : "10001" , "country" : "US" }, "billing_address" : { "street" : "456 Finance Ave" , "city" : "New York" , "state" : "NY" , "postal_code" : "10002" , "country" : "US" }, "contacts" : [ { "id" : "contact-001" , "name" : "John Smith" , "title" : "Facilities Manager" , "email" : "jsmith@acme.com" , "phone" : "+1-555-111-2222" , "is_primary" : true } ], "branch" : { "id" : "branch-001" , "name" : "Northeast Region" }, "tax_id" : "12-3456789" , "payment_terms" : "net30" , "notes" : "VIP customer - priority service" , "custom_fields" : { "industry" : "Manufacturing" , "employee_count" : "500+" }, "created_at" : "2023-06-15T10:30:00Z" , "updated_at" : "2024-01-20T14:15:00Z" } }
Create Customer Create a new customer record.
Request Body: { "name" : "New Company Inc" , "customer_type" : "commercial" , "email" : "info@newcompany.com" , "phone" : "+1-555-999-8888" , "address" : { "street" : "789 Business Blvd" , "city" : "Chicago" , "state" : "IL" , "postal_code" : "60601" , "country" : "US" }, "branch_id" : "branch-002" , "payment_terms" : "net30" }
Example Response: { "data" : { "id" : "cust-002" , "customer_number" : "C-10002" , "name" : "New Company Inc" , "status" : "active" , "created_at" : "2024-01-27T16:00:00Z" } }
Update Customer Update an existing customer.
PUT /api/v1/customers/{id}
Request Body: { "email" : "newemail@company.com" , "phone" : "+1-555-888-7777" , "notes" : "Updated contact information" }
Delete Customer Delete a customer (moves to trash).
DELETE /api/v1/customers/{id}
Customers with active work orders or contracts cannot be deleted. Complete or cancel related records first.
Customer Contacts List Contacts GET /api/v1/customers/{customer_id}/contacts
Create Contact POST /api/v1/customers/{customer_id}/contacts
Request Body: { "name" : "Jane Doe" , "title" : "Operations Manager" , "email" : "jdoe@company.com" , "phone" : "+1-555-222-3333" , "is_primary" : false }
Update Contact PUT /api/v1/contacts/{id}
Delete Contact DELETE /api/v1/contacts/{id}
Customer Assets List Customer Assets GET /api/v1/customers/{customer_id}/assets
Get Asset See the Assets API for full asset management.
Customer Work Orders List Customer Work Orders GET /api/v1/customers/{customer_id}/work-orders
Returns work orders for the specified customer.
Error Responses Code Description 400Bad request 401Unauthorized 403Forbidden 404Customer not found 409Conflict (duplicate) 422Validation error
Related Documentation
Assets API Asset endpoints
Work Orders API Work order endpoints
Customers Customer user guide
Authentication API authentication
