Skip to main content
POST
/
contacts
curl -X POST https://api.guayaba.ai/contacts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
  -d '{
    "phoneNumber": "+15551234567",
    "name": "Jane Smith",
    "splitterId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customVariables": {
      "company": "Acme Corp",
      "leadSource": "website",
      "loanAmount": "50000"
    }
  }'

{
  "success": true,
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "adminId": "8f14e45f-ceea-467a-9575-d0e9e3c8b8a3",
    "campaignId": "550e8400-e29b-41d4-a716-446655440000",
    "phoneNumber": "+15551234567",
    "name": "Jane Smith",
    "timezone": "America/New_York",
    "status": "active",
    "customVariables": {
      "company": "Acme Corp",
      "leadSource": "website",
      "loanAmount": "50000"
    },
    "createdAt": "2026-05-13T14:30:00.000Z",
    "updatedAt": "2026-05-13T14:30:00.000Z"
  }
}
Send a contact to a splitter and let it pick which campaign to enroll them in. This uses the same POST /contacts endpoint as Create Contact — the only difference is that you send splitterId instead of campaignId. All splitter management (create, update, stats, distribution strategies) is handled by admins in the dashboard. This endpoint is the only one integrators need.

​
Request Body

​
phoneNumber
string
required
Phone number in E.164 format (e.g., +15551234567).
​
splitterId
string (UUID)
required
The ID of the splitter to route this contact through.
Send either splitterId or campaignId, not both. If both are provided, campaignId takes priority and the splitter is ignored.
​
name
string
Full name of the contact.
​
customVariables
object
Flat key-value pairs of custom data to store on the contact. All values must be strings — send numbers as "50000", not 50000.These variables are passed to the assigned campaign and available for template substitution in SMS, WhatsApp templates, and voice agent prompts as {{company}}, {{leadSource}}, etc.

​
Authentication

Either method works:
  • JWT token: Authorization: Bearer <jwt-token>
  • API key: X-API-Key: <api-key> — rate limited to 30 writes per minute.

​
What happens after the contact is created

  1. The splitter picks a campaign based on its distribution strategy (percentage, time-weighted, or adaptive).
  2. The contact is created in the chosen campaign with all provided customVariables.
  3. The distribution decision is logged (visible in the splitter’s Distribution Logs in the dashboard).
  4. The campaign’s schedule kicks in — calls, SMS, and WhatsApp are scheduled based on that campaign’s configuration.
  5. customVariables are available for template substitution in all outbound messages.

​
Existing contacts

If a contact with the same phone number already exists for this admin:
  • If active: the contact is updated with the new name and customVariables, then reassigned to the splitter’s chosen campaign. Existing scheduled calls, SMS, and WhatsApp are cancelled and rescheduled.
  • If soft-deleted: the contact is reactivated with the new data and assigned to the splitter’s chosen campaign.
This matches the existing behavior for direct campaignId contact creation.

​
Response

​
success
boolean
Always true on a successful request.
​
data
object
The created or updated contact object.

​
Errors

StatusErrorWhen
400Splitter distribution failed: Splitter has no active campaignsAll campaigns in the splitter are deactivated.
400Splitter distribution failed: No valid campaigns found in splitterAll campaigns in the splitter were deleted.
400Invalid phone numberPhone number format is invalid or not in allowed country codes.
404Splitter not found or inactiveSplitter doesn’t exist, was deleted, or is paused.
429Rate limit exceededMore than 30 requests/minute with API key auth.

​
Zapier

The Zapier endpoint also supports splitters: 
POST /contacts/zapier
Same fields, same behavior. Custom variables can be sent as flat top-level fields — Zapier transform middleware will nest them into customVariables automatically. 
curl -X POST https://api.guayaba.ai/contacts \
  -H "Content-Type: application/json" \
  -H "X-API-Key: gua_a1b2c3d4_your-api-key-here" \
  -d '{
    "phoneNumber": "+15551234567",
    "name": "Jane Smith",
    "splitterId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "customVariables": {
      "company": "Acme Corp",
      "leadSource": "website",
      "loanAmount": "50000"
    }
  }'

{
  "success": true,
  "data": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "adminId": "8f14e45f-ceea-467a-9575-d0e9e3c8b8a3",
    "campaignId": "550e8400-e29b-41d4-a716-446655440000",
    "phoneNumber": "+15551234567",
    "name": "Jane Smith",
    "timezone": "America/New_York",
    "status": "active",
    "customVariables": {
      "company": "Acme Corp",
      "leadSource": "website",
      "loanAmount": "50000"
    },
    "createdAt": "2026-05-13T14:30:00.000Z",
    "updatedAt": "2026-05-13T14:30:00.000Z"
  }
}