Customers

The people and organizations you work for. Everything else hangs off a customer: a site belongs to one, and an estimate is written for the customer who owns the site it prices.

get /customers List customers
post /customers Create a customer

gethttps://app.treeinventory.ai/api/v1/customers

List customers

Oldest first, by creation. Use search to find one by name. That is the usual first call when you are working from a name on a spreadsheet.

Scope: customers:read

Query parameters

Field	Type	Notes
cursor	string	Opaque. Take it from a previous response's `nextCursor` and send it back unchanged. Do not parse it; its contents are not part of this contract.
limit	integer	Page size. Defaults to 50, clamped to 200 rather than refused.
search	string	Case-insensitive substring of the customer name.

Each item in data.items

Field	Type	Notes
id	uuid
name	string
email	string or null
phone	string or null
createdAt	string	ISO-8601, UTC.
updatedAt	string	ISO-8601, UTC.

Example response 200

{
  "success": true,
  "message": "Customers retrieved",
  "data": {
    "items": [
      {
        "id": "9f1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
        "name": "Delap Road Properties",
        "email": "office@delaproad.example",
        "phone": "(812) 555-0134",
        "createdAt": "2026-08-19T14:02:11.412Z",
        "updatedAt": "2026-08-19T14:02:11.412Z"
      }
    ],
    "nextCursor": "eyJ2IjoidjEiLCJjcmVhdGVkQXQiOiIyMDI2LTA4LTE5IDE0OjAyOjExLjQxMjMzMSswMCIsImlkIjoiOWYxYjJjM2QtNGU1Zi00YTZiLThjN2QtMGUxZjJhM2I0YzVkIn0"
  }
}

Failures

401 Missing, malformed, revoked or expired credential. The WWW-Authenticate header names the scheme, which is ApiKey. Carries no RateLimit-* headers: the credential was never resolved, so there is no bucket to report.
403 The key is valid but does not carry the scope this operation requires. The message names the scope, so you can ask for exactly the grant you need. Carries no RateLimit-* headers: a request refused for scope is not counted against your limit.
404 No such record in your organization. A record belonging to somebody else is indistinguishable from one that does not exist.
422 Validation failed. Every bad field is named, at once.
429 Rate limit exceeded.
500 Something failed on our side. Retry with the SAME Idempotency-Key; a 5xx is the one status where retrying is correct.

posthttps://app.treeinventory.ai/api/v1/customers

Create a customer

Send an Idempotency-Key. Without one, a retry after a timeout creates a second customer and somebody has to merge them by hand.

Scope: customers:write

Headers

Field	Type	Notes
Idempotency-Key	uuid	A UUID you mint per logical action and REUSE on every retry of it. Replay returns the original response and creates nothing. Omit it and a retry creates a second record.

Request body

Field	Type	Notes
namerequired	string
email	email or null
phone	string or null

Example request

{
  "name": "Delap Road Properties",
  "email": "office@delaproad.example",
  "phone": "(812) 555-0134"
}

data

Field	Type	Notes
id	uuid
name	string
email	string or null
phone	string or null
createdAt	string	ISO-8601, UTC.
updatedAt	string	ISO-8601, UTC.

Example response 201

{
  "success": true,
  "message": "Customer created",
  "data": {
    "id": "9f1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
    "name": "Delap Road Properties",
    "email": "office@delaproad.example",
    "phone": "(812) 555-0134",
    "createdAt": "2026-08-19T14:02:11.412Z",
    "updatedAt": "2026-08-19T14:02:11.412Z"
  }
}

Failures

401 Missing, malformed, revoked or expired credential. The WWW-Authenticate header names the scheme, which is ApiKey. Carries no RateLimit-* headers: the credential was never resolved, so there is no bucket to report.
403 The key is valid but does not carry the scope this operation requires. The message names the scope, so you can ask for exactly the grant you need. Carries no RateLimit-* headers: a request refused for scope is not counted against your limit.
404 No such record in your organization. A record belonging to somebody else is indistinguishable from one that does not exist.
409 Idempotency conflict. idempotency_key_reused means this Idempotency-Key was already used with a DIFFERENT request body: mint a new key for a new request, or resend the original body to replay. command_in_progress means an identical request is still in flight; wait Retry-After seconds and retry.
422 Validation failed. Every bad field is named, at once.
429 Rate limit exceeded.
500 Something failed on our side. Retry with the SAME Idempotency-Key; a 5xx is the one status where retrying is correct.