Direct Mail API
This document describes the API a direct-mail partner exposes so SearchLight can pull campaign and mailing data. SearchLight calls the API on a schedule; the partner does not push anything. For how a partner-built integration is set up, see the overview.
The API serves the same data at two levels of detail:
- Campaign level: one record per campaign, with its tracking numbers, drop dates, quantity and cost.
- Mail-piece level: one record per piece mailed, with the delivery address and the campaign it belongs to.
SearchLight uses campaign records to attribute tracked calls and report spend, and mail-piece records to match mailed addresses against the client's CRM.
Request
A single GET endpoint over HTTPS, authenticated with a bearer token or API key issued to SearchLight. Responses are JSON.
| Parameter | Type | Required | Description |
|---|---|---|---|
level | string | optional | campaign returns campaign records. mail_piece returns mail-piece records. Defaults to campaign. |
location_id | string | optional | Limits results to one business location. Omitted, the response covers every location SearchLight can read. |
start | date (YYYY-MM-DD) | optional | Returns records with a drop date on or after this date. |
end | date (YYYY-MM-DD) | optional | Returns records with a drop date before this date. |
updated_start | datetime (ISO 8601, UTC) | optional | Returns records whose campaign was created or updated at or after this time. |
updated_end | datetime (ISO 8601, UTC) | optional | Returns records whose campaign was created or updated before this time. |
page | integer | optional | Page number, starting at 1. |
Rules:
- Ranges are half-open: a record is included when its date is on or after the start and before the end. Consecutive requests then never return the same record twice or skip one.
- Filters combine: any mix of
location_id, a drop-date range and an updated range may be sent together, at either level. - Results are paged: every response reports
total_pages. Mail-piece responses for a single campaign can run to tens of thousands of records. - An empty result is a
200with an emptydataarray, not an error.
Response envelope
{
"page": 1,
"total_pages": 4,
"data": []
}
Campaign record (level=campaign)
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
location_id | string | required | Your stable identifier for the business location the campaign was mailed for. An id, not a name. | "12345" |
campaign_id | string | required | Your stable identifier for the campaign, unique within the location. | "1111111" |
campaign_name | string | required | Display name of the campaign, as the client would recognise it. | "Spring Tune-Up Postcard" |
campaign_phone_numbers | string[] | required | Every tracking number printed on the campaign's pieces. | ["000-000-0000"] |
drop_dates | date[] | required | Every date pieces of this campaign entered the mail. | ["2024-12-09"] |
quantity_mailed | integer | required | Total pieces mailed for the campaign. | 8000 |
total_cost | number | required | Total cost of the campaign in dollars. | 3200 |
updated_at | datetime (ISO 8601, UTC) | required | When the campaign, or its mailing list, was created or last changed. | "2025-01-01T00:00:00.000Z" |
location_name | string | optional | Display name of the business location. | "Jim's HVAC" |
deleted | boolean | optional | true when the campaign has been deleted or voided. Omitted or false otherwise. | false |
{
"location_id": "12345",
"location_name": "Jim's HVAC",
"campaign_id": "1111111",
"campaign_name": "Spring Tune-Up Postcard",
"campaign_phone_numbers": ["000-000-0000"],
"drop_dates": ["2024-12-09"],
"quantity_mailed": 8000,
"total_cost": 3200,
"updated_at": "2025-01-01T00:00:00.000Z"
}
Mail-piece record (level=mail_piece)
Each record carries the piece's own fields plus its campaign's fields, so a piece can be read without a second request.
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
drop_date | date | required | The date this piece entered the mail. | "2024-12-09" |
street_address | string | required | Street address the piece was mailed to, including any unit. | "4870 EXAMPLE AVE STE 200" |
city | string | required | "SAN DIEGO" | |
state | string | required | Two-letter state code. | "CA" |
zip5 | string | required | Five-digit ZIP code. | "92123" |
zip_plus4 | string | optional | ZIP+4. | "92123-1671" |
| campaign fields | location_id, location_name, campaign_id, campaign_name, campaign_phone_numbers, quantity_mailed, total_cost and updated_at, exactly as on the campaign record. |
{
"drop_date": "2024-12-09",
"street_address": "4870 EXAMPLE AVE STE 200",
"city": "SAN DIEGO",
"state": "CA",
"zip5": "92123",
"zip_plus4": "92123-1671",
"location_id": "12345",
"location_name": "Jim's HVAC",
"campaign_id": "1111111",
"campaign_name": "Spring Tune-Up Postcard",
"campaign_phone_numbers": ["000-000-0000"],
"quantity_mailed": 8000,
"total_cost": 3200,
"updated_at": "2025-01-01T00:00:00.000Z"
}
Data rules
- Identifiers are strings and never change.
location_idandcampaign_idstay the same for the life of the record. Send them as strings so a numeric id is not reformatted in transit ("12345", not12345.0). - One
location_idis one business location. A client with several locations has one id per location. A campaign mailed for several locations is one campaign record perlocation_id, each with that location's own quantity and cost. updated_atis the campaign's, at both levels. Any edit to a campaign (cost, quantity, drop dates, tracking numbers, name) or to its mailing list (a piece added, removed or corrected) moves the campaign'supdated_at. Every mail-piece record carries its campaign's value. SearchLight finds changes only through this field.- A campaign's mail pieces are replaced as a set. When a campaign's
updated_atmoves, SearchLight re-reads all of its mail pieces and discards what it held, so mail pieces need no identifier of their own. - A deleted campaign is marked, not removed. When a campaign is deleted or voided (cancelled before mailing, entered in error, a duplicate upload), its record stays in campaign-level responses with
deleted: trueand itsupdated_atmoves to the time of deletion. It keeps being returned for at least 30 days. SearchLight then removes the campaign, its spend and its mail pieces. A campaign that simply disappears from the API is never noticed and keeps reporting. Mail-piece responses omit the pieces of a deleted campaign. - Quantity and cost are campaign totals. On a mail-piece record,
quantity_mailedandtotal_costrepeat the campaign's totals; they are not per-piece figures. - Tracking numbers are 10-digit US numbers. Punctuation and a leading
1are ignored. - Dates are ISO 8601. Drop dates are calendar dates (
YYYY-MM-DD); timestamps are UTC.
How SearchLight uses the API
- Each night SearchLight requests the campaigns updated in the last few days (
updated_start,updated_end,level=campaign), and removes any campaign markeddeleted. - Where address matching is in use, it requests the mail pieces for the same updated range (
level=mail_piece) and replaces what it held for each campaign returned. - To load history when a location is first connected, it requests by
location_idand drop-date range.