Skip to main content
Switchbord exposes compatibility endpoints and webhook ingress points so you can connect external CRM, marketing, and automation systems without rebuilding your existing workflows. Whether you are migrating from a legacy platform or adding new integrations, these endpoints accept the request shapes your existing systems already produce.

​
Contact sync from external systems

Use these endpoints to upsert a contact record from any external system.

​
Staged path

POST /compat/contact This is the recommended path for new integrations. It accepts the Charles-style contact update shape, including external_reference_id, source_type, and person_properties as first-class fields. 
curl -X POST https://your-switchbord.example.com/compat/contact \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "name": "Jane Smith",
    "tags": ["newsletter"]
  }'

​
Legacy path

PUT /api/v1beta/contact/ Use this path if you have an upstream system that was already sending to the Charles contact mutation endpoint. The response includes status and message fields to match the expected shape from that system.
Both paths accept the same contact payload shape. Use /compat/contact for new integrations and the legacy path only when an upstream system cannot be reconfigured.

​
Journey triggers from external systems

Trigger a Switchbord journey from any external system using one of these paths:
PathWhen to use
POST /compat/journey-trigger/{legacyPath}Compatibility path for systems that already know a Charles-style trigger path
POST /webhooks/v0/rest-trigger/organization/{org}/flow/{flow}/trigger/Versioned path for new integrations
POST /webhooks/v0/rest-trigger/organization/{org}/flow/{flow}/trigger/{triggerId}/Versioned path when you need to specify a trigger ID
Payloads are phone-number centric. Any additional personalization keys you include are accepted and forwarded into the queued job payload for the journey. Responses include status, message, triggerEventId, and outboxJobId.

​
Emarsys integration

Switchbord accepts Emarsys custom events at: POST /api/v0/webhooks/incoming/emarsys/custom_external_event

​
Authentication

When a shared secret is configured, Switchbord enforces it through the secret query parameter on every request. Include it as follows: 
curl -X POST "https://your-switchbord.example.com/api/v0/webhooks/incoming/emarsys/custom_external_event?secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "newsletter_signup",
    "phone": "+15551234567"
  }'

​
Payload rules

  • event_name is required and must not contain whitespace
  • Both flattened and nested contact payload styles are normalized automatically
  • A successful response returns status, message, webhookEventId, and outboxJobId

​
What Emarsys events can do

Once Switchbord receives an Emarsys event, it can:
  • Trigger a journey flow configured to listen for that event name
  • Mutate a contact record (for example, update tags or properties)

​
Twenty CRM sync

Switchbord supports bidirectional sync with Twenty CRM for contact data.
  • Contact property writes — journey steps that write properties or tags to a contact can reflect those changes back to Twenty CRM
  • Field mapping — you can configure which Switchbord contact fields map to Twenty CRM fields
  • Sync health — the product surfaces sync status so you can identify records that failed to propagate
Field mapping configuration is available in Settings once the Twenty integration is connected.

​
Outbound webhook events

Configure outbound webhooks in Settings to push Switchbord events to any external system — Zapier, n8n, a custom endpoint, or any HTTP listener.

​
Configuring an outbound webhook

1

Open Settings

Navigate to /settings and select the Webhooks section.
2

Add an endpoint

Enter the URL of your external system and select which event types you want to receive.
3

Save and test

Save the endpoint. Switchbord will begin delivering events to it as they occur.

​
Available event types

EventTriggered when
message.receivedAn inbound WhatsApp message arrives
message.deliveredA sent message is confirmed delivered
message.failedA send attempt fails
contact.opted_outA contact opts out of messaging
Outbound webhook delivery is best-effort. If your endpoint is unreachable, events may be dropped. Ensure your endpoint returns a 2xx response promptly to acknowledge receipt.