Menu
GETPOST files/ User APIService tier

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

URL

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

Query parameters

NameDefault
document_typenone
sortnone

Pagination

Accepts limit and offset. The response meta carries total, returned, has_more and next_offset.

Responses

200 data and meta envelope

{
  "data": {
    "files": [
      {
        "id": "...",
        "title": "...",
        "description": "...",
        "document_type": "...",
        "filename": "...",
        "file_size": "...",
        "mime_type": "...",
        "is_private": true,
        "tags": [
          "..."
        ],
        "contact_id": "...",
        "business_id": "...",
        "uploaded_by": "...",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-01T00:00:00Z"
      }
    ]
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "returned": 0,
    "has_more": true,
    "next_offset": 0
  }
}

201 data and meta envelope

{
  "data": {
    "file": {
      "id": "...",
      "title": "...",
      "description": "...",
      "document_type": "...",
      "filename": "...",
      "file_size": "...",
      "mime_type": "...",
      "is_private": true,
      "tags": [
        "..."
      ],
      "contact_id": "...",
      "business_id": "...",
      "uploaded_by": "...",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  },
  "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
400anchor_mismatch
400missing_field
404business_not_found
404contact_not_found
413file_too_large
502file_service_unavailable

Example

curl -X GET "https://sales.mattering.io/api/user/v1/files/?document_type=...&sort=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: CRMCore/files_api.py (files_api.files)

POST files/upload/finalize/ User APIService tier

Record a finished direct upload as a file on the record.

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

URL

  • User APIhttps://sales.mattering.io/api/user/v1/files/upload/finalize/
  • Service tierhttps://sales.mattering.io/api/internal/files/upload/finalize/

Body keys (JSON)

KeyRequiredDefault
business_idoptional or conditionalnone
contact_idoptional or conditionalnone
content_typeoptional or conditionalnone
descriptionoptional or conditionalnone
document_typeoptional or conditionalnone
filenameoptional or conditionalnone
is_privateoptional or conditionalnone
titleoptional or conditionalnone
upload_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

201 data and meta envelope

{
  "data": {
    "file": {
      "id": "...",
      "title": "...",
      "description": "...",
      "document_type": "...",
      "filename": "...",
      "file_size": "...",
      "mime_type": "...",
      "is_private": true,
      "tags": [
        "..."
      ],
      "contact_id": "...",
      "business_id": "...",
      "uploaded_by": "...",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  }
}

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

Errors

StatusCode
400anchor_mismatch
400invalid_document_type
400invalid_json
400invalid_upload
400missing_field
404business_not_found
404contact_not_found
404upload_not_found
409direct_upload_unavailable
502file_service_unavailable

Example

curl -X POST "https://sales.mattering.io/api/user/v1/files/upload/finalize/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "business_id": "...",
  "contact_id": "...",
  "content_type": "...",
  "description": "...",
  "document_type": "...",
  "filename": "...",
  "is_private": "...",
  "title": "..."
}'

Source: CRMCore/files_api.py (files_api.upload_finalize)

POST files/upload/init/ User APIService tier

Start a direct upload: returns a URL to PUT the bytes to, and the ``upload_id`` to hand back to finalize.

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

URL

  • User APIhttps://sales.mattering.io/api/user/v1/files/upload/init/
  • Service tierhttps://sales.mattering.io/api/internal/files/upload/init/

Body keys (JSON)

KeyRequiredDefault
business_idoptional or conditionalnone
contact_idoptional or conditionalnone
content_typeoptional or conditionalnone
file_sizeoptional or conditionalnone
filenameoptional 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": {
    "mode": "multipart",
    "detail": "Direct uploads are not available on this server; POST the file to files/ instead."
  }
}

200 data and meta envelope

{
  "data": {
    "mode": "direct",
    "upload_url": "...",
    "upload_id": "...",
    "method": "PUT",
    "headers": {
      "Content-Type": "..."
    }
  }
}

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

Errors

StatusCode
400anchor_mismatch
400invalid_file_size
400invalid_json
400missing_field
404business_not_found
404contact_not_found
413file_too_large

Example

curl -X POST "https://sales.mattering.io/api/user/v1/files/upload/init/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "business_id": "...",
  "contact_id": "...",
  "content_type": "...",
  "file_size": "...",
  "filename": "..."
}'

Source: CRMCore/files_api.py (files_api.upload_init)

GETPATCHDELETE files/{file_id}/ User APIService tier

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

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

URL

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

Path parameters

NameType
file_iduuid

Body keys (JSON)

KeyRequiredDefault
descriptionoptional or conditionalnone
document_typeoptional or conditionalnone
is_privateoptional or conditionalnone
tagsoptional 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.

Responses

200 data and meta envelope

{
  "data": {
    "id": "...",
    "deleted": true
  }
}

200 data and meta envelope

{
  "data": {
    "file": {
      "id": "...",
      "title": "...",
      "description": "...",
      "document_type": "...",
      "filename": "...",
      "file_size": "...",
      "mime_type": "...",
      "is_private": true,
      "tags": [
        "..."
      ],
      "contact_id": "...",
      "business_id": "...",
      "uploaded_by": "...",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  }
}

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

Errors

StatusCode
400invalid_document_type
400invalid_json
400tags_must_be_list
404not_found

Example

curl -X PATCH "https://sales.mattering.io/api/user/v1/files/FILE_ID/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "...",
  "document_type": "...",
  "is_private": "...",
  "tags": "...",
  "title": "..."
}'

Source: CRMCore/files_api.py (files_api.file_detail)

GET files/{file_id}/download/ User APIService tier

The file's bytes, streamed (``?inline=1`` for an inline disposition).

URL

  • User APIhttps://sales.mattering.io/api/user/v1/files/{file_id}/download/
  • Service tierhttps://sales.mattering.io/api/internal/files/{file_id}/download/

Path parameters

NameType
file_iduuid

Query parameters

NameDefault
inlinenone

Responses

200 non-JSON body

binary or text body

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

Errors

StatusCode
404file_unavailable
404not_found

Example

curl -X GET "https://sales.mattering.io/api/user/v1/files/FILE_ID/download/?inline=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: CRMCore/files_api.py (files_api.file_download)

All Sales resources
Start Free Explore our Products