Documents

The Documents API allows you to manage files and documents within the Meridian CRM system.

Authentication

All requests must include a Bearer token in the HTTP header:

Authorization: Bearer ACCESS_TOKEN

Endpoints

List Documents

Description: Retrieve a list of documents from the user's organization.

Endpoint: GET api/public/v1/documents/

Optional Query Parameters:

search (string): Filter by document name or description
ordering (string): Order results by specific fields (e.g., name, created for descending)
company (UUID): Filter by associated company
deal (UUID): Filter by associated deal
folder (UUID): Filter by parent folder

Response Example:

[
  {
    "id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "name": "Contract.pdf",
    "description": "Final contract document",
    "file_type": "pdf",
    "size": 1024000,
    "created": "2025-04-26T09:15:00Z",
    "modified": "2025-04-26T09:15:00Z",
    "is_folder": false,
    "parent_folder": {
      "id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
      "name": "Contracts"
    },
    "company": {
      "id": "bfcd725e-88da-41cd-8d9c-6aed5dda1a4a",
      "title": "Acme Corp"
    },
    "deal": {
      "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "title": "Enterprise Software License"
    },
    "user": {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "first_name": "John",
      "last_name": "Doe"
    }
  },
  {
    "id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
    "name": "Contracts",
    "description": "Contract documents folder",
    "file_type": null,
    "size": null,
    "created": "2025-04-25T14:30:00Z",
    "modified": "2025-04-26T09:15:00Z",
    "is_folder": true,
    "parent_folder": null,
    "company": {
      "id": "bfcd725e-88da-41cd-8d9c-6aed5dda1a4a",
      "title": "Acme Corp"
    },
    "deal": null,
    "user": {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "first_name": "John",
      "last_name": "Doe"
    }
  }
]

Get Document Details

Description: Retrieve details for a specific document.

Endpoint: GET api/public/v1/documents/{id}/

Response Example:

