Customers API

Create and search customers for your business.

Create customer

POST /api/v1/customers

Scope required: write

Request body

Field	Type	Required	Description
name	string	Yes	Customer name
email	string	No	Email address
phone	string	No	Phone number
address	string	No	Street address
city	string	No	City
state	string	No	State / Province
country	string	No	Country
postal_code	string	No	Postal / ZIP code
tax_id	string	No	Tax identification number (GST, VAT, etc.)
notes	string	No	Internal notes about the customer

Example request

curl -X POST https://onlineinvoicemaker.com/api/v1/customers \
  -H "Authorization: Bearer oim_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "phone": "+1-555-0100",
    "address": "123 Business Ave",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105",
    "tax_id": "US-12345678"
  }'

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "business_id": "cb21efb1-fa40-434f-a1d3-e17c0bdb9aa6",
  "name": "Acme Corp",
  "email": "billing@acme.com",
  "phone": "+1-555-0100",
  "address": "123 Business Ave",
  "city": "San Francisco",
  "state": "CA",
  "country": "US",
  "postal_code": "94105",
  "tax_id": "US-12345678",
  "notes": null,
  "created_at": "2026-04-01T10:00:00.000Z",
  "updated_at": "2026-04-01T10:00:00.000Z"
}

Status: 201 Created

Webhook event

A customer.created webhook event is emitted after creation.

---

Search customers

GET /api/v1/customers

Scope required: read

Query parameters

Parameter	Type	Description
name	string	Filter by name (partial match, case-insensitive)
email	string	Filter by email (partial match, case-insensitive)
page	number	Page number. Default: 1
limit	number	Results per page. Default: 25, max: 100

Example request

curl -X GET "https://onlineinvoicemaker.com/api/v1/customers?name=acme" \
  -H "Authorization: Bearer oim_your_api_key"

Example response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "business_id": "cb21efb1-fa40-434f-a1d3-e17c0bdb9aa6",
      "name": "Acme Corp",
      "email": "billing@acme.com",
      "phone": "+1-555-0100",
      "created_at": "2026-04-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "total_pages": 1
  }
}

Typical workflow

1. Create a customer with their billing details
2. Use the returned id as customer_id when creating invoices or quotations
3. The customer info is automatically included on generated PDFs

# Step 1: Create customer
CUSTOMER=$(curl -s -X POST .../api/v1/customers \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Client", "email": "client@example.com"}')

CUSTOMER_ID=$(echo $CUSTOMER | jq -r '.id')

# Step 2: Create invoice for that customer
curl -X POST .../api/v1/invoices \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"customer_id\": \"$CUSTOMER_ID\",
    \"items\": [{\"description\": \"Consulting\", \"quantity\": 10, \"unit_price\": 150}]
  }"