The Files API can be used to view and manage files stored in Addepar, as well as the groups and entities associated with the files.

Base Route | /v1/files |
Endpoints | GET /v1/files/:id /v1/files /v1/files/:id/download /v1/archive/files/:id /v1/archive/files/:id/download /v1/files/:id/relationships/associated_groups /v1/files/:idrelationships/associated_entities POST /v1/files/ /v1/files/:id/relationships/associated_groups /v1/files/:id/relationships/associated_entities PATCH /v1/files/:id /v1/files/:id/relationships/associated_groups /v1/files/:id/relationships/associated_entities DELETE /v1/files/:id /v1/files/:id/relationships/associated_groups /v1/files/:id/relationships/associated_entities |
Produces | JSON |
Pagination | Yes |
Application Permissions Required | "API Access: Create, edit, and delete" "Files: View Only" is required to retrieve and download files. All other operations require "Files: Create, edit and delete" permissions. |
OAuth Scopes | FILES or FILES_WRITE |
Resource Overview
Files are described by the below resource object attributes. Attributes required for creating, updating, or deleting the Files are noted.
Attribute | Description | Example |
---|---|---|
name | The file's name. String. Required for creation. | "Sample File.txt" |
content_type | The content type of the file. String. Not editable. | "application/PDF" |
created_at | Time stamp of the file's creation. String. ISO 8601 date format. | "2014-12-01T13:22:40Z" |
deleted_at | Time stamp of the file's deletion. String. ISO 8601 date format. | "2014-12-01T13:22:40Z" |
bytes | The size of the file in bytes. Number. Not editable. | 100000 |
Parameters
The GET All Files (/v1/files
), GET a Single File (/v1/files/:file-id
), and GET All Archived Files (/v1/archive/files
) requests can be filtered using the parameters below. The filters require the ISO 8601 date format.
Parameter | Description | Example |
---|---|---|
filter[files][createdAfter] | Returns only files created after a specific time. | /v1/files/?filter[files][createdAfter]=2017-04-06T20:12:45Z |
filter[files][createdBefore] | Returns only files created before a specific time. | /v1/files/?filter[files][createdBefore]=2017-04-06T20:12:45Z |
filter[files][createdAfter] &filter[files][createdBefore] | Returns only filters created within a specific time range. | /v1/files/?filter[files][createdAfter]=2017-04-05T20:12:45Z&filter[files][createdBefore]=2017-04-06T20:12:45Z |
filter[files][entityId] | Returns only files associated with the specific entity. | /v1/files?[files][entityId]=100 |
filter[files][groupId] | Returns only files associated with the specific group. | /v1/files?[files][groupId]=20 |
filter[files][entityId]&filter[files][groupId] | If IDs for both an entity and a group are included in a request, the API will ignore the group and return only the files associated with the entity. | /v1/files?[files][entityId]=100&filter[files][groupId]=20 |
Relationships
Relationship | Description |
---|---|
associated_groups | Groups associated with a file. |
associated_entities | Entities associated with a file. |
"relationships": {
"associated_groups": {
"links": {
"self": "/v1/files/123/relationships/associated_groups",
"related": "/v1/files/123/associated_groups"
},
"data": [
{
"type": "groups",
"id": "1234"
},
{
"type": "groups",
"id": "5678"
}
]
},
"associated_entities": {
"links": {
"self": "/v1/files/123/relationships/associated_entities",
"related": "/v1/files/123/associated_entities"
},
"data": [
{
"type": "entities",
"id": "10000"
},
{
"type": "entities",
"id": "10001"
}
]
}
},
Get a File
Retrieves details for a specific file, such as when it was created, the type of content it holds, its name and size, and the groups and entities associated with it.
GET /v1/files/:id
Example:
GET https://examplefirm.addepar.com/api/v1/files/123
HTTP/1.1 200
{
"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"
},
{
"type": "groups",
"id": "5678"
}
]
},
"associated_entities": {
"links": {
"self": "/v1/files/123/relationships/associated_entities",
"related": "/v1/files/123/associated_entities"
},
"data": [
{
"type": "entities",
"id": "10000"
},
{
"type": "entities",
"id": "10001"
}
]
}
},
"links": {
"self": "/v1/files/123"
}
}
}
Response Codes
200 OK
: Success400 Bad Request
: "include" query parameter not allowed403 Forbidden
: Lacking files read permission
Get All Files
Retrieves a list of all files you have permission to access, as well as details about when each was created, the type of content it holds, its name and size, and the groups and entities associated with it.
GET /v1/files
Example:
GET https://examplefirm.addepar.com/api/v1/files
HTTP/1.1 200
{
"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"
},
{
"type": "groups",
"id": "5678"
}
]
},
"associated_entities": {
"links": {
"self": "/v1/files/123/relationships/associated_entities",
"related": "/v1/files/123/associated_entities"
},
"data": [
{
"type": "entities",
"id": "10000"
},
{
"type": "entities",
"id": "10001"
}
]
}
},
"links": {
"self": "/v1/files/123"
}
},
{
"id": "345",
"type": "files",
"attributes": {
"content_type": "application/PDF",
"bytes": 798121,
"name": "Report.pdf",
"created_at": "2014-06-20T20:55:19Z"
},
"relationships": {
"associated_groups": {
"links": {
"self": "/v1/files/345/relationships/associated_groups",
"related": "/v1/files/345/associated_groups"
},
"data": []
},
"associated_entities": {
"links": {
"self": "/v1/files/345/relationships/associated_entities",
"related": "/v1/files/345/associated_entities"
},
"data": [
{
"type": "entities",
"id": "123400"
}
]
}
},
"links": {
"self": "/v1/files/345"
}
}
],
"links": {
"next": null
}
}
Response Codes
200 OK
: Success400 Bad Request
: "include" query parameter not allowed403 Forbidden
: Lacking files read permission
Download a File
Retrieves the raw contents of a specific file.
GET /v1/files/:id/download
Example:
GET https://examplefirm.addepar.com/api/v1/files/123/download
HTTP/1.1 200
Content-DispositionL attachment; filename="Sample.pdf"
Content-Type: application/binary
<RAW_FILE_DATA>
Response Codes
200 OK
: Success403 Forbidden
: Lacking files read permission404 Not Found
: Nonexistent/non-permissioned file ID
Get an Archived File
Retrieves an archived (deleted) file, as well as information about when it was created, the type of content it holds, its name and size, the groups and entities associated with it, and when it was deleted.
GET /v1/archive/files/:id
Example:
GET https://examplefirm.addepar.com/api/v1/archive/files/319
HTTP/1.1 200
{
"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":{
"links":{
"self":"/v1/archive/files/319/relationships/associated_groups",
"related":"/v1/archive/files/319/associated_groups"
},
"data":[
]
},
"associated_entities":{
"links":{
"self":"/v1/archive/files/319/relationships/associated_entities",
"related":"/v1/archive/files/319/associated_entities"
},
"data":[
{
"type":"entities",
"id":"22"
}
]
}
},
"links":{
"self":"/v1/archive/files/319"
}
}
}
Response Codes
200 OK
: Success400 Bad Request
: "include" query parameter not allowed403 Forbidden
: Lacking files read permission
Get All Archived Files
Retrieves a list of all archived (deleted) files, as well as information about when each was created, the type of content it holds, its name and size, the groups and entities associated with it, and when it was deleted.
GET /v1/archive/files
Example:
GET https://examplefirm.addepar.com/api/v1/archive/files
HTTP/1.1 200
{
"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":{
"links":{
"self":"/v1/archive/files/319/relationships/associated_groups",
"related":"/v1/archive/files/319/associated_groups"
},
"data":[
]
},
"associated_entities":{
"links":{
"self":"/v1/archive/files/319/relationships/associated_entities",
"related":"/v1/archive/files/319/associated_entities"
},
"data":[
{
"type":"entities",
"id":"22"
}
]
}
},
"links":{
"self":"/v1/archive/files/319"
}
}
],
"links":{
"next":null
}
}
Response Codes
200 OK
: Success400 Bad Request
: "include" query parameter not allowed403 Forbidden
: Lacking files read permission
Download an Archived File
Retrieves the raw contents of an archived file.
GET /v1/archive/files/:id/download
Example:
GET https://examplefirm.addepar.com/api/v1/archive/files/319/download
HTTP/1.1 200
Content-Disposition: attachment; filename="Sample.pdf"
Content-Type: application/binary
<RAW_FILE_DATA>
Response Codes
200 OK
: Success403 Forbidden
: Lacking files read permission404 Not Found
: Nonexistent/non-permissioned file ID
Get All Groups Associated with a File
Retrieves the full object of groups associated with the file.
GET /v1/files/:id/relationships/associated_groups
Example:
GET https://examplefirm.addepar.com/api/v1/files/123/relationships/associated_groups
HTTP/1.1 200
{
"links":{
"self":"/v1/files/123/relationships/associated_groups",
"related":"/v1/files/123/associated_groups"
},
"data":[
{
"type":"groups",
"id":"1234"
},
{
"type":"groups",
"id":"5678"
}
]
}
Response Codes
200 OK
: Success403 Forbidden
: Lacking file read permission or API permission404 Not Found
: Nonexistent/non-permissioned file ID
Get All Entities Associated with a File
Retrieves the full object of entities associated with the file.
GET /v1/files/:id/relationships/associated_entities
Example:
GET https://examplefirm.addepar.com/api/v1/files/123/relationships/associated_entities
HTTP/1.1 200
{
"links":{
"self":"/v1/files/123/relationships/associated_entities",
"related":"/v1/files/123/associated_entities"
},
"data":[
{
"type":"entities",
"id":"10000"
},
{
"type":"entities",
"id":"10001"
}
]
}
Response Codes
200 OK
: Success403 Forbidden
: Lacking file read permission or API permission404 Not Found
: Nonexistent/non-permissioned file ID
Create a File
Adds a new file to your firm. You can specify the name of the file and the groups and entities associated with the file.
The file extension provided in the metadata must match the file extension of filename in "Content-Disposition".
POST /v1/files/
Example:
POST https://examplefirm.addepar.com/api/v1/files
Content-Type: multipart/form-data; boundary=<UNIQUE_BOUNDARY>
Content-Length: 2198
--<UNIQUE_BOUNDARY>
Content-Disposition: form-data; name="file"; file name="Sample.txt"
Content-Type: text/plain
<RAW_FILE_DATA>
--<UNIQUE_BOUNDARY>
Content-Disposition: form-data; name="metadata"
{
"data":{
"type":"files",
"attributes":{
"name":"Sample.txt"
}
}
}
--<UNIQUE_BOUNDARY>--
HTTP/1.1 201 Created
{
"data": {
"id": 1111,
"type": "files",
"attributes": {
"content_type": "application/PDF",
"bytes": 256201,
"name": "Sample.txt",
"created_at": "2017-01-01T20:55:07Z"
},
"relationships": {
"associated_groups": {
"links": {
"self": "/v1/files/1111/relationships/associated_groups",
"related": "/v1/files/111113/associated_groups"
},
"data": []
},
"associated_entities": {
"links": {
"self": "/v1/files/1111/relationships/associated_entities",
"related": "/v1/files/1111/associated_entities"
},
"data": []
}
},
"links": {
"self": "/v1/files/1111"
}
}
}
Response Codes
201 OK
: Successfully created the file400 Bad Request
: Invalid payload such as non-permissioned entities and groups,
or file is missing403 Forbidden
: Lacking file write permission or API permission
Associate Groups with a File
Adds to the list of groups associated to the file.
POST /v1/files/:id/relationships/associated_groups
Example:
POST https://examplefirm.addepar.com/api/v1/files/123/relationships/associated_groups
{
"data":[
{
"type":"groups",
"id":"200"
},
{
"type":"groups",
"id":"201"
}
]
}
HTTP/1.1 204 No Content
Response Codes
204 No Content
: Success400 Bad Request
: Invalid payload such as non-permissioned entities and groups403 Forbidden
: Lacking file write permission or complete access to file and all entities/groups
related to file404 Not Found
: Nonexistent/non-permissioned file ID
Associate Entities with a File
Adds to the list of entities associated to the file.
POST /v1/files/:id/relationships/associated_entities
Example:
POST https://examplefirm.addepar.com/api/v1/files/123/relationships/associated_entities
{
"data":[
{
"type":"entities",
"id":"100"
},
{
"type":"entities",
"id":"101"
}
]
}
HTTP/1.1 204 No Content
Response Codes
204 No Content
: Success400 Bad Request
: Invalid payload such as non-permissioned entities and groups403 Forbidden
: Lacking file write permission or complete access to file and all entities/groups
related to file404 Not Found
: Nonexistent/non-permissioned file ID
Update a File
Updates the attributes and relationships for a specific file.
PATCH /v1/files/:id
Example:
PATCH https://examplefirm.addepar.com/api/v1/files/1111
{
"data":{
"id":1111,
"type":"files",
"attributes":{
"name":"RenamedFile.txt"
}
}
}
HTTP/1.1 200
{
"data": {
"id": 1111,
"type": "files",
"attributes": {
"content_type": "application/PDF",
"bytes": 256201,
"name": "RenamedFile.txt",
"created_at": "2017-01-01T20:55:07Z"
},
"relationships": {
"associated_groups": {
"links": {
"self": "/v1/files/1111/relationships/associated_groups",
"related": "/v1/files/111113/associated_groups"
},
"data": []
},
"associated_entities": {
"links": {
"self": "/v1/files/1111/relationships/associated_entities",
"related": "/v1/files/1111/associated_entities"
},
"data": []
}
},
"links": {
"self": "/v1/files/1111"
}
}
}
Response Codes
200 OK
: Successfully modified the file400 Bad Request
: Invalid payload such as non-permissioned entities and groups403 Forbidden
: Lacking file write permission or complete access to file and all entities/groups
related to file404 Not Found
: Nonexistent/non-permissioned file ID
Replace Groups Associated with a File
Replaces all groups currently associated with different groups.
PATCH /v1/files/:id/relationships/associated_groups
Example:
PATCH https://examplefirm.addepar.com/api/v1/files/123/relationships/associated_groups
{
"data":[
{
"type":"groups",
"id":"200"
},
{
"type":"groups",
"id":"201"
}
]
}
HTTP/1.1 204 No Content
ResponseCodes
204 No Content
: Success400 Bad Request
: Invalid payload such as non-permissioned entities and groups403 Forbidden
: Lacking file write permission or complete access to file and all entities/groups
related to file404 Not Found
: Nonexistent/non-permissioned file ID
Replace Entities Associated with a File
Replaces all entities currently associated with different entities.
PATCH /v1/files/:id/relationships/associated_entities
Example:
PATCH https://examplefirm.addepar.com/api/v1/files/123/relationships/associated_entities
{
"data":[
{
"type":"entities",
"id":"100"
},
{
"type":"entities",
"id":"101"
}
]
}
HTTP/1.1 204 No Content
Response Codes
204 No Content
: Success400 Bad Request
: Invalid payload such as non-permissioned entities and groups403 Forbidden
: Lacking file write permission or complete access to file and all entities/groups
related to file404 Not Found
: Nonexistent/non-permissioned file ID
Delete a File
Archives a file available in Addepar. The archived file and its associated metadata will remain available through separate routes.
DELETE /v1/files/:id
Example:
DELETE https://examplefirm.addepar.com/api/v1/files/1111
HTTP/1.1 204 No Content
Response Codes
204 No Content
: Success403 Forbidden
: Lacking file write permission or complete access to file and all entities/groups
related to file404 Not Found
: Nonexistent/non-permissioned file ID
Remove Groups Associated with a File
Removes the list of groups specified from the file associations.
DELETE /v1/files/:id/relationships/associated_groups
Example:
DELETE https://examplefirm.addepar.com/api/v1/files/123/relationships/associated_groups
{
"data":[
{
"type":"entities",
"id":"10000"
}
]
}
HTTP/1.1 204 No Content
Response Codes
204 No Content
: Success400 Bad Request
: Invalid payload such as non-permissioned entities and groups403 Forbidden
: Lacking file write permission or complete access to file and all entities/groups
related to file404 Not Found
: Nonexistent/non-permissioned file ID
Remove Entities Associated with a File
Removes the list of entities specified from the file associations.
DELETE /v1/files/:id/relationships/associated_entities
Example:
DELETE https://examplefirm.addepar.com/api/v1/files/123/relationships/associated_entities
{
"data":[
{
"type":"entities",
"id":"10000"
}
]
}
HTTP/1.1 204 No Content
Response Codes
204 No Content
: Success400 Bad Request
: Invalid payload such as non-permissioned entities and groups403 Forbidden
: Lacking file write permission or complete access to file and all entities/groups
related to file404 Not Found
: Nonexistent/non-permissioned file ID
Updated about a month ago