API

The Leadtosale API reads your lead data: summaries of leads, sales and their value, and the leads themselves. It’s read-only, and every request is made with an API key.

Getting started

1. In Leadtosale, open Settings > Developers and create an API key. Choose Reports for summaries, and Individual leads only if you need contact details. The key is shown once, so store it somewhere safe.

2. Check the key works:

   curl https://api.leadto.sale/api/v1/health \
     -H "Authorization: Bearer lts_…"
   

3. List your containers to find their IDs, then ask for a report:

   curl "https://api.leadto.sale/api/v1/reports/leads?start=2026-09-01&end=2026-09-30&group_by=week,channel" \
     -H "Authorization: Bearer lts_…"
   

The API reference lists every endpoint and its parameters.

Authentication

Send your key in the Authorization header as Bearer lts_… on every request. A key acts as the person who created it, so it can read the accounts they belong to, or only some of them if the key was limited to those accounts. It loses access to an account as soon as its owner does, and stops working as soon as it’s revoked.

Each key has scopes:

Listing accounts and containers works with any key.

IDs, dates and time zones

IDs start with their type: acct_ for accounts, ctr_ for containers, lead_ for leads, and formtrk_, calltrk_ or customtrk_ for trackers. The part after the prefix matches the IDs shown by the Zapier and Data Studio integrations.

Date ranges are start and end, both included, as YYYY-MM-DD. Pass timezone (an IANA name such as Pacific/Auckland; default UTC) to say where each day starts. Reports group days, weeks and months in that time zone, and lead timestamps are shown in it, always with an offset. Weeks start on Monday.

Money is an object: {"amount": "1250.00", "currency": "NZD"}. Fields with no value are present and null.

Pagination

Lists return {"results": [...], "next_cursor": "…"}. To fetch the next page, repeat the request with cursor set to next_cursor, keeping the other parameters the same. next_cursor is null on the last page. page_size sets the page size: 100 by default, up to 500. Lists don’t include a total; use the summary report for counts.

Limits

Every response has X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until there’s room again) for whichever limit is closest to running out. Over a limit you get a 429 with a Retry-After header: wait that many seconds and retry. Requests that take too long are cancelled with a 503; ask for a shorter date range.

Errors

Errors are JSON with a stable code, a message saying what went wrong, a hint saying what to do, and a docs_url linking to the code on the errors page:

{
  "code": "missing_scope",
  "message": "This API key does not have the leads:read scope.",
  "hint": "Create a key with the leads:read scope on the Developers page in Leadtosale.",
  "docs_url": "https://leadto.sale/help/api/errors/#missing_scope"
}