Customers API

Customers endpoints

Base URL: https://api.web.aivapad.io/api/external/v1

Use these endpoints to centralize customer data and keep records synchronized across your operation.

Required scopes:

• customers:read for visibility and customer lookup operations
• customers:write for customer lifecycle operations

Customer response shape (example):

{
  "_id": "7f5f2d2f-6c7c-4f49-b6d4-7445319f3b8e",
  "id": "7f5f2d2f-6c7c-4f49-b6d4-7445319f3b8e",
  "firstName": "Jane",
  "lastName": "Smith",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+1 (800) 123-4567",
  "status": "active",
  "type": "individual",
  "value": 0,
  "autoPayment": false,
  "createdAt": "2026-04-06T20:33:50.414Z",
  "updatedAt": "2026-04-06T20:33:50.414Z"
}

1) List customers

GET /customers

curl -X GET "https://api.web.aivapad.io/api/external/v1/customers" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE"

Successful response (200): array of customers.

2) Get customer by ID

GET /customers/:id

curl -X GET "https://api.web.aivapad.io/api/external/v1/customers/7f5f2d2f-6c7c-4f49-b6d4-7445319f3b8e" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE"

Successful response (200): customer object.

3) Create customer

POST /customers

Minimum validation:

• name is required
• email is required

curl -X POST "https://api.web.aivapad.io/api/external/v1/customers" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1 (800) 123-4567",
    "status": "active",
    "type": "individual"
  }'

Successful response (201): full created customer object.

4) Update customer status

PUT /customers/:id/status

Allowed values:

• active
• inactive
• blocked

curl -X PUT "https://api.web.aivapad.io/api/external/v1/customers/7f5f2d2f-6c7c-4f49-b6d4-7445319f3b8e/status" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "inactive"
  }'

Successful response (200): full updated customer object.

5) Update customer

PUT /customers/:id

Use this endpoint for partial or full customer profile updates.

curl -X PUT "https://api.web.aivapad.io/api/external/v1/customers/7f5f2d2f-6c7c-4f49-b6d4-7445319f3b8e" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane A. Smith",
    "phone": "+1 (800) 987-6543",
    "notes": "Enterprise account"
  }'

Successful response (200): full updated customer object.

6) Delete customer

DELETE /customers/:id

curl -X DELETE "https://api.web.aivapad.io/api/external/v1/customers/7f5f2d2f-6c7c-4f49-b6d4-7445319f3b8e" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE"

Successful response (200):

{
  "success": true
}

Error reference

Common errors across customers endpoints:

• 403 Forbidden:
  • token missing/invalid/expired
  • token permission does not include required access
  • token is not mapped to an active account context
• 404 Not Found: customer ID does not exist in your tenant
• 400 Bad Request: invalid payload or missing required fields
• 500 Internal Server Error: unexpected server-side failure