Deals

Deals represent revenue opportunities in your pipeline. Each deal has a name, value, stage, and can be associated with a company and contacts.

List Pipelines

GET /deals/pipelines

Returns all deal pipelines and their stages. Use this to get valid pipeline_id and stage_id values before creating deals.

curl "https://be.graph8.com/api/v1/deals/pipelines" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(
    f"{BASE_URL}/deals/pipelines",
    headers=HEADERS
)
pipelines = response.json()

Response

{
  "data": [
    {
      "id": "pipe-123",
      "name": "Sales Pipeline",
      "is_default": true,
      "stages": [
        {
          "id": "stage-1",
          "name": "Qualification",
          "probability": 10,
          "position": 0,
          "stage_type": "open",
          "color": "#3B82F6"
        },
        {
          "id": "stage-2",
          "name": "Proposal",
          "probability": 50,
          "position": 1,
          "stage_type": "open",
          "color": "#F59E0B"
        }
      ]
    }
  ]
}

List Deals

GET /deals

Returns all deals across the organization with pagination and optional filters.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	50	Items per page (max 200)
`stage_id`	string	—	Filter by stage ID
`pipeline_id`	string	—	Filter by pipeline ID
`search`	string	—	Search by deal name

Example

cURL
Python

curl "https://be.graph8.com/api/v1/deals?search=Enterprise&limit=10" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(
    f"{BASE_URL}/deals",
    headers=HEADERS,
    params={"search": "Enterprise", "limit": 10}
)

Response

{
  "data": [
    {
      "id": "deal-abc",
      "name": "Enterprise Contract",
      "amount": 50000,
      "currency": "USD",
      "stage_id": "stage-2",
      "stage_name": "Proposal",
      "pipeline_id": "pipe-123",
      "company_id": 456,
      "close_date": "2026-06-30T00:00:00",
      "created_at": "2026-02-20T10:00:00",
      "updated_at": "2026-02-25T14:30:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "has_next": false
  }
}

Create Deal

POST /deals

Creates a new deal. If pipeline_id is not specified, the organization’s default pipeline is used. If stage_id is not specified, the first stage in the pipeline is used.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Deal name
`company_id`	integer	No	Company to associate
`description`	string	No	Deal description
`amount`	number	No	Monetary value
`currency`	string	No	Currency code (default: `USD`)
`stage_id`	string	No	Stage ID from `/deals/pipelines`
`pipeline_id`	string	No	Pipeline ID (defaults to org default)
`close_date`	string	No	Expected close date (ISO 8601)

Example

cURL
Python

curl -X POST "https://be.graph8.com/api/v1/deals" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Contract",
    "amount": 50000,
    "company_id": 456,
    "close_date": "2026-06-30"
  }'

response = requests.post(
    f"{BASE_URL}/deals",
    headers=HEADERS,
    json={
        "name": "Enterprise Contract",
        "amount": 50000,
        "company_id": 456,
        "close_date": "2026-06-30"
    }
)

Returns 201 Created with the new deal object.

Get Deal

GET /deals/{deal_id}

Returns a single deal by ID.

Update Deal

PATCH /deals/{deal_id}

Partial update — send only the fields you want to change.

Request Body

Field	Type	Description
`name`	string	Deal name
`description`	string	Deal description
`amount`	number	Monetary value
`currency`	string	Currency code
`stage_id`	string	Stage ID
`close_date`	string	Expected close date (ISO 8601)

Delete Deal

DELETE /deals/{deal_id}

Returns 200 with {"data": {"deleted": true}} on success.

Get Contact Deals

GET /contacts/{contact_id}/deals

Returns all deals associated with a specific contact.

Example

cURL
Python

curl "https://be.graph8.com/api/v1/contacts/12345/deals" \
  -H "Authorization: Bearer $API_KEY"

response = requests.get(
    f"{BASE_URL}/contacts/12345/deals",
    headers=HEADERS
)

Response

{
  "data": [
    {
      "deal_id": "deal-abc",
      "name": "Enterprise Contract",
      "stage": "Proposal",
      "value": 50000,
      "currency": "USD",
      "pipeline_id": "pipe-123",
      "close_date": "2026-06-30",
      "created_at": "2026-02-20T10:00:00"
    }
  ]
}

Get Company Deals

GET /companies/{company_id}/deals

Returns all deals associated with a specific company. Same response shape as contact deals.