Custom API and payload mapping

7 min

Custom API automations let another system trigger Peach.

Use this when an external app, backend service, form, CRM, billing system, or internal tool should start an Automation Rule.

API styles

Peach supports two custom API styles in the automation builder.

Style	Endpoint	Best for
Automation endpoint	A rule-specific endpoint	One payload should trigger one automation.
Topic-mapped payload	The general events endpoint	Multiple automations may listen to the same topic.

Automation endpoint

Use the automation endpoint when the payload belongs to one specific rule.

After saving the rule, Peach shows the URL for that automation.

Example shape:

curl -X POST https://YOUR_DOMAIN/api/v1/streams/STREAM_ID/events \
  -H "X-Account-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "phone_number": "+14155550123",
      "name": "Jane Doe"
    }
  }'

Topic-mapped payload

Use topic-mapped payloads when the event should be routed by a topic name.

Example shape:

curl -X POST https://YOUR_DOMAIN/api/v1/events \
  -H "X-Account-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "lead.created",
    "contact": {
      "phone_number": "+14155550123",
      "name": "Jane Doe"
    }
  }'

The rule's topic condition must match the payload topic.

Recipient mapping

Recipient mapping tells Peach who the automation should run for.

Common fields are:

Field	Example JSONPath
Name	$.contact.name
Phone number	$.contact.phone_number
Email	$.contact.email

The phone number is the most important field for WhatsApp automations.

Template variable mapping

When an automation sends a WhatsApp template or Flow template with placeholders, map incoming payload fields to those variables.

For example, if a template needs order_id and delivery_date, map each placeholder to the matching field in the payload.

Deduplication keys

Deduplication keys help Peach avoid running the same automation twice for the same external event.

Use a stable external ID when available, such as:

Order ID

Payment ID

Event ID

Ticket ID

Testing tips

Start with a test contact and a narrow payload. Confirm that:

The API key is valid.

The topic or automation endpoint is correct.

The recipient phone number is present.

Template variables resolve correctly.

The rule is active.

The phone number is in a WhatsApp-ready format.