Files

The Files API lets you upload, download, move, rename, and delete files and folders stored in Addepar. You can associate files with entities and groups for organized access through the Client Portal.

Overview


Base route	`/v1/files`
Produces	JSON
Pagination	Yes
OAuth scopes	GET `FILES`; POST, PATCH, DELETE `FILES_WRITE`

📘
Access requirements
Application permissions: "API Access: Create, edit, and delete" for all operations.
Files: View Only is required for GET endpoints.
Files: Create, edit and delete is required for POST, PATCH, and DELETE endpoints.

Resource attributes

Attribute	Type	Description
`name`	String	The file or folder name. Required for creation. Example: `"Sample.pdf"`
`content_type`	String	Read-only. The MIME type of the file, or `"folder"` for folders.
`created_at`	String	Read-only. ISO 8601 timestamp of creation.
`modified_at`	String	Read-only. ISO 8601 timestamp of last modification.
`deleted_at`	String	Read-only. ISO 8601 timestamp of deletion. Only present for archived files.
`bytes`	Number	Read-only. File size in bytes.
`is_folder`	Boolean	Read-only. `true` if the resource is a folder.
`parent_folder_id`	Number	The ID of the parent folder. `0` for top-level items.
`file_path`	String	Write-only. Specifies the folder path for upload. Example: `"Sample/Folder/Path/"`
`checksum_md5`	String	Read-only. MD5 checksum of the file content.

Query parameters

Use these parameters to filter results on GET /v1/files, GET /v1/files/:id, and GET /v1/archive/files.

Parameter	Description
`filter[files][createdAfter]`	Files created after this time. ISO 8601 format.
`filter[files][createdBefore]`	Files created before this time. ISO 8601 format.
`filter[files][entityId]`	Files associated with this entity ID.
`filter[files][groupId]`	Files associated with this group ID.
`filter[files][includedObjects]`	What to return: `FILES_ONLY` (default), `FOLDERS_ONLY`, or `FILES_AND_FOLDERS`.
`filter[files][parentFolderId]`	Files within this folder ID.

Relationships

Relationship	Description
`associated_entities`	Entities associated with the file.
`associated_groups`	Groups associated with the file.

Get all files

Returns all files you have access to. Use query parameters to filter by type, folder, date range, or association.

GET /v1/files

curl -X GET "https://{firm}.addepar.com/api/v1/files" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

{
  "data": [
    {
      "id": "123",
      "type": "files",
      "attributes": {
        "content_type": "application/PDF",
        "bytes": 256201,
        "name": "Sample.pdf",
        "created_at": "2014-06-20T20:55:07Z"
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/123/relationships/associated_groups",
            "related": "/v1/files/123/associated_groups"
          },
          "data": [
            { "type": "groups", "id": "1234" }
          ]
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/123/relationships/associated_entities",
            "related": "/v1/files/123/associated_entities"
          },
          "data": [
            { "type": "entities", "id": "10000" }
          ]
        }
      },
      "links": { "self": "/v1/files/123" }
    }
  ],
  "links": { "next": null }
}

To get only folders:

curl -X GET "https://{firm}.addepar.com/api/v1/files?filter[files][includedObjects]=FOLDERS_ONLY" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

To get files and folders within a specific folder:

curl -X GET "https://{firm}.addepar.com/api/v1/files?filter[files][includedObjects]=FILES_AND_FOLDERS&filter[files][parentFolderId]=12345" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

Response codes:

200 OK -- Success
400 Bad Request -- Invalid query parameter
403 Forbidden -- Insufficient permissions

Get a file or folder

Returns details for a single file or folder.

GET /v1/files/:id

curl -X GET "https://{firm}.addepar.com/api/v1/files/123" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