{
  "id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
  "name": "Contract.pdf",
  "description": "Final contract document",
  "file_type": "pdf",
  "size": 1024000,
  "created": "2025-04-26T09:15:00Z",
  "modified": "2025-04-26T09:15:00Z",
  "is_folder": false,
  "parent_folder": {
    "id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
    "name": "Contracts",
    "is_folder": true
  },
  "organization": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "company": {
    "id": "bfcd725e-88da-41cd-8d9c-6aed5dda1a4a",
    "title": "Acme Corp",
    "website": "<https://acme-corp.com/>"
  },
  "deal": {
    "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
    "title": "Enterprise Software License"
  },
  "user": {
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "download_url": "<https://api.meridian-ai.com/api/v1/documents/1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f/download/>",
  "preview_url": "<https://api.meridian-ai.com/api/v1/documents/1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f/preview/>",
  "versions": [
    {
      "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
      "version_number": 1,
      "created": "2025-04-26T09:15:00Z"
    }
  ],
  "tags": [
    {
      "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "name": "Contract",
      "color": "#0000FF"
    }
  ]
}

Upload Document

Description: Upload a new document.

Endpoint: POST api/public/v1/documents/

Request Example:

# Multipart form data
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="proposal.pdf"
Content-Type: application/pdf

(Binary file data)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="name"

Proposal.pdf
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="description"

Project proposal document
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="parent_folder"

3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="company"

bfcd725e-88da-41cd-8d9c-6aed5dda1a4a
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="deal"

7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response: Returns the created document object with HTTP 201 status code.

Create Folder

Description: Create a new folder.

Endpoint: POST api/public/v1/documents/folders/

Request Example:

{
  "name": "Proposals",
  "description": "Project proposal documents",
  "parent_folder": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
  "company": "bfcd725e-88da-41cd-8d9c-6aed5dda1a4a",
  "deal": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}

Response: Returns the created folder object with HTTP 201 status code.

Update Document

Description: Update an existing document's metadata.

Endpoint: PUT api/public/v1/documents/{id}/

Request Example:

{
  "name": "Updated Contract.pdf",
  "description": "Updated contract document",
  "parent_folder": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b"
}

Response: Returns the updated document object.

Delete Document

Description: Delete a document.

Endpoint: DELETE api/public/v1/documents/{id}/

Response: Returns HTTP 204 No Content on success.

Download Document

Description: Download a document file.

Endpoint: GET api/public/v1/documents/{id}/download/

Response: Returns the document file as a binary stream with appropriate Content-Type and Content-Disposition headers.

Preview Document

Description: Get a preview of a document.

Endpoint: GET api/public/v1/documents/{id}/preview/

Optional Query Parameters:

page (integer): Page number for multi-page documents
width (integer): Desired width of the preview image
height (integer): Desired height of the preview image

Response: Returns a preview image of the document with appropriate Content-Type header.

Upload New Version

Description: Upload a new version of an existing document.

Endpoint: POST api/public/v1/documents/{id}/versions/

Request Example:

# Multipart form data
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="contract_v2.pdf"
Content-Type: application/pdf

(Binary file data)
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="comment"

Updated with client feedback
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response: Returns the created document version object with HTTP 201 status code.

List Document Versions

Description: Retrieve versions of a document.

Endpoint: GET api/public/v1/documents/{id}/versions/

Request Example:

[
  {
    "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
    "document": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "version_number": 1,
    "created": "2025-04-26T09:15:00Z",
    "user": {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "first_name": "John",
      "last_name": "Doe"
    },
    "comment": null,
    "size": 1024000,
    "download_url": "<https://api.meridian-ai.com/api/v1/documents/versions/5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d/download/>"
  },
  {
    "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "document": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "version_number": 2,
    "created": "2025-04-28T14:30:00Z",
    "user": {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "first_name": "John",
      "last_name": "Doe"
    },
    "comment": "Updated with client feedback",
    "size": 1048576,
    "download_url": "<https://api.meridian-ai.com/api/v1/documents/versions/7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f/download/>"
  }
]

Download Document Version

Description: Download a specific version of a document.

Endpoint: GET api/public/v1/documents/versions/{version_id}/download/

Response: Returns the document version file as a binary stream with appropriate Content-Type and Content-Disposition headers.

Manage Tags

Description: Add, update, or remove tags for documents.

Endpoint: POST api/public/v1/documents/tags/

Request Example:

{
  "name": "Contract",
  "color": "#0000FF"
}

Response: Returns the created tag object with HTTP 201 status code.

Update Endpoint: PUT api/public/v1/documents/tags/{id}/

Request Example:

{
  "name": "Legal Contract",
  "color": "#0000FF"
}

Response: Returns the updated tag object.

Delete Endpoint: DELETE api/public/v1/documents/tags/{id}/

Response: Returns HTTP 204 No Content on success.

Add Tag to Document

Description: Associate a tag with a document.

Endpoint: POST api/public/v1/documents/{document_id}/add-tag/{tag_id}/

Response: Returns HTTP 200 OK on success.

Remove Tag from Document

Description: Remove a tag association from a document.

Endpoint: DELETE api/public/v1/documents/{document_id}/remove-tag/{tag_id}/

Response: Returns HTTP 204 No Content on success.

Metadata Endpoints

Document Metadata

Description: Retrieve metadata about document fields, including field names, types, and whether they are required, createable, or updateable.

Endpoint: GET api/public/v1/documents/metadata/fields/

Request Example:

{
  "fields": [
    {
      "name": "name",
      "label": "Document Name",
      "type": "string",
      "required": true,
      "createable": true,
      "updateable": true
    },
    {
      "name": "description",
      "label": "Description",
      "type": "text",
      "required": false,
      "createable": true,
      "updateable": true
    },
    {
      "name": "file",
      "label": "File",
      "type": "file",
      "required": true,
      "createable": true,
      "updateable": false
    },
    {
      "name": "is_folder",
      "label": "Is Folder",
      "type": "boolean",
      "required": false,
      "createable": true,
      "updateable": false
    },
    {
      "name": "parent_folder",
      "label": "Parent Folder",
      "type": "reference",
      "reference_to": "document",
      "required": false,
      "createable": true,
      "updateable": true
    },
    {
      "name": "company",
      "label": "Company",
      "type": "reference",
      "reference_to": "company",
      "required": false,
      "createable": true,
      "updateable": true
    },
    {
      "name": "deal",
      "label": "Deal",
      "type": "reference",
      "reference_to": "deal",
      "required": false,
      "createable": true,
      "updateable": true
    }
  ]
}

Document Version Metadata

Description: Retrieve metadata about document version fields.

Endpoint: GET api/public/v1/documents/versions/metadata/fields/

Request Example:

{
  "fields": [
    {
      "name": "document",
      "label": "Document",
      "type": "reference",
      "reference_to": "document",
      "required": true,
      "createable": true,
      "updateable": false
    },
    {
      "name": "file",
      "label": "File",
      "type": "file",
      "required": true,
      "createable": true,
      "updateable": false
    },
    {
      "name": "comment",
      "label": "Comment",
      "type": "string",
      "required": false,
      "createable": true,
      "updateable": false
    }
  ]
}

Document Tag Metadata

Description: Retrieve metadata about document tag fields.

Endpoint: GET api/public/v1/documents/tags/metadata/fields/

Request Example:

{
  "fields": [
    {
      "name": "name",
      "label": "Name",
      "type": "string",
      "required": true,
      "createable": true,
      "updateable": true
    },
    {
      "name": "color",
      "label": "Color",
      "type": "string",
      "required": true,
      "createable": true,
      "updateable": true,
      "pattern": "^#[0-9A-Fa-f]{6}$"
    }
  ]
}

Error Responses

400 Bad Request: Invalid request parameters
401 Unauthorized: Missing or invalid authentication
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
413 Payload Too Large: File size exceeds the maximum allowed size
415 Unsupported Media Type: File type not supported
500 Internal Server Error: Server-side error

Data Models

Document

Field

Type

Description

UUID

Unique identifier

name

String

Document name

description

String

Document description

file_type

String

File extension or MIME type

size

Integer

File size in bytes

is_folder

Boolean

Whether the document is a folder

parent_folder

UUID

Reference to parent folder (optional)

organization

UUID

Reference to organization

company

UUID

Reference to associated company (optional)

deal

UUID

Reference to associated deal (optional)

user

UUID

Reference to user who uploaded the document

created

DateTime

Creation timestamp

modified

DateTime

Last modification timestamp

Document Version

Field

Type

Description

UUID

Unique identifier

document

UUID

Reference to document

version_number

Integer

Sequential version number

comment

String

Version comment or description

size

Integer

File size in bytes

user

UUID

Reference to user who created the version

created

DateTime

Creation timestamp

Tag

Field

Type

Description

UUID

Unique identifier

name

String

Tag name

color

String

Hex color code

organization

UUID

Reference to organization

created

DateTime

Creation timestamp

modified

DateTime

Last modification timestamp

Deals

Emails

Documents

Authentication

Endpoints

List Documents

Get Document Details

Upload Document

Create Folder

Update Document

Delete Document

Download Document

Preview Document

Upload New Version

List Document Versions

Download Document Version

Manage Tags

Add Tag to Document

Remove Tag from Document

Metadata Endpoints

Document Metadata

Document Version Metadata

Document Tag Metadata

Error Responses

Data Models

Document

Document Version

Tag

Discover how Meridian can streamline deal sourcing and enhance your decision-making