---
title: Custom API and payload mapping
slug: custom-api-and-payload-mapping
docTags: 
createdAt: 2026-09-16T08:57:52.333Z
---

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.

![](https://api.archbee.com/api/optimize/LSvaQ8v7MiAYpp8V288yP/ekKpxFbVCgaNlxvYDpiLq_custom-api-endpoint.jpg)

## 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:

```shell
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:

```shell
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.