Customers API

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.

GET /api/v1/customers

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number
`per_page`	integer	Results per page (max: 100)
`search`	string	Search by name or code
`status`	string	Filter by status
`branch_id`	string	Filter by branch
`created_after`	date	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.

POST /api/v1/customers

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

GET /api/v1/assets/{id}

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
`400`	Bad request
`401`	Unauthorized
`403`	Forbidden
`404`	Customer not found
`409`	Conflict (duplicate)
`422`	Validation error

Assets API

Asset endpoints

Work Orders API

Work order endpoints

Customers

Customer user guide

Authentication

API authentication

Getting Started

SERVICE APPS

WORK ORDER & JOBS

CUSTOMER MANAGEMENT

SERVICE MANAGEMENT

Products & Inventory

WORKFORCE

ADMINISTRATION

API REFERENCE

Overview

Endpoints

List Customers

Get Customer

Create Customer

Update Customer

Delete Customer

Customer Contacts

List Contacts

Create Contact

Update Contact

Delete Contact

Customer Assets

List Customer Assets

Get Asset

Customer Work Orders

List Customer Work Orders

Error Responses

Assets API

Work Orders API

Customers

Authentication

​Overview

​Endpoints

​List Customers

​Get Customer

​Create Customer

​Update Customer

​Delete Customer

​Customer Contacts

​List Contacts

​Create Contact

​Update Contact

​Delete Contact

​Customer Assets

​List Customer Assets

​Get Asset

​Customer Work Orders

​List Customer Work Orders

​Error Responses

​Related Documentation

Assets API

Work Orders API

Customers

Authentication

Overview

Endpoints

List Customers

Get Customer

Create Customer

Update Customer

Delete Customer

Customer Contacts

List Contacts

Create Contact

Update Contact

Delete Contact

Customer Assets

List Customer Assets

Get Asset

Customer Work Orders

List Customer Work Orders

Error Responses

Related Documentation