Contacts API: create, list, update and search

How to manage Omnifox contacts through the REST API: create, search, update, and merge duplicates.

Jul 11, 2026

Watch this step in the video · Contacts via API

The Contacts API lets you sync your customer base with external systems (CRM, ERP, spreadsheets, automations) without going through the Omnifox interface. All endpoints live under /api/v1/contacts and require a Bearer token obtained via POST /api/v1/auth/login.

Requirements

  • A valid Bearer token (Sanctum) for the workspace the contact belongs to.
  • Optional: ?workspace_id= query parameter if your token has access to multiple workspaces.

Main endpoints

  • GET /api/v1/contacts — paginated list, filterable by tag, email, phone, country, and custom fields via filter[cf.<key>].
  • GET /api/v1/contacts/search — free-text search.
  • POST /api/v1/contacts — creates a contact (first_name is the only required field).
  • GET/PUT/DELETE /api/v1/contacts/{contact} — view, update, or delete a single contact.
  • POST /api/v1/contacts/upsert — creates or updates based on a match on email/phone/channel.
  • POST /api/v1/contacts/merge — merges duplicate contacts.
  • POST /api/v1/contacts/{contact}/tags — attaches tags.

Fields when creating a contact

{
  "first_name": "Maria",
  "last_name": "Garcia",
  "email": "[email protected]",
  "phone": "+593991234567",
  "country": "EC",
  "custom_fields": { "company": "Acme Corp" },
  "tags": ["VIP", "Prospect"]
}

Example: search contacts tagged VIP

curl -X GET "https://app.omnifox.io/api/v1/contacts?tag=VIP&per_page=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

The response returns the list in data, plus meta (current page, total count) and links for pagination.

Tips

  • Use upsert for integrations that receive data from external forms — it prevents duplicates by email or phone.
  • The include=custom_fields,channel_identities parameter pulls relationships without extra calls.
  • Before running merge, double-check which contact stays as the "primary" one: merges can't be undone.

Troubleshooting

  • 403 Forbidden: your token doesn't have access to that workspace; check the workspace_id.
  • 422 on create: missing first_name, or email/phone has an invalid format.
  • Contact missing from search results: filter[cf.*] filters only apply to custom fields with entity_type=contact; verify the field's internal key in Settings.
Was this helpful?

Related articles

Message us on WhatsApp