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

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:

StatuserrorWhat it means
401X-Secret-Key header is requiredThe header is missing.
400lead_id and message are requiredThe body is missing one of the two fields.
404Lead not foundNo lead has this lead_id.
404Source not foundThe lead’s source no longer exists.
400Integration is not enabledThe lead’s source doesn’t use a Lead Reply API integration, or its Enabled is off.
401Invalid secret keyThe 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:

  1. Wire up the REST Webhook so your system gets notified of new leads and messages.
  2. Turn on the Lead Reply API for the same sources and copy its secret.
  3. In your system, when you want to reply to a lead, call the Lead Reply API with the secret, the lead_id and 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

Troubleshooting


Questions about the Lead Reply API? Email support@nzleads.com.

Get Started