Using the API

Making requests

The base URL, the request and response format, and the OpenAPI document.

Base URL

https://api.leadity.io

Every path starts with /v1. The API only answers over HTTPS.

Requests

Send the key as Authorization: Bearer lk_api_... on every call. See Authentication.
A GET takes its inputs as query parameters. A POST takes a JSON body with Content-Type: application/json.
Path parameters are ids the API gave you, such as a scrape's id from create_scrape or list_scrapes. An id is letters and digits only, and anything else in its place is refused with invalid_body, its issues naming path.id, before the call reaches Leadity's servers.
Every operation that takes credits also needs an Idempotency-Key header and a maxCredits field. See Spending credits safely.

curl -X POST "https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/rename" \
  -H "Authorization: Bearer $LEADITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "TX roofers, mobiles" }'

Responses

A success answers 200 with a JSON body, except two kinds of answer: the file downloads answer a CSV file, and an operation that takes credits answers 201 when it buys. A retry of a purchase that went through carries the header Idempotent-Replayed: true, and a retried order or validation run answers 200 with "replayed": true (see Idempotency). A refusal answers a 4xx or 5xx status with the same small body every time:

{
  "error": "insufficient_scope",
  "message": "The key does not carry the scope this operation needs."
}

Branch on error, which is a stable code, and show message to a person. Some codes carry extra fields, such as retryAfterSeconds on rate_limited. Every code and its fields are listed on Errors.

Timestamps are ISO 8601 in UTC. Credits are whole numbers on the balance; a per-lead rate is given in thousandths of a credit (leadRateMilli) so the arithmetic stays exact.

OpenAPI

The API publishes an OpenAPI 3.1 document, generated from the same definitions as this reference:

https://api.leadity.io/v1/openapi.json

Point a client generator or an API tool at it to get every operation and schema.

Versioning

The version is in the path. Within /v1, fields are added and never renamed or removed, so a client that ignores fields it does not know keeps working. A change that would break a client becomes a new operation.