Contacts API: create, list, update and search

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.