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

S

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

e

The file's name. String. Required for creation.

"

content_type

The content type of the file. String. Not editable.

"

created_at

Time stamp of the file's creation. String. ISO 8601 date format.

"

deleted_at

Time stamp of the file's deletion. String. ISO 8601 date format.

"

bytes

The size of the file in bytes. Number. Not editable.

0

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

]

Returns only files created after a specific time.

Z

filter[files][createdBefore]

Returns only files created before a specific time.

Z

filter[files][createdAfter] &filter[files][createdBefore]

Returns only filters created within a specific time range.

Z

filter[files][entityId]

Returns only files associated with the specific entity.

0

filter[files][groupId]

Returns only files associated with the specific group.

0

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.

0

Relationships

Relationship

Description

s

Groups associated with a file.

s

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

Updated 4 days ago


Files


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.