Lead Reply API
The Lead Reply API lets an external system send replies back into NZ Leads so they’re delivered to the lead as if your team sent them from inside the app: your system posts the lead’s ID and the text, and NZ Leads sends the text to the customer on the platform the lead came from. This is the pair of the REST Webhook integration: the webhook sends lead data out, the Lead Reply API posts replies back in. Together they let a developer-owned workflow fully own the conversation.
You set the Lead Reply API up once and then choose which sources accept replies through it. In Add integration it’s listed as Lead Reply API under Webhooks and automation. Add it from a source’s Messaging Settings → Integrations tab, or from Settings → Integrations in the menu, which lists all your integrations. Voice agents can’t use it. Use it alongside the REST Webhook if you want a full outbound-plus-inbound integration.
What you’ll get
- A Secret key that your external system uses to authenticate when sending replies.
- The ability to post outbound messages back to the lead from your own software.
- Inbound activity from the lead still shows up in NZ Leads (and in your webhook receiver if you have one wired up).
Connecting the Lead Reply API
Add the Lead Reply API
In NZ Leads, open the source → Messaging Settings → Integrations tab → Add integration → Create new → Lead Reply API. Its window opens. If your account already has a Lead Reply API integration, pick it on the Use existing tab instead.
Generate and copy the Secret key
Click Generate Secret Key. Click the eye icon next to Secret Key: to show the key, then copy it and store it as a credential in your external system. Your system will include this key on every call it makes to the Lead Reply API so NZ Leads can confirm the call really came from you.
You can Regenerate the secret at any time. Regenerating invalidates the old key immediately - update your caller at the same time.
Turn on the Enabled toggle
The Enabled toggle appears once a key exists. The API won’t accept replies until it is on; until then calls get the error “Integration is not enabled”.
To accept replies for another source’s leads, open that source’s Integrations tab → Add integration → Use existing and pick this integration, or tick the source under Where it’s used in its window. If you added the Lead Reply API on the Integrations page, it isn’t used anywhere yet: tick the sources under Where it’s used.
Options
Enable
Turns this Lead Reply API integration on or off everywhere it’s used. Default: off. When off, calls to the Lead Reply API for leads of the sources that use it are rejected. To stop accepting replies for one source only, switch it off on that source’s Integrations tab, or untick the source under Where it’s used.
Secret key
The credential your external system uses to authenticate. Keep it secret and rotate it (via Regenerate) if it’s ever exposed. The old key stops working the moment a new one is generated.
Remove the key
The delete button next to the key removes it at once, without a confirmation, and turns the integration off. Calls with the old key are rejected. Click Generate Secret Key to make a new one.
Sending a reply
Your system sends a POST to the endpoint shown under Payload Example on the card - it ends with /api/rest-webhook/inbound - with the X-Secret-Key header and a JSON body holding lead_id (from the REST Webhook payload) and message (the reply text):
POST /api/rest-webhook/inbound
Content-Type: application/json
X-Secret-Key: your-secret-key
{
"lead_id": "lead123",
"message": "Hi! We can help you with that..."
}
A successful call returns {"ok": true}. A refused call returns {"ok": false, "error": "..."} with one of these errors:
| Status | error | What it means |
|---|---|---|
401 | X-Secret-Key header is required | The header is missing. |
400 | lead_id and message are required | The body is missing one of the two fields. |
404 | Lead not found | No lead has this lead_id. |
404 | Source not found | The lead’s source no longer exists. |
400 | Integration is not enabled | The lead’s source doesn’t use a Lead Reply API integration, or its Enabled is off. |
401 | Invalid secret key | The key isn’t the current key of the Lead Reply API integration the lead’s source uses. |
The key is checked against the Lead Reply API integration that the lead’s source uses: a key from another Lead Reply API integration doesn’t work for that lead, even in the same account. If the platform can’t take the reply - for example, Facebook Messenger and Instagram accept replies only within 24 hours of the customer’s last message - the call returns an error status as well.
Typical setup
The Lead Reply API is used together with the REST Webhook, which gives your system each lead’s lead_id:
- Wire up the REST Webhook so your system gets notified of new leads and messages.
- Turn on the Lead Reply API for the same sources and copy its secret.
- In your system, when you want to reply to a lead, call the Lead Reply API with the secret, the
lead_idand the reply text. The reply is delivered to the lead.
If you’re taking over the conversation entirely, turn on Skip welcome message & follow-ups in the source’s Messaging Settings → Conversation Setup (shown while the AI Assistant is off) so NZ Leads’s automated messages don’t interfere with yours.
When a source moves to another account
If a source that uses this Lead Reply API moves to another account while other places keep using it, the moved source gets its own copy with a new secret key. The copy stays on if the original was on, and shows “Copied from another account with a new secret key. Give your system the new key to keep replying to leads.” under its errors. From then on, replies to that source’s leads need the copy’s key.
Disconnecting
- For one source - switch the Lead Reply API off on that source’s Integrations tab, or untick the source under Where it’s used. Calls for that source’s leads get Integration is not enabled.
- Everywhere - click the delete button next to the key (the secret is cleared and the integration is turned off), turn off Enabled, or click Delete integration in its window. Any external system still calling with the old secret will get rejected.
Troubleshooting
- Calls being rejected - Confirm Enable is on and that your caller is sending the current secret. If you regenerated it, old callers need to be updated. The key must be the one of the Lead Reply API integration the lead’s source uses - after a move to another account, the key of the copy.
Integration is not enabled- Check that Enabled is on and that the lead’s source uses this integration on its Integrations tab.Lead not found- Use thelead_idfrom the REST Webhook payload exactly as it arrived.- Replies aren’t reaching the lead - Make sure you’re identifying the correct lead in your call, and that the lead’s conversation is still open on the source.
- I want the reverse direction too - Enable the REST Webhook for the same sources so your system also gets notified of inbound activity.
Questions about the Lead Reply API? Email support@nzleads.com.