API Reference

Deals

Create deals in your CRM pipeline. Uses the secret key for authentication.

Create a Deal

POST /api/v1/deals Secret Key

Creates a new deal in a CRM pipeline. Automatically assigns to the default pipeline and first open stage if not specified.

Parameters

Parameter	Type	Required	Description
name	string	Yes	Deal name
target_value	number	No	Deal value
target_close_date	string	No	ISO 8601 date or datetime
stage	string	No	Pipeline stage key
description	string	No	Deal description
source	string	No	Deal source
loss_reason	string	No	Reason for loss (if applicable)
pipeline_id	integer	No	Specific pipeline ID
pipeline_name	string	No	Pipeline name (used if pipeline_id not given)
created_by_email	string	No	Creator's email (defaults to first account user)
owner_email	string	No	Deal owner's email
contact_email	string	No	Associates a contact with the deal (creates contact if not found)
contact_name	string	No	Name for the contact (used when creating a new contact)
company_domain	string	No	Associates a company with the deal, found by domain (creates if not found)
company_name	string	No	Used to find or create the company when no domain is given, and as the name on a newly created company
company_phone	string	No	Phone number set on a newly created company (existing companies are not overwritten)

Success Response (201)

{
  "id": 42,
  "name": "Acme Corp Enterprise",
  "stage": "qualified",
  "pipeline_id": 1,
  "pipeline": "Sales Pipeline",
  "target_value": 15000.0,
  "target_close_date": "2025-03-15T00:00:00Z",
  "source": "website",
  "description": "Enterprise plan inquiry",
  "owner": "Jane Smith",
  "company": "Acme Corp",
  "created_at": "2025-01-15T10:30:00Z"
}

Error Response (422)

{
  "error": "name is required"
}

// or validation errors:
{
  "errors": ["Target value must be greater than 0"]
}