> This page is for Unified. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. The `File` object is used to represent a file in the workspace. The Object typically exists under a folder or drive, if it exists. ### The File Object ```json { "id": "string", "remote_id": "string", "created_at": "2023-01-01T00:00:00Z", "modified_at": "2023-01-01T00:00:00Z", "name": "string", "file_url": "string", "file_thumbnail_url": "string", "size": 99999, "mime_type": "string", "description": "string", "folder": "string", "checksum": { "string": {} }, "permissions": [ { "id": "string", "remote_id": "string", "created_at": "2023-01-01T00:00:00Z", "modified_at": "2023-01-01T00:00:00Z", "user": "string", "group": "string", "type": "USER", "roles": [ "READ" ], "remote_was_deleted": true, "field_mappings": { "organization_defined_targets": { "string": {} }, "linked_account_defined_targets": { "string": {} } } } ], "drive": "string", "remote_created_at": "2023-01-01T00:00:00Z", "remote_updated_at": "2023-01-01T00:00:00Z", "remote_was_deleted": true, "field_mappings": { "organization_defined_targets": { "string": {} }, "linked_account_defined_targets": { "string": {} } }, "remote_data": [ { "path": "string", "data": {} } ] } ``` ### Schema (`File`) ```yaml components: schemas: PermissionTypeEnum: type: string enum: - USER - GROUP - COMPANY - ANYONE title: PermissionTypeEnum RolesEnum: type: string enum: - READ - WRITE - OWNER title: RolesEnum PermissionFieldMappings: type: object properties: organization_defined_targets: type: object additionalProperties: description: Any type linked_account_defined_targets: type: object additionalProperties: description: Any type title: PermissionFieldMappings Permission: type: object properties: id: type: string format: uuid remote_id: type: - string - 'null' description: The third-party API ID of the matching object. created_at: type: string format: date-time description: The datetime that this object was created by Merge. modified_at: type: string format: date-time description: The datetime that this object was modified by Merge. user: type: - string - 'null' format: uuid description: >- The user that is granted this permission. This will only be populated if the type is `USER`. group: type: - string - 'null' format: uuid description: >- The group that is granted this permission. This will only be populated if the type is `GROUP`. type: oneOf: - $ref: '#/components/schemas/PermissionTypeEnum' - type: 'null' description: Denotes what type of people have access to the file. roles: type: - array - 'null' items: $ref: '#/components/schemas/RolesEnum' description: >- The permissions that the user or group has for the File or Folder. It is possible for a user or group to have multiple roles, such as viewing & uploading. Possible values include: `READ`, `WRITE`, `OWNER`. In cases where there is no clear mapping, the original value passed through will be returned. remote_was_deleted: type: boolean description: >- Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/). field_mappings: oneOf: - $ref: '#/components/schemas/PermissionFieldMappings' - type: 'null' description: >- # The Permission Object ### Description The Permission object is used to represent a user's or group's access to a File or Folder. Permissions are unexpanded by default. ### Usage Example Fetch from the `GET Files` or `GET Folders` endpoint. Permissions are unexpanded by default. Use the query param `expand=permissions` to see more details. title: Permission FileFieldMappings: type: object properties: organization_defined_targets: type: object additionalProperties: description: Any type linked_account_defined_targets: type: object additionalProperties: description: Any type title: FileFieldMappings RemoteData: type: object properties: path: type: string description: The third-party API path that is being called. data: description: >- The data returned from the third-party for this object in its original, unnormalized format. required: - path description: >- # The RemoteData Object ### Description The `RemoteData` object is used to represent the full data pulled from the third-party API for an object. ### Usage Example TODO title: RemoteData File: type: object properties: id: type: string format: uuid remote_id: type: - string - 'null' description: The third-party API ID of the matching object. created_at: type: string format: date-time description: The datetime that this object was created by Merge. modified_at: type: string format: date-time description: The datetime that this object was modified by Merge. name: type: - string - 'null' maxLength: 254 description: The file's name. file_url: type: - string - 'null' maxLength: 2000 description: The URL to access the file. file_thumbnail_url: type: - string - 'null' maxLength: 2000 description: >- The URL that produces a thumbnail preview of the file. Typically an image. size: type: - integer - 'null' format: int64 minimum: -9223372036854776000 maximum: 9223372036854776000 description: The file's size, in bytes. mime_type: type: - string - 'null' maxLength: 128 description: The file's mime type. description: type: - string - 'null' maxLength: 2000 description: The file's description. folder: type: - string - 'null' format: uuid description: The folder that the file belongs to. checksum: type: - object - 'null' additionalProperties: description: Any type description: >- This field stores file checksum data. 'type' indicates the algorithm (e.g. crc_32, sha1, sha256, quickXor, or md5), and 'content_hash' is the unique hash used to verify file integrity and detect alterations. permissions: type: array items: $ref: '#/components/schemas/Permission' drive: type: - string - 'null' format: uuid description: The drive that the file belongs to. remote_created_at: type: - string - 'null' format: date-time description: When the third party's file was created. remote_updated_at: type: - string - 'null' format: date-time description: When the third party's file was updated. remote_was_deleted: type: boolean description: >- Indicates whether or not this object has been deleted in the third party platform. Full coverage deletion detection is a premium add-on. Native deletion detection is offered for free with limited coverage. [Learn more](https://docs.merge.dev/integrations/hris/supported-features/). field_mappings: oneOf: - $ref: '#/components/schemas/FileFieldMappings' - type: 'null' remote_data: type: - array - 'null' items: $ref: '#/components/schemas/RemoteData' title: File ```