Sending us leads over the API

The endpoint

POST to /v1/leads with your key in the Authorization header as a bearer token, and a JSON body. Your key identifies your account; there is nothing in the URL that names it, and nothing you can send that changes which account a lead lands on.

POST /v1/leads
Authorization: Bearer mk_live_…
Content-Type: application/json

{
  "source": "your-source-code",
  "external_id": "your-own-reference",
  "first_name": "Dana",
  "last_name": "Whitfield",
  "phone": "813-555-0142",
  "email": "dana@example.com",
  "state": "FL",
  "zip": "33601",
  "tort": "Roundup",
  "xxTrustedFormCertUrl": "https://cert.trustedform.com/…",
  "consent": {
    "text": "the exact wording this person was shown",
    "at": "2026-08-17T10:00:00Z",
    "ip": "203.0.113.10"
  }
}

What we refuse, and what we accept and flag

We refuse a lead only when it cannot be used at all. Everything else is accepted and screened, because a lead you sent is evidence of something even when it scores badly.

• Refused: no telephone number and no email address. There is nobody to contact.
• Refused: no source. We would not be able to tell you where it came from.
• Accepted and flagged: a missing or unrecognised claim type, a state that does not match the IP, a missing consent record, a duplicate. Each appears in the screening as a sentence.
• Sending the same external_id twice returns the SAME lead rather than creating a second one — so a request that timed out can safely be retried.

Consent

Send the wording the person was actually shown, with the time and their IP. We store it verbatim and record that it is your assertion rather than ours — because it is, and a compliance record that blurs that is worth less than one that does not.

We never invent a consent record for a lead that arrived without one. It is screened as missing.

Webhook signatures

If we deliver to a webhook of yours, every request carries an X-Matic-Signature header of the form t=<timestamp>,v1=<hex>. The hex is an HMAC-SHA256 over the timestamp, a full stop, and the exact request body, keyed with your signing secret.

Compare it in constant time, and reject anything whose timestamp is old — that is what stops somebody replaying a request they captured. We do not follow redirects when delivering, so a webhook that moves must be updated on your side rather than forwarded.

Things worth knowing before you build against it

• Screening runs after the lead is stored, never before. A lead is never lost because a check was slow.
• If screening cannot complete, the lead stays as received with a note. It is not marked good by default.
• Every read is scoped to your account. A lead id belonging to somebody else returns 404, the same as one that does not exist — a 403 would confirm it was real.
• A delivery that fails is recorded as failed and left for a person to look at. Nothing is retried automatically and nothing is marked delivered on optimism.