Customers API Reference

Create and manage customer records in ChurnShield.

Create Customer

POST/api/customers

Example Request

curl -X POST https://api.churnshield.ai/api/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "name": "Acme Inc",
    "email": "contact@acme.com",
    "metadata": {
      "industry": "technology",
      "plan": "enterprise"
    }
  }'

Example Response

{
  "id": "cust_123",
  "name": "Acme Inc",
  "email": "contact@acme.com",
  "metadata": {
    "industry": "technology",
    "plan": "enterprise"
  },
  "created_at": "2024-03-15T12:00:00Z",
  "updated_at": "2024-03-15T12:00:00Z"
}

Request Body

customer_id - Required. Your unique identifier for the customer.

name - Required. The customer's name.

email - Required. The customer's email address.

metadata - Optional. Additional data about the customer.

Get Customer

GET/api/customers/{customer_id}

Example Request

curl https://api.churnshield.ai/api/customers/cust_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "cust_123",
  "name": "Acme Inc",
  "email": "contact@acme.com",
  "metadata": {
    "industry": "technology",
    "plan": "enterprise"
  },
  "created_at": "2024-03-15T12:00:00Z",
  "updated_at": "2024-03-15T12:00:00Z"
}

List Customers

GET/api/customers

Example Request

curl https://api.churnshield.ai/api/customers \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "customers": [
    {
      "id": "cust_123",
      "name": "Acme Inc",
      "email": "contact@acme.com",
      "metadata": {
        "industry": "technology",
        "plan": "enterprise"
      },
      "created_at": "2024-03-15T12:00:00Z",
      "updated_at": "2024-03-15T12:00:00Z"
    }
  ],
  "has_more": false
}

Query Parameters

limit - Optional. Number of customers to return (default: 10, max: 100).

starting_after - Optional. Cursor for pagination.

Update Customer

PATCH/api/customers/{customer_id}

Example Request

curl -X PATCH https://api.churnshield.ai/api/customers/cust_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "metadata": {
      "plan": "enterprise_plus"
    }
  }'

Example Response

{
  "id": "cust_123",
  "name": "Acme Corporation",
  "email": "contact@acme.com",
  "metadata": {
    "industry": "technology",
    "plan": "enterprise_plus"
  },
  "created_at": "2024-03-15T12:00:00Z",
  "updated_at": "2024-03-15T12:05:00Z"
}

Request Body

name - Optional. Update the customer's name.

email - Optional. Update the customer's email.

metadata - Optional. Update or add metadata fields.

Delete Customer

DELETE/api/customers/{customer_id}

Example Request

curl -X DELETE https://api.churnshield.ai/api/customers/cust_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "cust_123",
  "deleted": true
}