Customers API

Create, read, update, and delete customer records for your organization.

GET /api/v1/customers

Returns a paginated list of customers. Use query parameters to filter and search.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`pageSize`	integer	20	Items per page (max 100)
`search`	string		Search by company name, contact, email, or city
`activeOnly`	boolean	false	Only return active customers

Example Request

GET /api/v1/customers?page=1&pageSize=10&search=acme
Authorization: Bearer YOUR_JWT_TOKEN

Response (200 - Success)

{
    "success": true,
    "data": {
        "customers": [
            {
                "id": 1,
                "companyName": "Acme Corporation",
                "isActive": true,
                "contactName": "John Doe",
                "email": "[email protected]",
                "phone": "555-123-4567",
                "billingCity": "New York",
                "billingState": "NY",
                "paymentTerms": "Net 30",
                "isTaxExempt": false,
                "dateCreated": "2024-01-15T10:00:00Z",
                "dateUpdated": "2024-12-20T14:30:00Z"
            }
        ],
        "pagination": {
            "currentPage": 1,
            "pageSize": 10,
            "totalCount": 50,
            "totalPages": 5,
            "hasPrevious": false,
            "hasNext": true
        }
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

GET /api/v1/customers/{id}

Returns a single customer with full details including addresses.

Response (200 - Success)

{
    "success": true,
    "data": {
        "customer": {
            "id": 1,
            "companyName": "Acme Corporation",
            "isActive": true,
            "contactName": "John Doe",
            "email": "[email protected]",
            "phone": "555-123-4567",
            "fax": "555-123-4568",
            "website": "https://acme.com",
            "paymentTerms": "Net 30",
            "isTaxExempt": false,
            "taxExemptNumber": null,
            "billingAddress": "123 Main Street",
            "billingCity": "New York",
            "billingState": "NY",
            "billingZip": "10001",
            "billingCountry": "USA",
            "shippingSameAsBilling": true,
            "shippingAddress": null,
            "shippingCity": null,
            "shippingState": null,
            "shippingZip": null,
            "shippingCountry": null,
            "shippingContactName": null,
            "shippingContactPhone": null,
            "notes": "Priority customer",
            "salesforceAccountId": "001ABC123",
            "salesforceLastSync": "2024-12-20T10:00:00Z",
            "dateCreated": "2024-01-15T10:00:00Z",
            "dateUpdated": "2024-12-20T14:30:00Z"
        }
    },
    "timestamp": "2024-12-25T12:00:00Z"
}

Error Responses

Status	Code	Description
404	`CUSTOMER_NOT_FOUND`	Customer with specified ID does not exist

POST /api/v1/customers

Creates a new customer record.

Request Body

Field	Type	Required	Description
`companyName`	string	Yes	Company name (max 100 chars)
`isActive`	boolean	No	Active status (default: true)
`contactName`	string	No	Primary contact name (max 100 chars)
`email`	string	No	Email address (max 100 chars)
`phone`	string	No	Phone number (max 20 chars)
`fax`	string	No	Fax number (max 20 chars)
`website`	string	No	Website URL (max 200 chars)
`paymentTerms`	string	No	Payment terms (max 50 chars)
`isTaxExempt`	boolean	No	Tax exempt status (default: false)
`taxExemptNumber`	string	No	Tax exempt ID (max 50 chars)
`billingAddress`	string	No	Street address (max 200 chars)
`billingCity`	string	No	City (max 100 chars)
`billingState`	string	No	State/Province (max 50 chars)
`billingZip`	string	No	ZIP/Postal code (max 20 chars)
`billingCountry`	string	No	Country (max 100 chars)
`shippingSameAsBilling`	boolean	No	Use billing as shipping (default: true)
`shippingAddress`	string	No	Shipping street address
`shippingCity`	string	No	Shipping city
`shippingState`	string	No	Shipping state
`shippingZip`	string	No	Shipping ZIP code
`shippingCountry`	string	No	Shipping country
`shippingContactName`	string	No	Shipping contact name
`shippingContactPhone`	string	No	Shipping contact phone
`notes`	string	No	Internal notes (max 500 chars)

Example Request

POST /api/v1/customers
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
    "companyName": "Acme Corporation",
    "contactName": "John Doe",
    "email": "[email protected]",
    "phone": "555-123-4567",
    "paymentTerms": "Net 30",
    "billingAddress": "123 Main Street",
    "billingCity": "New York",
    "billingState": "NY",
    "billingZip": "10001",
    "billingCountry": "USA"
}

Response (201 - Created)

{
    "success": true,
    "customerId": 1,
    "message": "Customer created successfully",
    "timestamp": "2024-12-25T12:00:00Z"
}

PUT /api/v1/customers/{id}

Updates an existing customer. All fields from the POST request body are accepted.

DELETE /api/v1/customers/{id}

Permanently removes a customer record.

Response (200 - Success)

{
    "success": true,
    "customerId": 1,
    "message": "Customer deleted successfully"
}