Deals API

The Deals API provides endpoints for managing deals in your sales pipeline. Create deals, update values, move between stages, and retrieve forecasting data. All responses include the full deal object with related leads and contacts.

List deals

curl -X GET "https://api.skode.ai/v1/deals?pipeline_id=pipe_default&stage=proposal&sort=-value" \
  -H "Authorization: Bearer sk_live_your_api_key"

Filter by pipeline_id, stage, owner_id, status (open/won/lost), value_min, value_max, close_date_after, close_date_before.

Create a deal

const response = await fetch('https://api.skode.ai/v1/deals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Enterprise License - Acme Corp',
    value: 120000,
    currency: 'USD',
    pipeline_id: 'pipe_default',
    stage: 'qualification',
    expected_close_date: '2026-06-30',
    lead_id: 'lead_abc123',
    contact_ids: ['contact_xyz789'],
    owner_id: 'user_456',
    custom_fields: {
      product_line: 'Enterprise',
      contract_length: '12 months'
    }
  })
});

Required fields: title, pipeline_id. The deal is placed in the first stage if stage is not specified.

Update deal stage

curl -X PATCH "https://api.skode.ai/v1/deals/deal_xyz789" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"stage": "negotiation", "value": 135000}'

Stage changes are logged in the deal's activity timeline. Automation rules configured for stage transitions will fire automatically.

Close a deal

curl -X POST "https://api.skode.ai/v1/deals/deal_xyz789/close" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "won", "close_reason": "Competitive pricing", "actual_value": 130000}'

Set outcome to won or lost. Lost deals require a close_reason. Closing a deal as won can trigger invoice generation if configured.

Pipeline forecast

curl -X GET "https://api.skode.ai/v1/deals/forecast?pipeline_id=pipe_default&period=Q2-2026" \
  -H "Authorization: Bearer sk_live_your_api_key"

Returns weighted forecast (deal value multiplied by stage probability), best-case and worst-case scenarios, and comparison to the previous period. Group results by owner, stage, or month using the group_by parameter.

Delete a deal

curl -X DELETE "https://api.skode.ai/v1/deals/deal_xyz789" \
  -H "Authorization: Bearer sk_live_your_api_key"

Returns 204 No Content. Deleted deals are recoverable from trash for 30 days.