Skip to content

Customers API

🤖 Explain with AI

The Customers API allows you to create and manage customer records that can be associated with payments and subscriptions.

Base URL

https://api.4geeks.io

Authentication

All endpoints require the X-Api-Key header:

X-Api-Key: sk_test_your_api_key_here

See Authentication for details.

Create Customer

Creates a new customer.

POST /v1/customers

Request Body

Field Type Required Description
email string (email) Yes Customer email address
name string No Customer name
description string No Customer description
phone string No Customer phone number

Request Example

curl -X POST 'https://api.4geeks.io/v1/customers' \
  -H 'X-Api-Key: sk_test_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "customer@example.com",
    "name": "John Doe",
    "phone": "+1234567890",
    "description": "Premium customer"
  }'

import requests

response = requests.post(
    'https://api.4geeks.io/v1/customers',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    json={
        'email': 'customer@example.com',
        'name': 'John Doe',
        'phone': '+1234567890',
        'description': 'Premium customer'
    }
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/customers', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sk_test_your_api_key_here',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        email: 'customer@example.com',
        name: 'John Doe',
        phone: '+1234567890',
        description: 'Premium customer'
    })
});
const data = await response.json();
console.log(data);

Response (200 OK)

Field Type Description
id string Unique internal customer ID
object string Object type (default: “customer”)
email string Customer email address
name string Customer name
phone string Customer phone number
description string Customer description

Response Example

{
    "id": "cus_9a8b7c6d5e4f",
    "object": "customer",
    "email": "customer@example.com",
    "name": "John Doe",
    "phone": "+1234567890",
    "description": "Premium customer"
}

List Customers

Lists customers with pagination.

GET /v1/customers

Query Parameters

Parameter Type Required Default Description
limit integer No 10 Number of results per page
offset integer No 0 Number of results to skip

Request Example

curl -X GET 'https://api.4geeks.io/v1/customers?limit=5&offset=0' \
  -H 'X-Api-Key: sk_test_your_api_key_here'

import requests

response = requests.get(
    'https://api.4geeks.io/v1/customers',
    headers={'X-Api-Key': 'sk_test_your_api_key_here'},
    params={'limit': 5, 'offset': 0}
)
print(response.json())

const response = await fetch('https://api.4geeks.io/v1/customers?limit=5&offset=0', {
    headers: {'X-Api-Key': 'sk_test_your_api_key_here'}
});
const data = await response.json();
console.log(data);

Response (200 OK)

Field Type Description
items array[CustomerResponse] Array of customer objects
total_items integer Total number of customers
limit integer Requested page size
offset integer Requested offset

Response Example

{
    "items": [
        {
            "id": "cus_9a8b7c6d5e4f",
            "object": "customer",
            "email": "customer@example.com",
            "name": "John Doe",
            "phone": "+1234567890",
            "description": "Premium customer"
        },
        {
            "id": "cus_1f2g3h4i5j6k",
            "object": "customer",
            "email": "jane@example.com",
            "name": "Jane Smith",
            "phone": null,
            "description": null
        }
    ],
    "total_items": 2,
    "limit": 5,
    "offset": 0
}

Error Response (422 Validation Error)

All endpoints may return a 422 status when validation fails.

{
    "detail": [
        {
            "loc": ["body", "email"],
            "msg": "field required",
            "type": "value_error.missing"
        }
    ]
}

Still questions? Ask the community or explore tutorials