Retail Lead Management API (1.0)

Returns every lead in the pipeline matching {status} that the user in X-User-Email is allowed to see, most recently updated first.

A response carries at most 500 leads. This is a page, not a truncation: send no paging parameters and you get the first 500, exactly as if you had asked for page 1. A different limit may be configured for your account.

⚠️ If you previously received more than 500 leads from one call, you now receive 500 and must follow the pages to get the rest. Nothing errors, so an integration that ignores the Link header below will quietly process only the first page. This is the one thing to check before this change reaches you.

Read the rest with page[number] and page[size]. Asking for a page[size] above the limit - or below 1 - is refused with 422 and the standard error envelope rather than quietly given a different number, so you always know what you asked for. Nothing else about the size of the result set can produce an error.

Paging is advertised in a Link header (RFC 8288) on every response, including the 422 and including requests that asked for no page, with rel="first", rel="prev" and rel="next" as applicable. The response body is identical whether or not you paged - always a single data array, never a wrapper - so adding paging to an existing integration cannot change what it parses. Walk until no rel="next" is present.

There is no rel="last" and no total count: producing either would cost a full scan of the matching set on every request.

⚠️ Pages are cut from a list ordered by most recently updated first, and that ordering moves as leads are updated - so a lead can shift between pages while you walk them. For an unattended sync, page within a fixed by_datetime_since window rather than paging the whole history, or use the v3 API, whose ordering can be pinned to the immutable id.

For routine syncing, prefer open and narrow with the date parameters below rather than pulling all repeatedly.

Leads with no location or no division are dropped. Restricting this list to the pipelines, divisions and locations the user may see is an inner join on all three, so a lead whose location or division is empty matches nothing and never appears here - even though Lead documents both as nullable, and even though GET /api/v1/pipeline/{apiKey}/lead/{leadId} returns that same lead without complaint. If a lead is visible in the web app but never reaches your integration, check those two fields first.

Incremental syncing

To poll for changes, send by_date=updated together with by_datetime_since set to the timestamp of your last successful sync:

?by_date=updated&by_datetime_since=2026-08-05%2014:30:00

The two date parameters do not use the same clock. by_datetime_since is interpreted in your organization's configured time zone; by_date_at is a UTC calendar day and ignores your time zone entirely. For a Pacific dealer that means every lead taken after 5 p.m. local counts as the following UTC day.

Two more traps worth wiring around before you go live:

• Send a full timestamp, not a bare date. by_datetime_since=2026-08-05 is read as noon on that day, so it silently skips the morning.
• A by_datetime_since value that cannot be parsed - or a missing one - is not an error. It becomes a comparison against nothing, and the response is 201 with an empty data array. A wrong timestamp format therefore looks identical to "no new leads", forever. If a sync goes permanently quiet, re-check the value you are sending.

Returns one lead by its RLM id, in the same shape as an entry in the list response.

This endpoint does not use the 422 JSON envelope for every failure. It also returns 404 when the lead id does not exist in this pipeline, with an HTML body rather than JSON. Branch on the status before parsing.

Creates a lead in the pipeline identified by {apiKey}.

Note that this endpoint is not under /api/v1/ - its path is /api/{apiKey}/leads.

It takes no headers

The pipeline API key in the URL is the entire credential. This operation never reads X-Api-Key or X-User-Email; a request that sends neither is accepted and returns 201.

That has one important consequence. When a web-form vendor, chat widget or marketing platform posts leads on your behalf, give them the pipeline key and nothing else. Do not give a third party your organization API key for this endpoint - it is not used here, and it is the credential that reads every lead in your organization through /api/v1/. A pipeline key only writes into the one pipeline it names.

Four reserved keys change the shape of the request

Before anything else, RLM looks at the top level of the body for lead, contact, rawRequest or api, in that order. If one is present, its contents replace the entire payload and every other top-level key is discarded. This is how form vendors post: a JotForm webhook sends rawRequest, and lead and contact wrap a lead the same way.

Treat all four names as reserved. {"api": "web"} is not a lead with an api field - it is a malformed envelope, and it answers 500 rather than the 201 an unrecognised key would get. If you need to send a field called lead, contact, api or rawRequest, ask RLM support to configure an api_field_name for it and send that name instead.

If none of the four is present, the body itself is the payload. That is the ordinary case, and everything below describes it.

How keys are matched

Post a single lead object. For each key, RLM looks first for a pipeline field whose api_field_name matches, and failing that for a column on the lead with that name - which in practice is the field's column_name. Keys are lower-cased before either lookup.

api_field_name is an optional alias that somebody has to configure deliberately, and most pipelines have none set on any field, so column_name - as listed in pipeline_fields[] by GET /api/v1/pipeline/{apiKey} - is the normal answer to "what do I call this field?". Use api_field_name when the pipeline configuration shows one.

Neither is the label you see on a lead in RLM. A field shown as Lead Source is source_name on the wire, and the two are edited independently - see PipelineField for how each key maps to the pipeline's field settings. Give RLM support the display name when asking which key a field uses; give your own code the column_name.

A key matching neither is appended to the new lead as a note rather than being rejected, so a misspelled key name fails quietly. The note line uses the humanized key, so a stray first_name reads First name: Jane - not first_name: Jane. A note key is written into the note verbatim, with no prefix.

Some keys reach neither a field nor the note: formid, uniqueid, handshakekey, controller, action, api_key, salesperson_assignment, id, location_id, division_id, location_name, division_name, and any key whose value is blank. Several of those are acted on elsewhere in the request - the location and division keys file the lead - but none of them survive as a note, so do not rely on the note as a full record of what you posted.

The four reserved keys above are not in that list because they never get this far: they are read before the payload is walked, and a malformed one fails the request outright.

What you get back

The new lead is placed in the pipeline's initial status, and filed under the pipeline's default location and division unless the request supplies its own.

It is attributed to the pipeline's default salesperson, who is recorded as its creator - but it is not assigned to anyone. A lead created here comes back with salesperson and salesperson_id null and unassigned true, and stays that way until someone takes it in the web app. Do not read salesperson on a fresh lead to decide who owns it.

An empty or unrecognised payload does not fail. No key is required. Post an empty body and you get 201 and a blank lead sitting in the pipeline; post a body whose keys match nothing and you get 201 and a lead that is only a note. Validate the payload before you send it - nothing on this side will do it for you, and there is no response you can check for "that was not a real lead".

The one exception is a malformed envelope: a top-level lead, contact, api or rawRequest of the wrong type answers 500. That is the only shape of body this endpoint rejects.

Returns the organization identified by the X-Api-Key header, including its locations, divisions and pipelines.

Call this first: the pipelines[].id and pipelines[].name values tell you which pipelines exist and which one you mean.

This response does not contain pipeline API keys. Ask RLM support for the key of the pipeline you want to read; it is the {apiKey} path segment on every other endpoint.

Returns the configuration of a single pipeline: its fields, its lead statuses, and the locations and divisions available to it.

This is how you discover field names. A lead object carries the custom fields configured for its pipeline, so the pipeline_fields[] entries here tell you which keys to expect on a lead and what type each holds.