{
  "data": {
    "id": "123",
    "type": "files",
    "attributes": {
      "content_type": "application/PDF",
      "bytes": 256201,
      "name": "Sample.pdf",
      "created_at": "2014-06-20T20:55:07Z"
    },
    "relationships": {
      "associated_groups": {
        "links": {
          "self": "/v1/files/123/relationships/associated_groups",
          "related": "/v1/files/123/associated_groups"
        },
        "data": [
          { "type": "groups", "id": "1234" }
        ]
      },
      "associated_entities": {
        "links": {
          "self": "/v1/files/123/relationships/associated_entities",
          "related": "/v1/files/123/associated_entities"
        },
        "data": [
          { "type": "entities", "id": "10000" }
        ]
      }
    },
    "links": { "self": "/v1/files/123" }
  }
}

Response codes:

200 OK -- Success
400 Bad Request -- Invalid query parameter
403 Forbidden -- Insufficient permissions
404 Not Found -- File not found

Download a file

Returns the raw file contents as a binary download.

GET /v1/files/:id/download

curl -X GET "https://{firm}.addepar.com/api/v1/files/123/download" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -o "Sample.pdf"

The response includes Content-Disposition: attachment; filename="Sample.pdf" and Content-Type: application/binary.

Response codes:

200 OK -- Success
403 Forbidden -- Insufficient permissions
404 Not Found -- File not found

Upload a file

Uploads a new file using multipart/form-data. The request has two parts: the file content and a JSON metadata part.

The file extension in the name attribute must match the filename in Content-Disposition.

POST /v1/files

curl -X POST "https://{firm}.addepar.com/api/v1/files" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: multipart/form-data; boundary=BOUNDARY" \
  -d '--BOUNDARY
Content-Disposition: form-data; name="file"; filename="Sample.txt"
Content-Type: text/plain

<RAW_FILE_DATA>

--BOUNDARY
Content-Disposition: form-data; name="metadata"

{
  "data": {
    "type": "files",
    "attributes": {
      "name": "Sample.txt"
    }
  }
}
--BOUNDARY--'

{
  "data": {
    "id": "1111",
    "type": "files",
    "attributes": {
      "content_type": "text/plain",
      "bytes": 256201,
      "name": "Sample.txt",
      "created_at": "2017-01-01T20:55:07Z"
    },
    "relationships": {
      "associated_groups": {
        "data": []
      },
      "associated_entities": {
        "data": []
      }
    },
    "links": { "self": "/v1/files/1111" }
  }
}

Upload to a folder: Set parent_folder_id in attributes, or use the file_path attribute to specify a folder path by name. When uploading to a top-level folder that has nested folders, set parent_folder_id to 0 and include portfolio relationships. For nested folders, either provide the parent folder ID or a unique file_path string.

curl -X POST "https://{firm}.addepar.com/api/v1/files" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: multipart/form-data; boundary=BOUNDARY" \
  -d '--BOUNDARY
Content-Disposition: form-data; name="file"; filename="Sample.txt"
Content-Type: text/plain

<RAW_FILE_DATA>

--BOUNDARY
Content-Disposition: form-data; name="metadata"

{
  "data": {
    "type": "files",
    "attributes": {
      "name": "Sample.txt",
      "parent_folder_id": 12345
    }
  }
}
--BOUNDARY--'

Response codes:

201 Created -- Success
400 Bad Request -- Invalid payload, missing file, or inaccessible entities/groups
403 Forbidden -- Insufficient permissions

Rename or move a file

Updates a file's name or parent folder. To rename, set name. To move, set parent_folder_id.

PATCH /v1/files/:id

curl -X PATCH "https://{firm}.addepar.com/api/v1/files/1111" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "id": "1111",
      "type": "files",
      "attributes": {
        "name": "RenamedFile.txt"
      }
    }
  }'

curl -X PATCH "https://{firm}.addepar.com/api/v1/files/1111" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": {
      "id": "1111",
      "type": "files",
      "attributes": {
        "parent_folder_id": 54321
      }
    }
  }'

Response codes:

200 OK -- Success
400 Bad Request -- Invalid payload
403 Forbidden -- Insufficient permissions
404 Not Found -- File not found

Delete a file or folder

Archives a file or folder (and everything inside it). Archived items remain accessible through the archive endpoints.

DELETE /v1/files/:id

curl -X DELETE "https://{firm}.addepar.com/api/v1/files/1111" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

Response: 204 No Content on success.

Response codes:

