List Customers

The List Customers endpoint provides comprehensive customer retrieval capabilities with advanced filtering, search, and pagination features. This endpoint is designed for building customer management dashboards, implementing search functionality, and generating reports. It returns customers scoped to your application with built-in security and audit logging.

Endpoint Details

method

string

GET

url

string

/api/v0/customers

Authentication: Required (API Key & Secret)
Rate Limiting: Subject to standard API rate limits

Authentication

All requests require API key authentication using the following headers:

x-client-key: Your application’s client key
x-client-secret: Your application’s client secret

Query Parameters

Pagination Parameters

skip

number

Number of records to skip (must be non-negative)
Default: 0
Example: 20

take

number

Number of records to take (must be positive)
Default: 10
Range: 1-100
Example: 50

Filter Parameters

status

enum

Filter by customer status
Values: "ACTIVE", "BLACKLISTED", "DEACTIVATED"
Example: "ACTIVE"

name

string

Filter by customer name (partial match, case-insensitive)
Example: "John"

string

Filter by customer email (exact match, case-insensitive)
Example: "john.doe@example.com"

Request Examples

curl -X GET "https://api.devdraft.ai/api/v0/customers" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Response Format

Success Response (200 OK)

{
  "data": [
    {
      "id": "cust_123456",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone_number": "+1-555-123-4567",
      "customer_type": "Enterprise",
      "status": "ACTIVE",
      "last_spent": 1250.50,
      "last_purchase_date": "2024-03-15T14:30:00Z",
      "appId": "app_789012",
      "createdAt": "2024-03-20T10:00:00Z",
      "updatedAt": "2024-03-20T10:00:00Z"
    },
    {
      "id": "cust_789012",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@company.com",
      "phone_number": "+1-555-987-6543",
      "customer_type": "Startup",
      "status": "ACTIVE",
      "last_spent": 750.00,
      "last_purchase_date": "2024-03-18T09:15:00Z",
      "appId": "app_789012",
      "createdAt": "2024-03-18T08:30:00Z",
      "updatedAt": "2024-03-18T09:15:00Z"
    }
  ],
  "total": 156,
  "skip": 0,
  "take": 10
}

Response Fields

data

array

Array of customer objects matching the filter criteria

total

number

Total number of customers matching the filter criteria

skip

number

Number of records skipped (pagination offset)

take

number

Number of records returned in this response

Customer Object Fields

string

Unique customer identifier (UUID)

first_name

string

Customer’s first name

last_name

string

Customer’s last name

string | null

Customer’s email address

phone_number

string

Customer’s phone number with country code

customer_type

string

Type of customer account (Individual, Startup, Small Business, etc.)

status

string

Current customer status (ACTIVE, BLACKLISTED, DEACTIVATED)

last_spent

number

Amount of customer’s last transaction

last_purchase_date

string | null

Date of customer’s last purchase (ISO 8601 format)

appId

string

Associated application identifier

createdAt

string

Customer account creation timestamp (ISO 8601)

updatedAt

string

Last update timestamp (ISO 8601)

Error Responses

{
  "statusCode": 400,
  "message": [
    "skip must be a non-negative number",
    "take must be between 1 and 100"
  ],
  "error": "Bad Request"
}

Use Cases

1. Customer Management Dashboards

Build comprehensive dashboards with filtering, search, and pagination for customer service teams.

2. Customer Search Functionality

Implement search features allowing users to find customers by name or email quickly.

3. Bulk Operations

Retrieve customer lists for bulk operations like sending newsletters or updating records.

4. Analytics and Reporting

Generate customer reports with specific filters for business intelligence purposes.

5. Integration Synchronization

Sync customer data with external CRM systems or marketing platforms.

Advanced Integration Patterns

class CustomerDashboard {
  constructor(api) {
    this.api = api;
    this.filters = {
      status: null,
      search: '',
      page: 1,
      pageSize: 25
    };
  }

  async loadCustomers() {
    const params = {
      skip: (this.filters.page - 1) * this.filters.pageSize,
      take: this.filters.pageSize
    };

    if (this.filters.status) {
      params.status = this.filters.status;
    }

    if (this.filters.search) {
      // Determine if search is email or name
      if (this.filters.search.includes('@')) {
        params.email = this.filters.search;
      } else {
        params.name = this.filters.search;
      }
    }

    return await this.api.listCustomers(params);
  }

  async exportCustomers(format = 'csv') {
    const allCustomers = await this.api.getAllCustomers();
    
  }
}

Best Practices

1. Pagination Strategy

Always use pagination for large customer lists to maintain performance and avoid timeouts.

2. Efficient Filtering

Use specific filters to reduce response size and improve query performance.

3. Caching Implementation

Cache frequently accessed customer lists with appropriate TTL to reduce API calls.

4. Search Optimization

Implement client-side debouncing for search queries to minimize API requests.

5. Error Handling

Handle rate limits and network errors gracefully with exponential backoff retry logic.

6. Data Export

For bulk operations, use the pagination system to fetch all data rather than single large requests.

Create Customer - Create new customer records
Fetch Customer - Get specific customer details
Update Customer - Update customer information
Blacklist Customer - Blacklist customer access
Delete Customer - Remove customer records

Support

For technical support or questions about listing customers:

Verify your API credentials are correctly configured
Check pagination parameters are within allowed ranges
Ensure filter values match expected formats
Contact support for assistance with complex filtering requirements

For more information, see:

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

Endpoint Details

Authentication

Query Parameters

Filter Parameters

Request Examples

Response Format

Success Response (200 OK)

Response Fields

Customer Object Fields

Error Responses

Use Cases

1. Customer Management Dashboards

2. Customer Search Functionality

3. Bulk Operations

4. Analytics and Reporting

5. Integration Synchronization

Advanced Integration Patterns

Best Practices

2. Efficient Filtering

3. Caching Implementation

4. Search Optimization

5. Error Handling

6. Data Export

Support

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

​Endpoint Details

​Authentication

​Query Parameters

​Pagination Parameters

​Filter Parameters

​Request Examples

​Response Format

​Success Response (200 OK)

​Response Fields

​Customer Object Fields

​Error Responses

​Use Cases

​1. Customer Management Dashboards

​2. Customer Search Functionality

​3. Bulk Operations

​4. Analytics and Reporting

​5. Integration Synchronization

​Advanced Integration Patterns

​Best Practices

​1. Pagination Strategy

​2. Efficient Filtering

​3. Caching Implementation

​4. Search Optimization

​5. Error Handling

​6. Data Export

​Related Endpoints

​Support

Endpoint Details

Authentication

Query Parameters

Pagination Parameters

Filter Parameters

Request Examples

Response Format

Success Response (200 OK)

Response Fields

Customer Object Fields

Error Responses

Use Cases

1. Customer Management Dashboards

2. Customer Search Functionality

3. Bulk Operations

4. Analytics and Reporting

5. Integration Synchronization

Advanced Integration Patterns

Best Practices

1. Pagination Strategy

2. Efficient Filtering

3. Caching Implementation

4. Search Optimization

5. Error Handling

6. Data Export

Related Endpoints

Support