List Customers

Retrieve a list of customer accounts.

GET /api/customers

Authorization

• Analyst: Required

Query Parameters

Parameter	Type	Required	Description
verification_status	string	No	Filter: pending, verified, rejected
search	string	No	Search by company name or email
limit	number	No	Items per page (default: 20)
offset	number	No	Items to skip (default: 0)

Response

{
  "customers": [
    {
      "id": "cus_xyz789",
      "company_name": "Acme Corporation",
      "contact_name": "Jane Smith",
      "contact_email": "jane@acme.com",
      "verification_status": "verified",
      "total_collections": 5,
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "cus_abc123",
      "company_name": "Beta Industries",
      "contact_name": "John Doe",
      "contact_email": "john@beta.com",
      "verification_status": "pending",
      "total_collections": 0,
      "created_at": "2024-01-14T00:00:00Z"
    }
  ],
  "total": 47
}

Verification Status Values

Status	Description
pending	Awaiting verification
verified	Account verified and active
rejected	Verification rejected

Example Request

curl -X GET "https://api.traces.io/api/customers?verification_status=pending" \
  -H "Authorization: Bearer <token>"

Example: Search Customers

curl -X GET "https://api.traces.io/api/customers?search=acme" \
  -H "Authorization: Bearer <token>"

Error Responses

403 Forbidden

Non-analyst attempting access:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Only analysts can list customers"
  }
}