Menu
GETPOST contacts/ User APIService tier

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

URL

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

Query parameters

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

Body keys (JSON)

KeyRequiredDefault
custom_fieldsoptional or conditionalnone
space_idoptional 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 response meta carries total, returned, has_more and next_offset.

Responses

200 data and meta envelope, legacy keys repeated beside data

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

200 data and meta envelope, legacy keys repeated beside data

{
  "data": {
    "contacts": []
  },
  "meta": "..."
}

200 data and meta envelope, legacy keys repeated beside data

{
  "data": {
    "custom_fields": "..."
  },
  "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_group_by
400invalid_record
400invalid_value
401unauthorized
404space_not_found_or_forbidden

Example

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

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

POST contacts/bulk/ User APIService tier

POST to contacts/bulk/. derived from route

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

URL

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

Body keys (JSON)

KeyRequiredDefault
dry_runoptional or conditionalnone
match_onoptional or conditionalnone
modeoptional or conditionalnone
recordsoptional or conditionalnone
space_idoptional 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

{
  "data": {
    "results": [
      {
        "index": "...",
        "status": "would_create",
        "id": "...",
        "custom_fields": "...",
        "defaults_applied": [
          "..."
        ],
        "ignored_fields": "...",
        "not_stored": "..."
      }
    ]
  },
  "meta": {
    "...": "..."
  }
}

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

Errors

StatusCode
400invalid_mode
400invalid_record
400invalid_value
400missing_field
400too_many_records
401unauthorized
404space_not_found_or_forbidden

Example

curl -X POST "https://sales.mattering.io/api/user/v1/contacts/bulk/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": "...",
  "match_on": "...",
  "mode": "...",
  "records": "...",
  "space_id": "..."
}'

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

POST contacts/merge/ User APIService tier

POST to contacts/merge/. derived from route

URL

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

Body keys (JSON)

KeyRequiredDefault
duplicate_idsoptional or conditionalnone
primary_idoptional 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

{
  "data": {
    "...": "..."
  }
}

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

Errors

StatusCode
400missing_field
401unauthorized
404not_found

Example

curl -X POST "https://sales.mattering.io/api/user/v1/contacts/merge/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "duplicate_ids": "...",
  "primary_id": "..."
}'

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

POST contacts/upsert/ User APIService tier

POST to contacts/upsert/. derived from route

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

URL

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

Body keys (JSON)

KeyRequiredDefault
custom_fieldsoptional or conditionalnone
domainoptional or conditionalnone
dry_runoptional or conditionalnone
emailoptional or conditionalnone
match_onoptional or conditionalnone
nameoptional or conditionalnone
recordsoptional or conditionalnone
space_idoptional or conditionalnone
websiteoptional 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

{
  "data": {
    "index": "...",
    "status": "would_create",
    "id": "...",
    "custom_fields": "...",
    "defaults_applied": [
      "..."
    ],
    "ignored_fields": "...",
    "not_stored": "..."
  },
  "meta": {
    "dry_run": true,
    "note": "..."
  }
}

200 data and meta envelope, legacy keys repeated beside data

{
  "data": {
    "custom_fields": "..."
  }
}

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

Errors

StatusCode
400invalid_match_on
400invalid_record
400invalid_value
400missing_field
401unauthorized
404space_not_found_or_forbidden
409ambiguous_match

Example

curl -X POST "https://sales.mattering.io/api/user/v1/contacts/upsert/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "custom_fields": "...",
  "domain": "...",
  "dry_run": "...",
  "email": "...",
  "match_on": "...",
  "name": "...",
  "records": "...",
  "space_id": "..."
}'

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

GETPATCHDELETE contacts/{contact_id}/ User APIService tier

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

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

URL

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

Path parameters

NameType
contact_idstr

Body keys (JSON)

KeyRequiredDefault
custom_fieldsoptional 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": {
    "contact": {
      "first_name": "...",
      "last_name": "...",
      "email": "...",
      "phone": "...",
      "title": "...",
      "lifecycle_stage": "...",
      "status": "...",
      "notes": [
        "..."
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z",
      "job_title": "...",
      "id": "...",
      "business_id": "...",
      "is_archived": true,
      "tags": [
        "..."
      ],
      "owner": "...",
      "owner_email": "...",
      "persona": {
        "id": "...",
        "name": "..."
      },
      "custom_fields": "..."
    },
    "deleted": true
  }
}

200 data and meta envelope, legacy keys repeated beside data

{
  "data": {
    "custom_fields": "..."
  }
}

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

Errors

StatusCode
400invalid_record
400invalid_value
400no_writable_fields
401unauthorized
404not_found

Example

curl -X PATCH "https://sales.mattering.io/api/user/v1/contacts/CONTACT_ID/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "custom_fields": "..."
}'

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

All Sales resources
Start Free Explore our Products