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
| Name | Default |
|---|---|
archived_only | none |
created_after | none |
created_before | none |
fields | none |
group_by | none |
include | none |
include_archived | none |
sort | none |
space_id | none |
updated_after | none |
updated_before | none |
view | none |
Body keys (JSON)
| Key | Required | Default |
|---|---|---|
custom_fields | optional or conditional | none |
name | optional or conditional | none |
owner_email | optional or conditional | none |
pipe_id | optional or conditional | none |
space_id | optional or conditional | none |
stage | optional or conditional | none |
status | optional or conditional | none |
title | optional or conditional | none |
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
| Status | Code |
|---|---|
| 400 | invalid_amount |
| 400 | invalid_group_by |
| 400 | name_required |
| 400 | pipe_has_no_stages |
| 401 | unauthorized |
| 404 | owner_not_found |
| 404 | pipe_not_found |
| 404 | space_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": "..."
}'curl -X POST "https://sales.mattering.io/api/internal/deals/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-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)