CRM API: deals, companies and pipelines

How to create and move deals, manage companies, and query Omnifox's CRM pipelines via API.

Jul 11, 2026

Watch this step in the video · CRM and calendar via API

Omnifox's CRM module organizes sales opportunities (deals) into pipelines with stages, linked to contacts and companies. The API exposes that same model so you can integrate it with your ERP, spreadsheet, or BI tool.

Requirements

  • The workspace must have the crm_enabled plan feature; without it these endpoints return 403.
  • A Bearer token for the workspace.

Main endpoints

  • GET/POST /api/v1/crm/pipelines — list or create pipelines; GET /api/v1/crm/pipelines/{pipeline}/stages for their stages.
  • GET/POST /api/v1/crm/companies — companies; POST /api/v1/crm/companies/{company}/contacts to link contacts.
  • GET/POST /api/v1/crm/deals — deals.
  • PATCH /api/v1/crm/deals/{deal}/stage — move a deal to another stage.
  • GET /api/v1/crm/reports/funnel and /forecast — aggregate reports.

Deal fields

{
  "pipeline_id": 1,
  "stage_id": null,
  "title": "Annual renewal",
  "amount": 1200.0,
  "currency": "USD",
  "probability": 40,
  "contact_id": 55,
  "company_id": 12,
  "expected_close_date": "2026-09-01"
}

If you omit stage_id, the deal lands in the pipeline's first stage.

Example: move a deal to "Won"

curl -X PATCH "https://app.omnifox.io/api/v1/crm/deals/501/stage" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stage_id": 9}'

(Stage 9 must have is_won: true for the forecast to count it as a closed-won deal.)

Contact required and currency

  • When creating a deal (POST /api/v1/crm/deals), contact_id is required. Without it the API returns 422 with the error on contact_id.
  • When editing, a deal that already has a contact can't be left without one (422).
  • If you omit currency, the deal starts in the workspace's CRM Main currency (the one chosen in Settings; if none, the most used among deals, then the catalog's, and finally USD).

Tips

  • Every company accepts custom_fields; fetch them via GET /api/v1/crm/companies/{company}/custom-fields.
  • Use client_nonce when creating a deal from an integration that retries automatically, to avoid duplicates from double submits.

Troubleshooting

  • 403 on any /crm/* endpoint: the workspace's plan doesn't include CRM; check Settings > Billing.
  • Deal missing from the forecast: confirm the stage's is_won/is_lost flags are set correctly in the pipeline.
Was this helpful?

Related articles

Message us on WhatsApp