204 No Content -- Success
403 Forbidden -- Insufficient permissions
404 Not Found -- File not found

Manage entity and group associations

Three operations for managing file associations with entities and groups:

Operation	Method	Endpoint	Behavior
Get associations	GET	`/v1/files/:id/relationships/associated_entities`	Returns entity or group IDs linked to the file.
Get associations	GET	`/v1/files/:id/relationships/associated_groups`	Returns entity or group IDs linked to the file.
Add associations	POST	`/v1/files/:id/relationships/associated_entities`	Appends entities or groups to the file.
Add associations	POST	`/v1/files/:id/relationships/associated_groups`	Appends entities or groups to the file.
Replace associations	PATCH	`/v1/files/:id/relationships/associated_entities`	Replaces all entity or group associations.
Replace associations	PATCH	`/v1/files/:id/relationships/associated_groups`	Replaces all entity or group associations.
Remove associations	DELETE	`/v1/files/:id/relationships/associated_entities`	Removes specified entities or groups.
Remove associations	DELETE	`/v1/files/:id/relationships/associated_groups`	Removes specified entities or groups.

POST, PATCH, and DELETE accept the same body format:

{
  "data": [
    { "type": "entities", "id": "100" },
    { "type": "entities", "id": "101" }
  ]
}

For group associations, use "type": "groups".

curl -X POST "https://{firm}.addepar.com/api/v1/files/123/relationships/associated_entities" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -d '{
    "data": [
      { "type": "entities", "id": "100" },
      { "type": "entities", "id": "101" }
    ]
  }'

GET returns a linkage array:

{
  "links": {
    "self": "/v1/files/123/relationships/associated_entities",
    "related": "/v1/files/123/associated_entities"
  },
  "data": [
    { "type": "entities", "id": "10000" },
    { "type": "entities", "id": "10001" }
  ]
}

POST, PATCH, and DELETE return 204 No Content on success.

Response codes (all association endpoints):

200 OK -- Success (GET)
204 No Content -- Success (POST, PATCH, DELETE)
400 Bad Request -- Invalid payload or inaccessible entities/groups
403 Forbidden -- Insufficient permissions
404 Not Found -- File not found

Archived files

Archived (deleted) files and folders remain accessible through a separate set of read-only endpoints. These support the same query parameters as active file endpoints.

Endpoint	Description
GET `/v1/archive/files`	List all archived files. Supports `includedObjects` and `parentFolderId` filters.
GET `/v1/archive/files/:id`	Get a single archived file with its `deleted_at` timestamp.
GET `/v1/archive/files/:id/download`	Download an archived file's contents.

curl -X GET "https://{firm}.addepar.com/api/v1/archive/files/319" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"

{
  "data": {
    "id": "319",
    "type": "files",
    "attributes": {
      "content_type": "text/plain",
      "bytes": 21607,
      "name": "archived_transactions.csv",
      "created_at": "2017-03-15T20:31:49Z",
      "deleted_at": "2017-03-15T20:32:16Z"
    },
    "relationships": {
      "associated_groups": {
        "data": []
      },
      "associated_entities": {
        "data": [
          { "type": "entities", "id": "22" }
        ]
      }
    },
    "links": { "self": "/v1/archive/files/319" }
  }
}

Response codes:

200 OK -- Success
400 Bad Request -- Invalid query parameter
403 Forbidden -- Insufficient permissions
404 Not Found -- Archived file not found

📘
Related

Generated Reports -- Access report output files

Entities -- Entities that files can be associated with

Groups -- Groups that files can be associated with

Pagination -- Paginate through file lists

Access & Authentication -- API key setup

Files

Overview

📘
Access requirements

Resource attributes

Query parameters

Relationships

Get all files

Get a file or folder

Download a file

Upload a file

Rename or move a file

Delete a file or folder

Manage entity and group associations

Archived files

📘
Related

Overview

📘Access requirements

Resource attributes

Query parameters

Relationships

Get all files

Get a file or folder

Download a file

Upload a file

Rename or move a file

Delete a file or folder

Manage entity and group associations

Archived files

📘Related

📘
Access requirements

📘
Related