Menu

Deals

2 endpoints in the Mattering Sales API.

GETPOST deals/ User APIService tier

List deals, or create one with POST. derived from route

URL

  • User APIhttps://sales.mattering.io/api/user/v1/deals/
  • Service tierhttps://sales.mattering.io/api/internal/deals/

Query parameters

NameDefault
archived_onlynone
created_afternone
created_beforenone
fieldsnone
group_bynone
includenone
include_archivednone
sortnone
space_idnone
updated_afternone
updated_beforenone
viewnone

Body keys (JSON)

KeyRequiredDefault
custom_fieldsoptional or conditionalnone
nameoptional or conditionalnone
owner_emailoptional or conditionalnone
pipe_idoptional or conditionalnone
space_idoptional or conditionalnone
stageoptional or conditionalnone
statusoptional or conditionalnone
titleoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view, silently. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Pagination

Accepts limit and offset; the default page is 50 and the server caps limit at 200. The response meta carries total, returned, has_more and next_offset.

Responses

200 data and meta envelope, legacy keys repeated beside data

{
  "data": {
    "deals": [],
    "groups": "..."
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "returned": 0,
    "has_more": true,
    "next_offset": 0
  }
}

201 data and meta envelope, legacy keys repeated beside data

{
  "data": "...",
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "returned": 0,
    "has_more": true,
    "next_offset": 0
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_amount
400invalid_group_by
400name_required
400pipe_has_no_stages
401unauthorized
404owner_not_found
404pipe_not_found
404space_not_found_or_forbidden

Example

curl -X POST "https://sales.mattering.io/api/user/v1/deals/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "custom_fields": "...",
  "name": "...",
  "owner_email": "...",
  "pipe_id": "...",
  "space_id": "...",
  "stage": "...",
  "status": "...",
  "title": "..."
}'

Source: CRMCore/internal_api.py (internal_api.deals)

GETPATCHDELETE deals/{deal_id}/ User APIService tier

Read, update or delete one of the deals by id. derived from route

This read is not paginated. It returns at most 10 rows and does not report a total, so a result of exactly 10 may be truncated.

URL

  • User APIhttps://sales.mattering.io/api/user/v1/deals/{deal_id}/
  • Service tierhttps://sales.mattering.io/api/internal/deals/{deal_id}/

Path parameters

NameType
deal_idstr

Body keys (JSON)

KeyRequiredDefault
amountoptional or conditionalnone
currencyoptional or conditionalnone
custom_fieldsoptional or conditionalnone
descriptionoptional or conditionalnone
expected_close_dateoptional or conditionalnone
is_activeoptional or conditionalnone
owner_emailoptional or conditionalnone
probabilityoptional or conditionalnone
stageoptional or conditionalnone
statusoptional or conditionalnone
titleoptional or conditionalnone
valueoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view, silently. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope, legacy keys repeated beside data

{
  "data": "..."
}

200 data and meta envelope, legacy keys repeated beside data

{
  "data": {
    "deal": {
      "title": "...",
      "amount": "...",
      "currency": "...",
      "probability": "...",
      "expected_close_date": "2026-01-01",
      "description": "...",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "id": "...",
      "is_archived": true,
      "pipe_id": "...",
      "pipe": "...",
      "stage_id": "...",
      "stage": "...",
      "status": "...",
      "owner_email": "...",
      "business_id": "...",
      "primary_contact_id": "...",
      "custom_index": {
        "...": "..."
      }
    },
    "deleted": true
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_amount
400invalid_expected_close_date
400invalid_probability
400name_required
400no_writable_fields
401unauthorized
404not_found
404owner_not_found

Example

curl -X PATCH "https://sales.mattering.io/api/user/v1/deals/DEAL_ID/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "...",
  "currency": "...",
  "custom_fields": "...",
  "description": "...",
  "expected_close_date": "...",
  "is_active": "...",
  "owner_email": "...",
  "probability": "..."
}'

Source: CRMCore/internal_api.py (internal_api.deal_detail)

All Sales resources
Start Free Explore our Products