Files

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: Success
400 Bad Request: "include" query parameter not allowed
403 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: 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

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

201 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

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