Files

See and manage files stored in Addepar. For example, you can upload files to a specific folder or move, delete, and download them. You can also link files to portfolios.


Base Route	/v1/files
Endpoints	GET /v1/files /v1/files/:id /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

Responses include a resource object described by the below attributes.

Attribute	Description	Example
`name`	The file or folder's name. String. Required for creation.	`"Sample File.txt"` `"Test Folder"`
`content_type`	The content type of the file or folder. String. Not editable.	`"application/PDF"` `"folder"`
`created_at`	Time stamp of the file or folder's creation. String. ISO 8601 date format.	`"2014-12-01T13:22:40Z"`
`modified_at`	Time stamp of the file or folder’s modification. String. ISO 8601 date format.	`“2014-12-01T13:22:40Z”`
`deleted_at`	Time stamp of the file or folder's deletion. String. ISO 8601 date format.	`"2014-12-01T13:22:40Z"`
`bytes`	The size of the file in bytes. Number. Not editable.	`100000`
`is_folder`	The designation of file or folder. String. Not editable.	`"true"`
`parent_folder_id`	The ID of the parent folder. Number. Not editable.	`12345`

Optional parameters

You can use these parameters to specify responses from GET /v1/files, GET /v1/files/:id, and GET /v1/archive/files.

Parameter	Description	Example	Validation
`filter[files][createdAfter]`	Returns files or folders created after a specific time.	`/v1/files/?filter[files][createdAfter]=2017-04-06T20:12:45Z`	Uses YYYY-MM-DD date format (ISO 8601)
`filter[files][createdBefore]`	Returns files or folders created before a specific time.	`/v1/files/?filter[files][createdBefore]=2017-04-06T20:12:45Z`	Uses YYYY-MM-DD date format (ISO 8601)
`filter[files][createdAfter] &filter[files][createdBefore]`	Returns files or folders created within a specific time range.	`/v1/files/?filter[files][createdAfter]=2017-04-05T20:12:45Z&filter[files][createdBefore]=2017-04-06T20:12:45Z`	Uses YYYY-MM-DD date format (ISO 8601) createdBefore must be earlier than createdAfter
`filter[files][entityId]`	Returns files or folders associated with an entity ID.	`/v1/files?[files][entityId]=100`
`filter[files][groupId]`	Returns files or folders associated with a group ID.	`/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 or folders associated with the entity.	`/v1/files?[files][entityId]=100&filter[files][groupId]=20`
`filter[files][includedObjects]`	Returns only files, only folders, or both. - `FOLDERS_ONLY` - `FILES_ONLY` - `FILES_AND_FOLDERS`If not specified, defaults to FILES_ONLY.	`=FOLDERS_ONLY`	Must be one of the three valid inputs. Any other input results in an error.
`filter[files][parentFolderId]`	Returns only the objects in the specified folder	`=12345`	You must have access to this active folder.

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 or folder

Retrieves details for a specific file or folder, 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: Success
400 Bad Request: "include" query parameter not allowed
403 Forbidden: Lacking files read permission

Get all files and/or folders

Retrieves a list of all files and/or folders 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 to get all files:

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
  }
}

Example to get all folders:

GET https://examplefirm.addepar.com/api/v1/files?filter[files][includedObjects]=FOLDERS_ONLY

HTTP/1.1 200

{
  "data": [
    {
      "id": "5",
      "type": "files",
      "attributes": {
        "name": "folder1",
        "created_at": "2014-08-12T21:15:56Z",
        "modified_at": "2014-08-12T21:15:56Z",
        "is_folder": true,
        "parent_folder_id": 0
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/5/relationships/associated_groups",
            "related": "/v1/files/5/associated_groups"
          },
          "data": []
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/5/relationships/associated_entities",
            "related": "/v1/files/5/associated_entities"
          },
          "data": [
            {
              "type": "entities",
              "id": "22"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/files/5"
      }
    },
    {
      "id": "7",
      "type": "files",
      "attributes": {
        "name": "folder2",
        "created_at": "2014-08-12T21:38:59Z",
        "modified_at": "2014-08-12T21:38:59Z",
        "is_folder": true,
        "parent_folder_id": 0
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/7/relationships/associated_groups",
            "related": "/v1/files/7/associated_groups"
          },
          "data": []
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/7/relationships/associated_entities",
            "related": "/v1/files/7/associated_entities"
          },
          "data": [
            {
              "type": "entities",
              "id": "22"
            },
            {
              "type": "entities",
              "id": "151"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/files/7"
      }
    },
    {
      "id": "11",
      "type": "files",
      "attributes": {
        "name": "folder3",
        "created_at": "2014-08-12T21:38:58Z",
        "modified_at": "2014-12-02T19:40:25Z",
        "is_folder": true,
        "parent_folder_id": 0
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/11/relationships/associated_groups",
            "related": "/v1/files/11/associated_groups"
          },
          "data": []
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/11/relationships/associated_entities",
            "related": "/v1/files/11/associated_entities"
          },
          "data": [
            {
              "type": "entities",
              "id": "22"
            },
            {
              "type": "entities",
              "id": "151"
            },
            {
              "type": "entities",
              "id": "183"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/files/11"
      }
    },
    {
      "id": "12",
      "type": "files",
      "attributes": {
        "name": "folder4",
        "created_at": "2014-08-12T21:15:57Z",
        "modified_at": "2014-08-12T21:15:57Z",
        "is_folder": true,
        "parent_folder_id": 0
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/12/relationships/associated_groups",
            "related": "/v1/files/12/associated_groups"
          },
          "data": []
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/12/relationships/associated_entities",
            "related": "/v1/files/12/associated_entities"
          },
          "data": [
            {
              "type": "entities",
              "id": "22"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/files/12"
      }
    },
    {
      "id": "13",
      "type": "files",
      "attributes": {
        "name": "folder5",
        "created_at": "2014-12-01T21:22:40Z",
        "modified_at": "2014-12-01T21:24:00Z",
        "is_folder": true,
        "parent_folder_id": 0
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/13/relationships/associated_groups",
            "related": "/v1/files/13/associated_groups"
          },
          "data": []
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/13/relationships/associated_entities",
            "related": "/v1/files/13/associated_entities"
          },
          "data": [
            {
              "type": "entities",
              "id": "183"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/files/13"
      }
    }
  ],
  "included": [],
  "links": {
    "next": null
  }
}

Response Codes

200 OK: Success
400 Bad Request: "include" query parameter not allowed or not valid
403 Forbidden: Lacking files read permission

Get files and/or folders from within a folder

Retrieve information for files or folders you have permission to access within a specific folder, including creation date, name, and associated groups and entities.

GET /v1/files

Example:

GET https://examplefirm.addepar.com/api/v1/files?filter[files][includedObjects]=FILES_AND_FOLDERS&filter[files][parentFolderId]=12345

HTTP/1.1 200

{
  "data": [
    {
      "id": "5",
      "type": "files",
      "attributes": {
        "content_type": "image/png",
        "bytes": 37909,
        "name": "bleed.png",
        "created_at": "2014-08-12T21:15:56Z",
        "modified_at": "2014-08-12T21:15:56Z",
        "is_folder": false,
        "parent_folder_id": 12345
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/5/relationships/associated_groups",
            "related": "/v1/files/5/associated_groups"
          },
          "data": []
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/5/relationships/associated_entities",
            "related": "/v1/files/5/associated_entities"
          },
          "data": [
            {
              "type": "entities",
              "id": "22"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/files/5"
      }
    },
    {
      "id": "7",
      "type": "files",
      "attributes": {
        "content_type": "image/png",
        "bytes": 6859,
        "name": "cutoff.png",
        "created_at": "2014-08-12T21:38:59Z",
        "modified_at": "2014-08-12T21:38:59Z",
        "is_folder": false,
        "parent_folder_id": 12345
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/7/relationships/associated_groups",
            "related": "/v1/files/7/associated_groups"
          },
          "data": []
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/7/relationships/associated_entities",
            "related": "/v1/files/7/associated_entities"
          },
          "data": [
            {
              "type": "entities",
              "id": "22"
            },
            {
              "type": "entities",
              "id": "151"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/files/7"
      }
    },
    {
      "id": "11",
      "type": "files",
      "attributes": {
        "content_type": "image/png",
        "bytes": 30834,
        "name": "is.png",
        "created_at": "2014-08-12T21:38:58Z",
        "modified_at": "2014-12-02T19:40:25Z",
        "is_folder": false,
        "parent_folder_id": 12345
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/11/relationships/associated_groups",
            "related": "/v1/files/11/associated_groups"
          },
          "data": []
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/11/relationships/associated_entities",
            "related": "/v1/files/11/associated_entities"
          },
          "data": [
            {
              "type": "entities",
              "id": "22"
            },
            {
              "type": "entities",
              "id": "151"
            },
            {
              "type": "entities",
              "id": "183"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/files/11"
      }
    },
    {
      "id": "12",
      "type": "files",
      "attributes": {
        "content_type": "image/png",
        "bytes": 9553,
        "name": "header.png",
        "created_at": "2014-08-12T21:15:57Z",
        "modified_at": "2014-08-12T21:15:57Z",
        "is_folder": false,
        "parent_folder_id": 12345
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/12/relationships/associated_groups",
            "related": "/v1/files/12/associated_groups"
          },
          "data": []
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/12/relationships/associated_entities",
            "related": "/v1/files/12/associated_entities"
          },
          "data": [
            {
              "type": "entities",
              "id": "22"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/files/12"
      }
    },
    {
      "id": "13",
      "type": "files",
      "attributes": {
        "name": "folder1",
        "created_at": "2014-12-01T21:22:40Z",
        "modified_at": "2014-12-01T21:24:00Z",
        "deleted_at": "2021-05-28T12:24:00Z",
        "is_folder": true,
        "parent_folder_id": 12345
      },
      "relationships": {
        "associated_groups": {
          "links": {
            "self": "/v1/files/13/relationships/associated_groups",
            "related": "/v1/files/13/associated_groups"
          },
          "data": []
        },
        "associated_entities": {
          "links": {
            "self": "/v1/files/13/relationships/associated_entities",
            "related": "/v1/files/13/associated_entities"
          },
          "data": [
            {
              "type": "entities",
              "id": "183"
            }
          ]
        }
      },
      "links": {
        "self": "/v1/files/13"
      }
    }
  ],
  "included": [],
  "links": {
    "next": null
  }
}

Response codes

200 OK: Success
400 Bad Request: "include" query parameter not allowed
403 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: Success
403 Forbidden: Lacking files read permission
404 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: Success
400 Bad Request: "include" query parameter not allowed
403 Forbidden: Lacking files read permission

Get all archived files and/or folders

Retrieves a list of all archived (deleted) files and/or folders, 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
  }
}

Example request to get all archived folders:

GET https://examplefirm.addepar.com/api/v1/archive/files?filter[files][includedObjects]=FOLDERS_ONLY

Response Codes

200 OK: Success
400 Bad Request: "include" query parameter not allowed
403 Forbidden: Lacking files read permission

Get archived files and/or folders within a folder

Retrieves archived (deleted) files and/or folders within a specified folder, as well as information about when it was created, the type of content it holds, its name, 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?filter[files][includedObjects]=FOLDERS_ONLY&filter[files][parentFolderId]=319

Response Codes

200 OK: Success
400 Bad Request: "include" query parameter not allowed
403 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: Success
403 Forbidden: Lacking files read permission
404 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: Success
403 Forbidden: Lacking file read permission or API permission
404 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: Success
403 Forbidden: Lacking file read permission or API permission
404 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

200 OK: Successfully created the file
400 Bad Request: Invalid payload such as non-permissioned entities and groups,
or file is missing
403 Forbidden: Lacking file write permission or API permission

Create a file in a folder

When uploading a file to a top-level folder that has nested folders, set "parent_folder_id = 0" and include the portfolio relationship node in the request.

When uploading a file to a nested folder, use a valid ID for the parent folder. You don't need to provide the portfolio relationship node because it's inherited from the parent folder. You can specify the file's name and the groups and entities associated with it.

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",
	“parent_folder_id”: 12345
    }
  }
}
--<UNIQUE_BOUNDARY>--

{
  "data": {
	"id": 1111,
    "type": "files",
    "attributes": {
      "content_type": "application/PDF",
      "bytes": 256201,
      "name": "Sample.txt",
      "created_at": "2017-01-01T20:55:07Z",
	“is_folder”: false,
	“parent_folder_id”: 12345
    },
    "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 created the file
400 Bad Request: Invalid payload such as non-permissioned entities and groups,
or file is missing
403 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: Success
400 Bad Request: Invalid payload such as non-permissioned entities and groups
403 Forbidden: Lacking file write permission or complete access to file and all entities/groups
related to file
404 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: Success
400 Bad Request: Invalid payload such as non-permissioned entities and groups
403 Forbidden: Lacking file write permission or complete access to file and all entities/groups
related to file
404 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 file
400 Bad Request: Invalid payload such as non-permissioned entities and groups
403 Forbidden: Lacking file write permission or complete access to file and all entities/groups
related to file
404 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: Success
400 Bad Request: Invalid payload such as non-permissioned entities and groups
403 Forbidden: Lacking file write permission or complete access to file and all entities/groups
related to file
404 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: Success
400 Bad Request: Invalid payload such as non-permissioned entities and groups
403 Forbidden: Lacking file write permission or complete access to file and all entities/groups
related to file
404 Not Found: Nonexistent/non-permissioned file ID

Move a file or folder to another folder

Move any file to a specific folder. You can also move a folder into another folder.

PATCH /v1/files/:id

Example:

PATCH https://examplefirm.addepar.com/api/v1/files/1111

{
  "data":{
    "id":1111,
    "type":"files",
    "attributes":{
      "parent_folder_id":54321
    }
  }
}

{
  "data": {
	"id": 1111,
    "type": "files",
    "attributes": {
      "content_type": "application/PDF",
      "bytes": 256201,
      "name": "Sample.txt",
      "created_at": "2017-01-01T20:55:07Z",
	“is_folder”: false,
	“parent_folder_id”: 54321
    },
    "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 created the file
400 Bad Request: Invalid payload such as non-permissioned entities and groups
403 Forbidden: Lacking file write permission or API permission

Delete a file or folder

Archives a file available in Addepar or a folder and everything in it. The archived file or folder and its associated metadata will remain available through separate routes. You can retrieve archived folders and their associated metadata via API.

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: Success
403 Forbidden: Lacking file write permission or complete access to file and all entities/groups
related to file
404 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: Success
400 Bad Request: Invalid payload such as non-permissioned entities and groups
403 Forbidden: Lacking file write permission or complete access to file and all entities/groups
related to file
404 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: Success
400 Bad Request: Invalid payload such as non-permissioned entities and groups
403 Forbidden: Lacking file write permission or complete access to file and all entities/groups
related to file
404 Not Found: Nonexistent/non-permissioned file ID