Create Customer

Create a new customer account.

POST /api/customers

Authorization

• Authenticated User: Self-registration. The owning user is taken from the session — one customer profile per user (409 if one already exists).

Request Body

Field	Type	Required	Description
company_name	string	Yes	Company/organization name
contact_name	string	Yes	Primary contact name
contact_email	string	Yes	Primary contact email
contact_phone	string	No	Contact phone number
terms_accepted	boolean	Yes	Must be true

note

There is no user_id field — the user is resolved from the authenticated session. terms_accepted must be true; the acceptance timestamp is recorded server-side.

Request Example

{
  "company_name": "Acme Corporation",
  "contact_name": "Jane Smith",
  "contact_email": "jane@acme.com",
  "contact_phone": "+1-555-123-4567",
  "terms_accepted": true
}

Response

Returns 201 Created:

{
  "id": "cus_xyz789",
  "verification_status": "pending",
  "message": "Customer account created, pending verification"
}

Verification Flow

After creation:

1. Customer account is in pending status
2. Analyst receives notification of new registration
3. Analyst reviews and verifies the account
4. Customer is notified when verified

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Pending   │────▶│  Verified   │     │  Rejected   │
│             │     │             │     │             │
└─────────────┘     └─────────────┘     └─────────────┘
       │                                       ▲
       └───────────────────────────────────────┘

Example Request

curl -X POST "https://api.traces.io/api/customers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_clerk_abc123",
    "company_name": "Acme Corporation",
    "contact_name": "Jane Smith",
    "contact_email": "jane@acme.com",
    "terms_accepted": true
  }'

Error Responses

400 Bad Request

Request body failed validation (e.g. terms not accepted):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": { "terms_accepted": ["You must accept the terms and conditions"] }
  }
}

409 Conflict

Customer already exists for this user:

{
  "error": {
    "code": "CONFLICT",
    "message": "Customer profile already exists for this user"
  }
}