Skip to main content

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.

ParameterTypeRequiredDescription
levelstringoptionalcampaign returns campaign records. mail_piece returns mail-piece records. Defaults to campaign.
location_idstringoptionalLimits results to one business location. Omitted, the response covers every location SearchLight can read.
startdate (YYYY-MM-DD)optionalReturns records with a drop date on or after this date.
enddate (YYYY-MM-DD)optionalReturns records with a drop date before this date.
updated_startdatetime (ISO 8601, UTC)optionalReturns records whose campaign was created or updated at or after this time.
updated_enddatetime (ISO 8601, UTC)optionalReturns records whose campaign was created or updated before this time.
pageintegeroptionalPage 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 200 with an empty data array, not an error.

Response envelope​

{
"page": 1,
"total_pages": 4,
"data": []
}

Campaign record (level=campaign)​

FieldTypeRequiredDescriptionExample
location_idstringrequiredYour stable identifier for the business location the campaign was mailed for. An id, not a name."12345"
campaign_idstringrequiredYour stable identifier for the campaign, unique within the location."1111111"
campaign_namestringrequiredDisplay name of the campaign, as the client would recognise it."Spring Tune-Up Postcard"
campaign_phone_numbersstring[]requiredEvery tracking number printed on the campaign's pieces.["000-000-0000"]
drop_datesdate[]requiredEvery date pieces of this campaign entered the mail.["2024-12-09"]
quantity_mailedintegerrequiredTotal pieces mailed for the campaign.8000
total_costnumberrequiredTotal cost of the campaign in dollars.3200
updated_atdatetime (ISO 8601, UTC)requiredWhen the campaign, or its mailing list, was created or last changed."2025-01-01T00:00:00.000Z"
location_namestringoptionalDisplay name of the business location."Jim's HVAC"
deletedbooleanoptionaltrue 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.

FieldTypeRequiredDescriptionExample
drop_datedaterequiredThe date this piece entered the mail."2024-12-09"
street_addressstringrequiredStreet address the piece was mailed to, including any unit."4870 EXAMPLE AVE STE 200"
citystringrequired"SAN DIEGO"
statestringrequiredTwo-letter state code."CA"
zip5stringrequiredFive-digit ZIP code."92123"
zip_plus4stringoptionalZIP+4."92123-1671"
campaign fieldslocation_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_id and campaign_id stay the same for the life of the record. Send them as strings so a numeric id is not reformatted in transit ("12345", not 12345.0).
  • One location_id is one business location. A client with several locations has one id per location. A campaign mailed for several locations is one campaign record per location_id, each with that location's own quantity and cost.
  • updated_at is 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's updated_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_at moves, 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: true and its updated_at moves 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_mailed and total_cost repeat the campaign's totals; they are not per-piece figures.
  • Tracking numbers are 10-digit US numbers. Punctuation and a leading 1 are ignored.
  • Dates are ISO 8601. Drop dates are calendar dates (YYYY-MM-DD); timestamps are UTC.

How SearchLight uses the API​

  1. Each night SearchLight requests the campaigns updated in the last few days (updated_start, updated_end, level=campaign), and removes any campaign marked deleted.
  2. 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.
  3. To load history when a location is first connected, it requests by location_id and drop-date range.