Examples use curl. Replace YOUR_KEY and YOURSITE. The base is https://YOURSITE/wp-json/dreamscaper/v1/api/v1.

curl "BASE/customers?limit=2&stage=lead" -H "Authorization: Bearer YOUR_KEY"

Answer (shortened):

{ "object": "list",
  "data": [ { "id": 41, "object": "customer", "stage": "lead", "name": "Pat Lee",
              "email": "pat@example.com", "phone": "...", "town": "...",
              "tags": [], "created": "2026-01-05T14:00:00Z" } ],
  "has_more": true, "next_cursor": "..." }

Pass next_cursor as ?cursor= for the next page.

curl -X POST BASE/leads \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: web-form-1001" \
  -d '{"name":"Pat Lee","email":"pat@example.com","phone":"860-555-0100","message":"Need spring cleanup"}'

• Needs a name and at least an email, phone or address.
• message becomes the notes when notes is empty.
• source is an optional label (up to 20 characters). The default is api.
• A new lead returns 201. If the person already exists (same email or phone), the existing record is filled in and you get 200 with "duplicate": true and matched_on.

curl -X POST BASE/customers -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sam Roe","email":"sam@example.com","stage":"customer","on_duplicate":"return"}'

Fields accepted: name, company, email, phone, address, town, state, zip, notes, tags.
– stage defaults to customer.
– on_duplicate is error (default, returns 409), return (returns the existing record with 200) or fill (fills blanks, 200).
– Success is 201.

curl -X PATCH BASE/customers/41 -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" -d '{"phone":"860-555-0199","tags":["vip"]}'

Only the fields you send change. Sending none returns 422 nothing_to_change. An email or phone that belongs to another customer returns 409.

• Send JSON with Content-Type: application/json. Form bodies also work.
• A broken JSON body returns 400 invalid_json.

• Customers and leads created by a key are logged with the key’s name.
• Customers made through the API with stage other than lead trigger a customer.created alert.

• 422 invalid_lead or invalid_customer: add the missing name or contact detail.
• 409 duplicate_customer: includes existing_id and matched_on.
• 402 plan_limit: your plan stopped adding more records.

• API routes reference (api/v1 and zap)
• Idempotency-Key for safe retries
• API errors, 402 and 429, and rate limits
• Connecting Zapier (triggers and actions)