Customers and lookup

Customers

GET /v1/customers                  scope leads:read
GET /v1/customers?phone=2535550100
GET /v1/customers?email=pat@example.com

One record per person across repeat leads, built from leads whose contact details you can see:

{"customers":[{"id":"cus_4f1a9c0d2b7e8a6c5d3f","first_name":"Pat","last_name":"Rivera","phone":"+12535550100","email":"pat@example.com",
  "lead_ids":["6b1c...","91de..."],"first_seen":"2026-03-02T17:00:00Z","last_seen":"2026-10-22T16:04:11Z"}]}

The customer belongs to you once you have the lead: keep the record in your own system and contact them directly about their job, under our terms (no marketing lists).

Find a lead by your data

Find by	Call
Phone (any format)	`GET /v1/leads?phone=(253) 555-0100`
Email	`GET /v1/leads?email=pat@example.com`
Your own id	`GET /v1/leads?external_id=servicetitan:88213`
Customer	`GET /v1/leads?customer_id=cus_4f1a9c0d2b7e8a6c5d3f`

Save your id on the lead first with PATCH /v1/leads/{id} and {"external_ids":{"servicetitan":"88213"}}. Phone and email only match leads whose contact you can already see.

The same ids in the app

Every lead card in My account, Leads shows the lead ID and customer ID with copy buttons, the ids your software saved (external_ids), and boxes for job total, paid amount and a private note. Those boxes write the same fields as the API, so a number typed in the app shows up in your software and the other way around. Your business ID (the business_id in webhooks) is in Settings, Connect your software.

Ids are made automatically: lead IDs when a lead is created, customer IDs when you can see the contact, client IDs and secrets when a partner app is created. You never type or request one.