The Omnifox REST API: introduction and plan requirements

What the Omnifox REST API is, which plan you need (Crece and up), how to authenticate with the X-API-Key header, and where the docs live.

Jun 26, 2026

Watch this step in the video · Requirements: plan and permissions

What is the Omnifox REST API?

The REST API lets you read and create your workspace's data —contacts, conversations, messages, CRM, projects— from your own code or a no-code tool. It's the foundation for automating flows, syncing your CRM, or building custom integrations.

This guide covers the essentials to get started: plan requirements, authentication, and where the docs live.

Plan requirements

API access is a plan feature called API access. It's available from the Crece plan upward (Crece, Escala, and Exclusivo). The Lite and Conecta plans don't include it.

If your plan doesn't have it, the API keys section will be locked and any API call will respond with the code PLAN_API_ACCESS_REQUIRED.

Before you start

  • Administrator role for the workspace.
  • A plan with API access.
  • An API key already created (see below).

Steps

1. Create your API key

  1. Go to Settings → API Keys → New API key.
  2. Give it a name, choose the workspace, an expiration date, and check only the scopes you need: read:contacts, write:contacts, read:messages, write:messages, read:channels, read:crm, write:crm, read:projects, write:projects.
  3. Copy the key right away — it's shown only once.

2. Authenticate your calls

Send the token in the Authorization: Bearer header on every request:

curl https://omnifox.io/api/v1/contacts \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

3. Know the base URL

All endpoints live under /api/v1/. For example: /api/v1/contacts, /api/v1/conversations, /api/v1/messages.

4. Read the docs

The interactive reference is at omnifox.io/docs, and the OpenAPI spec at omnifox.io/api-docs/openapi.json to import into Postman or generate an SDK.

Verify it worked

A GET /api/v1/contacts call with a valid key returns 200 and JSON with your contacts. Responses are wrapped in { "success": true, "data": ... }.

If it doesn't work

  • PLAN_API_ACCESS_REQUIRED: your plan doesn't include API access. Upgrade to Crece or higher.
  • 401: the Authorization: Bearer header is missing, or the key expired or was revoked.
  • 403: the key lacks the scope needed for that endpoint; edit it and add the scope.
  • 404 on an endpoint: remember the path is /api/v1/..., not /v1/....

Tips

  • Create a separate key per integration and give it only the minimum scopes.
  • To receive real-time events (new messages, etc.) use Webhooks instead of polling.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp