Customers API Reference

This document provides detailed information about the Customers API, which allows you to manage customer data within our platform.

Base URL

All API endpoints for the Customers API are relative to the following base URL:

https://api.example.com/v1

Endpoints

GET /customers

Retrieves a list of all customers.

Query Parameters

Name Type Description Required
limit integer The maximum number of customers to return. Defaults to 50. No
offset integer The number of customers to skip before returning results. Defaults to 0. No
status string Filter customers by their status (e.g., 'active', 'inactive'). No

Responses

200 OK

{
  "data": [
    {
      "id": "cust_12345",
      "name": "Acme Corporation",
      "email": "contact@acme.com",
      "phone": "+1-555-123-4567",
      "status": "active",
      "created_at": "2023-10-26T10:00:00Z",
      "updated_at": "2023-10-26T10:00:00Z"
    },
    {
      "id": "cust_67890",
      "name": "Globex Industries",
      "email": "info@globex.net",
      "phone": "+1-555-987-6543",
      "status": "inactive",
      "created_at": "2023-10-25T14:30:00Z",
      "updated_at": "2023-10-25T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0,
    "next_offset": 50
  }
}

POST /customers

Creates a new customer.

Request Body

The request body should be a JSON object containing the customer's details.

Name Type Description Required
name string The full name or company name of the customer. Yes
email string The email address of the customer. Must be unique. Yes
phone string The phone number of the customer. No
status string The initial status of the customer (e.g., 'active', 'pending'). Defaults to 'active'. No

Responses

201 Created

{
  "id": "cust_abcde",
  "name": "Initech Solutions",
  "email": "support@initech.com",
  "phone": "+1-555-111-2222",
  "status": "active",
  "created_at": "2023-10-27T09:15:00Z",
  "updated_at": "2023-10-27T09:15:00Z"
}

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Email address is required."
  }
}

409 Conflict

{
  "error": {
    "code": "conflict",
    "message": "A customer with this email address already exists."
  }
}

GET /customers/{id}

Retrieves details for a specific customer by their unique ID.

Path Parameters

Name Type Description
id string The unique identifier of the customer.

Responses

200 OK

{
  "id": "cust_12345",
  "name": "Acme Corporation",
  "email": "contact@acme.com",
  "phone": "+1-555-123-4567",
  "status": "active",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "90210",
    "country": "USA"
  },
  "created_at": "2023-10-26T10:00:00Z",
  "updated_at": "2023-10-26T10:00:00Z"
}

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "Customer with ID 'cust_invalid' not found."
  }
}

PUT /customers/{id}

Updates an existing customer's details.

Path Parameters

Name Type Description
id string The unique identifier of the customer to update.

Request Body

The request body should be a JSON object containing the fields to update.

Name Type Description Required
name string The full name or company name of the customer. No
email string The email address of the customer. Must be unique if changed. No
phone string The phone number of the customer. No
status string The updated status of the customer (e.g., 'active', 'inactive'). No
address object An object containing the updated address details. No

Responses

200 OK

{
  "id": "cust_12345",
  "name": "Acme Corporation Inc.",
  "email": "contact@acmecorp.com",
  "phone": "+1-555-123-4567",
  "status": "active",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "90210",
    "country": "USA"
  },
  "created_at": "2023-10-26T10:00:00Z",
  "updated_at": "2023-10-27T11:30:00Z"
}

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "Customer with ID 'cust_invalid' not found."
  }
}

DELETE /customers/{id}

Deletes a specific customer by their unique ID.

Path Parameters

Name Type Description
id string The unique identifier of the customer to delete.

Responses

204 No Content

Indicates successful deletion with no response body.

404 Not Found

{
  "error": {
    "code": "not_found",
    "message": "Customer with ID 'cust_invalid' not found."
  }
}