# List leads (v3)

# Setup

Endpoint: https://app.lamatool.com/api/v3/leads

Type: GET

Returns the leads belonging to the company that owns the api_key. Without any filters, all leads are returned.

# Parameters

Field Type Required Note
api_key string true Company API key
limit integer false Number of leads per page. If omitted, all leads are returned unpaginated
page integer false Page number. Only used together with limit
orderBy string false Column to sort by, e.g. created_at
orderDirection string false asc or desc. Used together with orderBy
slim boolean false Returns a lighter response. See Slim response
trashed string false with includes deleted leads, only returns only deleted leads
selected_statuses array false Filter by current status. See Statuses
daterange[from] date false Lead creation date, format Y-m-d. Must be used with daterange[to]
daterange[to] date false Lead creation date, format Y-m-d. Inclusive (end of day)
{field} string false Filter on a lead field. See Filtering
{relation}__{field} string false Filter on a related model. See Filtering
customField__{slug} string false Filter on a custom field value. See Filtering

# Filtering

Any extra query parameter is used as a filter. All filters are combined with AND.

# Lead fields

Use the column name directly. The match is a partial match (LIKE %value%), except for slug, which must match exactly.

Example Matches
slug=a1b2c3d4e5f6g7h The lead with exactly this slug
special_id=12345 Leads whose special_id contains 12345
media_source=facebook Leads whose media_source contains facebook
description=kitchen Leads whose description contains kitchen

Separate the relation and the field with a double underscore __. Up to two levels of relations are supported.

Example Matches
customer__email=john@doe.com Leads where the customer's email contains the value
customer__phone=12345678 Leads where the customer's phone contains the value
customer__address__zip=1234 Leads where the customer's zip contains the value
dealer__name=Dealer 1 Leads where the accepting dealer's name contains the value
campaign__slug=abcdef Leads from campaigns whose slug contains the value
tags__name=VIP Leads with a tag whose name contains the value
products__slug=abc123 Leads with a product whose slug contains the value

Available relations include customer, customer__address, dealer, campaign, products, tags, notes and statuses.

# Custom fields

Use customField__ followed by the slug of the custom field. The value is a partial match.

customField__a1b2c3=123456

WARNING

Only use field and relation names that exist. An unknown field name will cause the request to fail.

# Statuses

selected_statuses filters on the lead's current status. Pass one or more of the following ids:

Id Status
1 Awaiting accept
2 Subject accepted
3 Manual distribution
4 Subject not contacted
5 Awaiting evaluation
6 Goal not reached
7 Goal reached
8 Disagreement customer says no
9 Disagreement customer says yes
10 Rejected
11 Ignored
12 Reminder sent
13 Stopped
14 Paused

Example: selected_statuses[]=5&selected_statuses[]=7

# Using daterange

daterange[from] is start of day and daterange[to] is end of day, both based on the lead creation date.

So if you want the leads from january:

✅ daterange[from]=2023-01-01&daterange[to]=2023-01-31

❌ daterange[from]=2023-01-01&daterange[to]=2023-02-01

# Slim response

With slim=1 fewer relations are loaded, which makes the request considerably faster. The following fields are returned as null:

customerEvaluation, dealerEvaluation, statuses, last_sent_to

TIP

Leave out slim entirely if you want the full response. Sending slim=false is treated as true.

# Pagination

When limit is set, the response is paginated and includes links and meta. Use page to fetch the next pages.

When limit is not set, all matching leads are returned in data without links and meta. For companies with many leads it is recommended to always use limit.

# Example

All leads created in january, awaiting evaluation, 50 per page, newest first:

https://app.lamatool.com/api/v3/leads?api_key=[YOUR_API_KEY]&daterange[from]=2023-01-01&daterange[to]=2023-01-31&selected_statuses[]=5&limit=50&orderBy=created_at&orderDirection=desc

Find a lead by the customer's email:

https://app.lamatool.com/api/v3/leads?api_key=[YOUR_API_KEY]&customer__email=john@doe.com

Find a lead by its slug:

https://app.lamatool.com/api/v3/leads?api_key=[YOUR_API_KEY]&slug=a1b2c3d4e5f6g7h

# Example result

{
    "data": [
        {
            "id": 48,
            "slug": "a1b2c3d4e5f6g7h",
            "special_id": null,
            "description": "This is a test",
            "media_source": "facebook",
            "campaign_id": 1,
            "campaign": { ... },
            "company_id": 1,
            "company": { ... },
            "customer_id": 52,
            "customer": {
                "id": 52,
                "name": "John Doe",
                "phone": "12345678",
                "email": "john@doe.com",
                "address": {
                    "streetname": "Doe street",
                    "number": "108A 2, 1",
                    "zip": 1234,
                    "city": "Doe city",
                    ...
                },
                ...
            },
            "customer_address": "Doe street 108A 2, 1, 1234 Doe city",
            "dealer_id": 6,
            "dealer": { ... }, // The dealer that accepted the lead, null if not accepted
            "sent_to": [ ... ], // All dealers the lead has been sent to
            "last_sent_to": { ... },
            "products": [ ... ],
            "tags": [ ... ],
            "custom_fields": [ ... ],
            "notes": [ ... ],
            "attachments": [ ... ],
            "current_status": {
                "id": 5,
                "description": "Awaiting evaluation",
                "lead_id": 48,
                "dealer_id": 6,
                "created_at": "2023-01-12T10:15:00.000000Z",
                "status_until": null,
                "status_reason": null,
                ...
            },
            "statuses": [ ... ], // Full status history
            "is_deleted": false,
            "created_at": "2023-01-10T09:00:00.000000Z",
            "formatted_created_at": "09:00:00 10/01-2023",
            "updated_at": "2023-01-12T10:15:00.000000Z",
            ...
        },
        ...
    ],
    // Only when using limit
    "links": {
        "first": "https://app.lamatool.com/api/v3/leads?page=1",
        "last": "https://app.lamatool.com/api/v3/leads?page=4",
        "prev": null,
        "next": "https://app.lamatool.com/api/v3/leads?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 4,
        "per_page": 50,
        "to": 50,
        "total": 187
    }
}

← Search leads →