Boiler down at 11pm. Tradespeople alerted before the customer calls back.
See how the API works →A customer calls at 23:00 reporting no heating. Your call handler logs the fault, checks a spreadsheet for out-of-hours contractors, leaves a voicemail, and promises a callback by 8am. The customer wakes up cold and angry, posts on X, and cancels their cover plan. Out-of-hours dispatch failures are your biggest churn driver — and they're entirely preventable.
A message, sent and delivered live on the platform. TPS-screened before every send. ICO registered: ZC164080.
A fault is logged out of hours; you POST the customer's number and postcode. Only those two fields are required — who to reach and where the job is. Everything else is optional attribution.
curl -X POST https://app.pipeiq.co.uk/api/leads/register \ -H "Content-Type: application/json" \ -H "X-PipeIQ-Token: YOUR_API_KEY" \ -d '{ "mobile_number": "07700900000", "postcode": "NE1 7RU", "selected_trade": "gas", "utm_source": "ooh-dispatch", "utm_campaign": "boiler-faults" }'
A 201 Created response means the lead was registered and the welcome SMS was
dispatched; the body returns the matched postcode sector. mobile_number accepts
07xxxxxxxxx or 447xxxxxxxxx. selected_trade takes plumbing,
gas, electrical, roofing, building or
all; it is not validated, so an unrecognised or omitted value is recorded as
Other rather than rejected. Full field and response reference on the
Partner API page.
Lead distribution fails quietly when nobody handles the unhappy path. One of these you must never retry.
| Code | Meaning | What to do |
|---|---|---|
201 | Lead registered, welcome SMS dispatched | Store the returned postcode sector against the lead. |
400 | Missing or invalid fields | Fix the payload; do not retry unchanged. |
401 | Invalid or missing API key | Check the header. Never put the key in client-side code. |
405 | Wrong HTTP method | POST only. OPTIONS returns 200 for CORS preflight; everything else is rejected. |
422 | Number previously opted out | Do not retry. Mark the lead unreachable by SMS and route it another way. |
429 | Daily call limit reached (100 per key per 24h) | Back off and resume; email support to raise the cap. Sandbox keys share this status. |
500 | Unexpected server error | Retry with backoff; contact support with your request id if it persists. |
The 422 is the one worth designing around. It is not a transport failure, it is a lawful-basis answer: that person has told us not to text them. Retrying it is the easiest way to turn a compliance feature into a compliance incident.