Skip to main content
The contacts API provides operator read access to the contact store, synced WhatsApp templates, campaigns, and journey definitions. These are internal endpoints intended for the operator application — they expose paginated lists you can use for search, dashboards, and configuration views. To create or update contacts from an external CRM or automation platform, use the compatibility endpoints instead.
All /internal/* endpoints are intended for the operator application and should be placed behind an authenticated session in production. Workspace scoping is enforced at the data layer.

​
GET /internal/contacts

List contacts from the current backing store. Supports pagination via limit and offset. 
curl "https://api.your-switchbord.example.com/internal/contacts?limit=50&offset=0"
​
limit
integer
Maximum number of contacts to return. Defaults to 50, capped at 200.
​
offset
integer
Number of contacts to skip for pagination. Defaults to 0. Must be non-negative.
Response:
​
contacts
array
Array of contact objects for the current page.
{
  "contacts": [
    {
      "id": "ctr_01hx...",
      "phoneNumber": "+15551234567",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "externalReferenceId": "crm_001",
      "subscriberStatus": "subscribed",
      "locale": "en_US"
    }
  ]
}
StatusCondition
200Contacts listed successfully

​
GET /internal/templates

List WhatsApp message templates synced from the Meta Graph API. Templates are synced from your connected WhatsApp Business Account and reflect the approved templates available for sending. 
curl "https://api.your-switchbord.example.com/internal/templates?limit=50&offset=0"
​
limit
integer
Maximum number of templates to return. Defaults to 50, capped at 200.
​
offset
integer
Number of templates to skip. Defaults to 0.
Response:
​
templates
array
Array of synced template records.
{
  "templates": [
    {
      "id": "tpl_01hx...",
      "name": "order_shipped_v2",
      "status": "approved",
      "category": "UTILITY",
      "language": "en_US",
      "components": [
        { "type": "BODY", "text": "Hi {{1}}, your order {{2}} has shipped!" }
      ]
    }
  ]
}
StatusCondition
200Templates listed successfully
Templates are synced from the Meta Graph API via a sync job, not fetched in real time. If you’ve recently submitted or approved a template and don’t see it here, trigger a template sync from the operator application.

​
GET /internal/campaigns

List campaign definitions from the current backing store. 
curl https://api.your-switchbord.example.com/internal/campaigns
Response:
​
campaigns
array
Array of campaign objects.
{
  "campaigns": [
    {
      "id": "cmp_01hx...",
      "name": "Summer Promo",
      "status": "active",
      "templateName": "summer_promo_v1"
    }
  ]
}
StatusCondition
200Campaigns listed successfully

​
GET /internal/journeys

List journey definitions from the current backing store. 
curl https://api.your-switchbord.example.com/internal/journeys
Response:
​
journeys
array
Array of journey definition objects.
{
  "journeys": [
    {
      "id": "jrn_01hx...",
      "name": "Welcome Flow",
      "status": "active",
      "triggerType": "api"
    }
  ]
}
StatusCondition
200Journeys listed successfully

​
Contact upsert from external systems

The read endpoints above are for the operator application. If you need to create or update contacts programmatically from a CRM, marketing platform, or other external system, use the compatibility endpoints:
  • POST /compat/contact — upsert with a Charles-compatible request body
  • PUT /api/v1beta/contact/ — same behavior with a legacy response shape
See Compatibility for full request schemas and response examples.