CRM API: deals, companies and pipelines

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.)

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 > Plan and billing.
• Deal missing from the forecast: confirm the stage's is_won/is_lost flags are set correctly in the pipeline.