> ## Documentation Index > Fetch the complete documentation index at: https://docs.cocoondata.com/llms.txt > Use this file to discover all available pages before exploring further. # /api/v1/objects/{objectId} ## URL structure ```text theme={null} https://access-service.xy-company.com/api/v1/objects/{objectId} ``` where `{objectId}` is the ID of a file object/Secure Object. ## Supported methods and overview * `GET` - used to retrieve information about a file object/[Secure Object](/3.2/api/creating-files-and-folders.md#secure-object) using its ID. * `PUT` - used to modify a file object's properties using the file object's ID. This involves the file's owner or a collaborator with sufficient permissions on the file 1 (represented through an access token), performing *any combination* of the following: 1. Modifying the collaborators (as well as their [permission sets](/3.2/api/access-service-api-v1-permissions-sets.md)) on the file object. 2. Modifying the classifications and time/date controls on the file object. \ **Note:** A collaborator with the **Share** *permission* on the file object (applied via the **Manage** *permission set*) can also perform these actions (i.e. both 1 and 2) above. 3. Renaming and/or moving the file object. \ **Note:** A collaborator with the **Rename** and **Move** permissions on the file object (applied via the **Modify** or **Manage** permission sets) can also perform these actions. 4. Completing an *Incomplete* file object (which changes its state to *Created*). Only the file object's owner can perform this action. * `DELETE` - used to change a file object's state on the Covata Platform's Access Service to *Deleted*. \ **Note**: A collaborator with the **Remove (File/Folder)** permissions on the file object (applied via the **Modify** or **Manage** permission sets) can also perform these actions. > [!NOTE] > > Both the `GET` and `DELETE` methods take no parameters. ## Detailed description This API endpoint serves a number of purposes: **GET method requests:** * Retrieves information about a file object using its ID. A file object's ID can be obtained using one of the following API endpoints: * [\/api/v1/items](/3.2/api/access-service-api-v1-items.md) - retrieves a list of information associated with file objects in an organization, which can be filtered using a variety of search criteria. * [\/api/v1/organisations/\{orgGroupId}/objects](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md) - retrieves a list of high-level information associated with all file objects that have been created within an organization (available to Organization administrators only), which can also be filtered using more restricted search criteria. * [\/api/v1/objects](/3.2/api/access-service-api-v1-objects.md) - retrieves information about a file object using the [SHA-512](http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf) value of its encrypted content. **PUT method requests:** * Allows a file object's owner or a collaborator with sufficient permissions on the file 1 to modify *any combination* of the file object's properties: * Collaborators and their [permission sets](/3.2/api/access-service-api-v1-permissions-sets.md) (specified through this endpoint's **collaborators** [parameter](/3.2/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters)) - where a *permission set* is specific to each individual collaborator. For each collaborator, one of the following four *permission sets* can be applied: * **View** - grants the collaborator the individual **View** [permission](/3.2/api/access-service-api-v1-permissions-sets.md) to allow the file's: * content to be viewed from a Safe Share application's [content viewer](/3.2/user/accessing-secure-content.md#viewing-and-printing-content), as well as the * *read-only view* to be downloaded (via the `GET` method on the [\/api/v1/objects/\{objectId}/view](/3.2/api/content-service-api-v1-objects-objectid-view.md) endpoint). * **Download** - grants the collaborator the individual **View** permission (provided by the **View** permission set), as well as the following additional permissions to: * **Download** the file's actual content (via the `GET` method on the [\/api/v1/objects/\{objectId}/contents](/3.2/api/content-service-api-v1-objects-objectid-contents.md) endpoint). * **Print** the file's content from a Safe Share application's content viewer. * **Modify** - grants the collaborator the individual permissions provided by the **Download** permission set, as well as the following additional permissions to perform any of the following actions on this file object and/or its content (in the owner's storage space): * **Rename** the file (via this endpoint's **name** [parameter](/3.2/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters)). * Delete the file and its content (via the `DELETE` method on the [\/api/v1/objects/\{objectId}/contents](/3.2/api/content-service-api-v1-objects-objectid-contents.md) endpoint followed by the `DELETE` method on the [\/api/v1/objects/\{objectId}](/3.2/api/access-service-api-v1-objects-objectid.md) endpoint), through the **Remove (File)** permission. * **Move** the file to a different folder within a common folder hierarchy (via this endpoint's **parentId** [parameter](/3.2/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters)). A *common folder hierarchy* is a folder hierarcy that contains this file, in which the same collaborator has also been added (with either the **Modify** or **Manage** permission set) to a higher level (i.e. a common) folder, such that this higher level folder forms the top of the folder's hierarchy. * **Manage** - grants the collaborator the individual permissions provided by the **Modify** permission set, as well as the following additional permissions to perform any of the following actions on this file object and/or its content (in the owner's storage space): * **Share** the file with other collaborators (via this endpoint's **collaborators** [parameter](/3.2/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters)), which also includes the ability to modify the **labelId**, **shareStartTime** and **shareEndTime** parameters (described next). * Classification (specified through this endpoint's **labelId** [parameter](/3.2/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters)) - defines which groups of [Covata users](/3.2/admin-org/administering-users-within-an-organisation.md) can be shared the file. * Time/date controls (specified through this endpoint's **shareStartTime** and **shareEndTime** parameters) - the time and date from which all collaborators on the file can begin accessing the file object and its data and/or when this access ceases. * Name (specified through this endpoint's **name** parameter) - the new name of the file. * Parent folder - i.e. [collection](/3.2/api/creating-files-and-folders.md#collection) (specified through this endpoint's **parentId** parameter) - the folder to which the file will be moved. * Allows a file object's owner 1 to complete an *Incomplete* file object, which changes its state to *Created*, by associating the SHA-512 value of the file's data encrypted (specified through this endpoint's **sha512** [parameter](/3.2/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters)). (Be aware that this data must have been encrypted externally - i.e. not via server-side encryption by the Content Service). For more information about initializing an *Incomplete* file object, see [\/api/v1/organisations/\{orgGroupId}/objects](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md). 1 This owner or collaborator is a [Covata user](/3.2/admin-org/administering-users-within-an-organisation.md), whose authenticated account is represented by the access token used in calling this API endpoint (see [Supported roles and conditions](/3.2/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-supported-roles-and-conditions) below for more information). A file object's: * Owner is a Covata user whose account's access token was used in [initializing or creating the file object](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md) (bearing in mind that a file object's ownership [can subsequently be changed](/3.2/api/access-service-api-v1-organisations-orgid-items-transfer.md) to that of another Covata user). * Collaborator is a Covata user whose account has already been added as a collaborator to this file object (with a given [permission set](/3.2/api/access-service-api-v1-permissions-sets.md)). **DELETE method requests:** * Changes a file object's state (on the Covata Platform's Access Service) to *Deleted* (`DELETE` method). \ **Notes:** * The encrypted data associated with this file object (deleted via this endpoint) is also automatically deleted from storage by the Content Service. However, this process only occurs every two hours (by default) or when a new access token (belonging to the owner of this file object and excluding access tokens obtained through a refresh token) is passed in the [header](/3.2/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-required-headers) of requests to this endpoint. Therefore, it is advised that you first explicitly [delete this data in storage](/3.2/api/content-service-api-v1-objects-objectid-contents.md) *before* calling the `DELETE` method of this API endpoint (to change the state of this file object to *Deleted*). If not, then the Covata user's actual quota may differ (potentially significantly) from the quota reported by the Covata Platform (until this data is automatically deleted by the Content Service). * Changing a file object's state to *Deleted* (by calling this endpoint) does not remove the file object's associated properties from the Covata Platform. * Be aware that a file object and its associated properties are deleted when the [Covata user (who owns this file object) is deleted themselves](/3.2/api/access-service-api-v1-users-userid.md). ## Supported roles and conditions This API endpoint supports requests utilizing Covata user accounts with the following [roles](/3.2/admin-org/administering-users-within-an-organisation.md#an-organisation-users-roles) (as described in the [Organization Administrator's Guide](/3.2/admin-org.md)) and conditions: * [Originator](/3.2/admin-org/administering-users-within-an-organisation.md#originator-role) - using the `GET`, `PUT` and `DELETE` methods, when this user owns the file object whose ID is specified by the `{objectId}` of the request's URL. * **Originator**, [Collaborator](/3.2/admin-org/administering-users-within-an-organisation.md#collaborator-role) and [Ad hoc](/3.2/admin-org/administering-users-within-an-organisation.md#adhoc-role) - using the: * `GET` method, when this user is a collaborator on the file object whose ID is specified by the `{objectId}` of the request's URL. * `PUT` method, when this user is a collaborator on the file object whose ID is specified by `{objectId}` in the URL. Such a collaborator user can set the: * **contentSize** and/or **sha512** parameters, when this user has the **Upload File** permission on this file object. * **mimeType** and/or **name** parameters, when this user has the **Rename** permission on this file object. * **parentId** parameter, when this user has the **Move** permission on this file object. * **collaborators**, **labelId**, **shareStartTime** and **shareEndTime** parameters, when this user has the **Share** permission on this file object. \ **Note:** With just the **Upload File** permission on this file object, this collaborator user can set the **labelId** parameter, if the classification (which this **labelId** represents) is one that this user has access to through their user group membership. See [Optional parameters](/3.2/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-optional-parameters) for more information about setting the **labelId** parameter and user group membership. To avoid complication, however, it is recommended setting both the **collaborators** and **labelId** parameters together in a single request (i.e. when the collaborator user also has the **Share** permission). * `DELETE` method, when this user is a collaborator on the file object whose ID is specified by `{objectId}` in the URL and has the **Remove (File)** permission on this file object. The Covata Platform's resources available to one of these Covata users (above) is determined by the access token passed in the [header](/3.2/api/access-service-api-v1-objects-objectid.md#access-service-api-v1-objects-objectid-required-headers) of requests to this endpoint. ## Required headers The appropriate access token as the `Bearer` token: * `Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...` The following header is required if the body of the request has a JSON object: * `Content-Type: application/json` ## Optional parameters The following optional parameters can be sent in the body of the PUT request, each as individual members of a JSON object: * **collaborators** ( *For collaborator users as opposed to owners, requires the **Share** [permission](/3.2/api/access-service-api-v1-permissions-sets.md) on `objectId`* ) - A parameter containing the following optional sub-element parameters, relating to the collaborators being applied to this file object: * **list** - An array of elements about each collaborator, where each element of this array contains the following optional sub-elements: * **email** - The email address of the person to add as a collaborator to the file object. (This sub-element is optional, although omitting it serves no purpose.) * **permissionSet** - The [permission set](/3.2/api/access-service-api-v1-permissions-sets.md) to apply to this collaborator. To apply a permission set to this collaborator, specify its ID as a sub-element parameter of this parameter: * **id** - The ID of the permission set. This ID can be obtained by calling the [\/api/v1/permissions/sets](/3.2/api/access-service-api-v1-permissions-sets.md) API endpoint. **Note:** If this sub-element is omitted, then the **View** permission set is automatically applied to this collaborator. **Additional note:** It is worthwhile your client application storing these set of collaborators and their respective permission sets (e.g. in its own object) because any modifications to one or more collaborators on a file object (through this parameter) requires all collaborators and their permission sets to be specified in the request to modify the file object (via this endpoint). * **contentSize** ( *For collaborator users, requires the **Upload File** permission on `objectId`* ) - The size (in bytes) of the file object's data (in its unencrypted form) to be recorded by the Covata Platform's Access Service. Specify this value to record the size of a completed file object's unencrypted data, which is to be encrypted locally by your client application. \ **Important:** * The **contentSize** value can only be set once on a file object, at which point this property becomes immutable. * If you intend to [upload](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST) the file object's *unencrypted* data to storage via the Covata Platform's Content Service, then *omit this parameter*. When you make the [upload](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST) request, the Content Service automatically calculates the size of the unencrypted data and assigns this value to **contentSize**. The Content Service then proceeds to encrypt the data and send this encrypted data to storage. * If you have already specified the **contentSize** parameter's value *before* uploading a file object's unencrypted data, then the Content Service will be unable to assign the unencrypted data's size to the **contentSize** property as it is immutable. The Access and Content Services will record errors in their respective logs. Nevertheless, the unencrypted data will still be encrypted by the Content Service, followed by the encrypted data being sent to storage and associated with the file object. * **labelId** ( *For collaborator users, requires the **Upload File** permission on `objectId`, although requiring the **Share** permission to set this parameter as a condition in your client application is recommended* ) - The ID of the classification to apply to (or modify on) the file object. If this parameter's value is an empty string (set as the file object's owner only) or the parameter is omitted altogether, then no classification is applied to the file object and therefore, no classification restrictions (i.e. checks on Covata users' group membership and the association of these groups with classifications - see [User group endpoints](/3.2/api/user-group-endpoints.md) for more information) are placed on any collaborators added to this file object. \ **Notes:** * Applying a classification has the potential to restrict access to the file object by any inherited collaborators. Inherited collaborators are collaborators who are able to access this file object because these collaborators were explicitly applied to an ancestral folder. * If Covata users' group memberships (associated with the classification applied to the file object in the request) do not comply with any **collaborators** applied to this file object (above), then this request will fail. * For more information about configuring classifications, see [Classification endpoints](/3.2/api/classification-endpoints.md). * **mimeType** ( *For collaborator users, requires the **Rename** permission on `objectId`* ) - The MIME type of the data associated with the file object. For example, if the data to be encrypted into this file object is an image in JPEG format, its MIME type value would be `image/jpeg`. * **name** ( *For collaborator users, requires the **Rename** permission on `objectId`* ) - The name to apply to the file object. For example, this might be the name of the original file (whose data is being encrypted into this file object) and its extension. * **parentId** ( *For collaborator users, requires the **Move** permission on `objectId`* ) - The ID of the [folder](/3.2/api/folder-handling-endpoints.md) that will contain the file object. Specifying a value of `0` (or omitting this parameter) results in the new file being located at the default logical root storage location. \ **Note:** Omitting this property (or not changing its existing value) results in the file object not being moved. * **sha512** ( *For collaborator users, requires the **Upload File** permission on `objectId` and* the same collaborator's user account that [initialized](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md) this file object ) - The [SHA-512](http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf) value of the file object's encrypted data. \ **Important:** * The **sha512** value can only be set once on a file object, at which point this property becomes immutable. * Omitting this parameter when updating an *Incomplete* file object, leaves this file object in an *Incomplete* state. * Specifying this parameter and its value on an *Incomplete* file object changes the file object's state to *Created*. * You can specify this parameter if you have encrypted the file object's data externally (e.g. locally by your client application) and intend to [upload](/3.2/api/content-service-api-v1-objects-objectid-contents.md) this *[encrypted data](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST)* to storage via the Covata Platform's Content Service. * If you have already specified this parameter's value when you [created a new completed file object](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md) (whose state is *Created*), then re-specifying this parameter (with any value) in this PUT request will cause this request to fail. * **shareStartTime** ( *For collaborator users, requires the **Share** permission on `objectId`* ) - The date and time from which collaborators can begin accessing the file object's content. Omitting this member makes the file object's content available immediately. \ **Note:** This parameter should only be specified in conjunction with the **collaborators** parameter. If the **shareStartTime** parameter is specified without the **collaborators** parameter, then the **shareStartTime** parameter's value will not be saved when the request is submitted. * **shareEndTime** ( *For collaborator users, requires the **Share** permission on `objectId`* ) - The date and time from which collaborators' access to the file object's content ceases. Omitting this member makes the file object's content available indefinitely (after its **shareStartTime**). \ **Note:** As for the **shareStartTime** parameter, the **shareEndTime** parameter should only be specified in conjunction with the **collaborators** parameter. Otherwise, the **shareEndTime** parameter's value will not be saved when the request is submitted. **Example (PUT request parameters - modifying a *Created* file object):** ```json theme={null} { "collaborators": { "list": [ { "email": "chris.collaborator@xy-company.com", "permissionSet": { "id": 3 } }, { "email": "adhoc.user@another-xy-company.com" } ] }, "labelId": "0", "mimeType": "application/pdf", "name": "Executive Report.pdf", "shareStartTime": "2016-10-03T05:30:00.000Z", "shareEndTime": "2016-10-10T05:30:00.000Z" } ``` **Notes:** * The permission set with an ID of **3** is **Modify**. See [\/api/v1/permissions/sets](/3.2/api/access-service-api-v1-permissions-sets.md) for more information about permission sets. * If this file object had existing collaborators and permission sets, then these would be overwritten by this example PUT request. ## Returns A JSON-formatted response containing the following members (from `GET` and `PUT` requests only): * **id** - The ID value of the file object. * **shareStartTime** - The date and time from which collaborators on this file object can begin accessing the file's content. * **shareEndTime** - The date and time from which collaborators' access to this file object's content ceases. * **shared** - A boolean value that indicates whether or not the file object has been shared with any collaborators. \ **Note:** If the request was made using the access token of an authenticated collaborator user (without the **View Other** [permission](/3.2/api/access-service-api-v1-permissions-sets.md)) on the file object, then the value returned will be `false`. * **name** - The name of the file object, which was set when the file object was [initialized or created](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md), or last updated (via a `POST` method request to this endpoint). This value is `null` if the **name** was never specified. * **sha512** - The unique [SHA-512](http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf) hash value of the encrypted data associated with the *Created*/complete file object. For initialized/*Incomplete* file objects, this value is `null`. * **owner** - A member containing information about the Covata user who is the current owner of the file object. This member contains the following sub-members: * **email** - This email address of the Covata user who owns this file object. * **firstName** - The first name set by this Covata user. This is the first name that appears on the [Users](/3.2/admin-org/administering-users-within-an-organisation.md) page of Safe Share Organization Administration and the [My Account](/3.2/user/managing-your-account.md) feature of the Covata Safe Share web application. * **lastName** - The last name set by this Covata user. Like the first name (above), this appears on the **User** page of Organization Administration and the **My Account** feature of the Safe Share web application. * **mfaEnabled** - A boolean value that indicates whether or not two-factor authentication has either been set by this Covata user on their own account, or enforced for all members of the organization (by an Organization administrator). * **id** - The ID of this Covata user's account. * **accountType** - A member containing the internationalization (I18N) property key/code 2 for the account type, including the account type's value (i.e. hard-coded in the Covata Platform), as sub-members: * **i18n** - A member containing the I18N code 2 for the account type as sub-members: * **code** - The I18N code for the account type's value. This I18N code could include the substring `local`, `ldap` or `external`. * **arguments** - An array containing any arguments/variables that constitute the value of the I18N code above. Since none of the account types' values contain any variables, this array is always empty. * **value** - The value of **accountType** as it is hard-coded in the Covata Platform. Your client application can exploit this value (instead of **i18n** above) if I18N is not required. 2 Your client application can exploit the Covata Platform's I18N features, by initially [downloading the relevant language bundles](/3.2/api/access-service-api-v1-i18n-bundles-localecode-download.md) (from the the Covata Platform), then using the **i18n code** (and if applicable, **arguments**) values above to extract the property values derived from these language bundles for use in your client application. For more information about the Covata Platform's I18N features, see [Managing internationalization](/3.2/admin-platform/managing-internationalization.md) in the Safe Share Administrator's Guide. \ **Note:** For more information about account types, see the description for [Account Type](/3.2/admin-org/administering-users-within-an-organisation.md#account-type) in the [Organization Administrator's Guide](/3.2/admin-org.md). * **hasView** - A boolean value that indicates whether or not the Covata Platform's Content Service has generated a read-only view of the file object's data in storage. \ **Notes:** * The Content Service automatically sets this value to `true` *after* it sets the value of **canGenerateView** (below) to `true` *and* the Content Service has successfully generated and stored a read-only view of the file object's data. * If your client application is managing its own file data (i.e. the data is not being uploaded to the Content Service), then your application can exploit this element's value for any purpose. * **canGenerateView** - A boolean value that indicates whether or not the Content Service is capable of generating a read-only view of the file object's data, which is based on the file name extension of the original file that was encrypted (as specified in **name**). For more information, see [File formats supported by the content viewer](/3.2/user/accessing-secure-content.md#file-formats-supported-by-the-content-viewer) in the Safe Share web application User's Guide. \ **Notes:** * Assuming the file name extension is one that supports a view being generated, the Content Service then automatically sets this value to `true` *after* the file object's data has been successfully [uploaded and stored](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST) *and* the size of this data is less than the maximum configured file size for generating a view (i.e. 20 MB by default). * If your client application is managing its own file object data (i.e. the data is not being uploaded to the Content Service), then your application can exploit this element's value for any purpose. * **extension** - The file name extension which appears after the final period/full-stop of the file object's **name**. * **organisation** - A member containing information about the organization in which this file object was created. This member contains the following sub-members: * **name** - The name of the organization. * **description** - The description of the organization, which can be set by Organization administrators. * **mfaEnabled** - A boolean value that indicates whether (`true`) or not (`false`) two-factor authentication has been enforced for all members of the organization. * **id** - The ID of the organization. * **permissions** - An array listing the individual [permissions](/3.2/api/access-service-api-v1-permissions-sets.md) that the **owner** above or **collaborator** below (whose access token was used in the request to this endpoint), has inherited from the location represented by **parentId**. * **mimeType** - The MIME type of the data associated with the file object, which was set when the file object was [initialized or created](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md), or last updated (via a `POST` method request to this endpoint). This value is `null` if the **mimeType** was never specified. * **contentSize** - The amount of space (in bytes) of the file object's data (as recorded by the Covata Platform's Access Service). For initialized/*Incomplete* file objects, this value should be `null`. * **parentId** - The ID of the [folder/collection](/3.2/api/folder-handling-endpoints.md) that contains the file object. A value of `0` indicates that this file object is located at the logical root location. * **originator** - A member containing information about the Covata user whose account was used to create this file object. This member contains the equivalent **email** and **id** sub-members only of either the **owner** member (above) or a **collaborators** array element (below). If these sub-members originally match those of the file's initial **owner** member and then the file's ownership changes to that of another Covata user, the **owner** member's **email** and **id** values will change while the equivalent sub-member values of this **originator** member will remain unchanged. * **state** - The I18N code for the current state of the file object. This I18N code could include the substring `incomplete` for an initialized file object, `created` for a completed file or `deleted` for a deleted file. * **modifiedAt** - The date and time when the file object was last modified. When a file object is [initialized or created](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md), this date and time should match (or be close to) that of the `createdAt` value below. Otherwise, if the file object has since been modified (via a `POST` method request to this endpoint), this date and time should reflect when the file object was last modified. * **createdAt** - The date and time when the file object was first initialized or created, either in its *Incomplete* or *Created* states. * **labelName** - The name of the classification applied to the file object. Like **labelId** below, if this element's value is `null`, then no classification was specified (i.e. the **labelId** parameter was specified with an empty string or this parameter was omitted) when the file object was [initialized or created](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md), or [last updated](/3.2/api/access-service-api-v1-objects-objectid.md). This means that no classification restrictions (i.e. checks on Covata users' group membership and the association of these groups with individual classifications - see [User group endpoints](/3.2/api/user-group-endpoints.md) for more information) have been placed on collaborators added to this file object. * **parentId** - The ID of the [folder/collection](/3.2/api/folder-handling-endpoints.md) that contains the file object. A value of `0` indicates that this file object is located at the logical root location. * **type** - Indicates `object`, which in turn indicates that information about item returned from this request is about a file object. * **labelId** - The ID of the classification applied to the file object. If this element's value is `null`, then no classification was specified (i.e. the **labelId** parameter was specified with an empty string or this parameter was omitted) when the file object was [initialized or created](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md), or last updated (via a `POST` method request to this endpoint). * **collaborators** - An array containing information about each Covata user who is currently a collaborator on this file object. Each element of this array contains information about one of these Covata users and is represented as an object, containing the following members: * **shareParentId** - Indicates either a value of `null` or `0`. A value of `null` indicates that the file object's location in its hierarchy of [folders](/3.2/api/folder-handling-endpoints.md) (e.g. as indicated in a Safe Share application's list of items) are equivalent between this collaborator (i.e. another Covata user account) and the current owner of this file object. A value of `0` indicates that the file object is being shared from the logical root file area/location of this collaborator's account. In Safe Share applications, this occurs when the owner of this file object has shared the file object with this collaborator, but the file object's parent folder has not also been shared with this collaborator. * **shareName** - Reserved for future use. Currently, this returns the value `null`. * **permissions** - An array listing the [permission set](/3.2/api/access-service-api-v1-permissions-sets.md) applied to this **collaborator** (or inherited by them from the location represented by **parentId**) on this file object, along with the individual permissions that constitue this permission set. * **email** - The collaborator's email address. * **firstName** - The collaborator's first name. This is the first name that appears on the [Users](/3.2/admin-org/administering-users-within-an-organisation.md) page of Safe Share Organization Administration and the [My Account](/3.2/user/managing-your-account.md) feature of the Covata Safe Share web application. * **lastName** - The collaborator's last name. Like the first name (above), this appears on the **User** page of Organization Administration and the **My Account** feature of the Safe Share web application. * **id** - The ID of the collaborator's Covata user account. **Note:** Only an empty array is returned from Covata user accounts who are collaborators on this file object *and* do not have the **View Other** [permission](/3.2/api/access-service-api-v1-permissions-sets.md) on it. \ **Example (GET response - from a request using the access token of an authenticated owner of the file object):** ```json theme={null} { "id": "734242448553197568", "shareStartTime": "2016-10-03T05:30:00.000Z", "shareEndTime": "2016-10-10T05:30:00.000Z", "shared": true, "name": "Executive Report.pdf", "sha512": "0X3iJ2keHhOBzrdJmUCw2QO0r7OOAwtaWDHGKU5cnkHVhdjeWtyvQAjjwAigT2dakgtM/BeZ/qvjuwAUtG9FdA==", "owner": { "email": "alex.originator@xy-company.com", "firstName": "Alex", "lastName": "Originator", "mfaEnabled": false, "id": "732856217122553856", "accountType": { "i18n": { "code": "server.useraccounttype.local", "arguments": [] }, "value": "LOCAL" } }, "hasView": false, "canGenerateView": true, "extension": "pdf", "organisation": { "name": "XY Company", "description": "", "mfaEnabled": false, "id": "732855142835470336" }, "permissions": [{ "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.file.delete", "id": "66" }, { "scopes": ["collection"], "nameI18nCode": "server.permission.name.folder.delete", "id": "67" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.download", "id": "62" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.move", "id": "69" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.view", "id": "60" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.delete.other", "id": "72" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.copy", "id": "63" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.print", "id": "61" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.share", "id": "73" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.rename", "id": "68" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.view.other", "id": "71" }, { "scopes": ["collection"], "nameI18nCode": "server.permission.name.folder.create", "id": "65" }, { "scopes": ["collection"], "nameI18nCode": "server.permission.name.file.upload", "id": "64" }], "mimeType": null, "contentSize": "3596924", "parentId": "0", "originator": { "email": "alex.originator@xy-company.com", "id": "732856217122553856" }, "state": "server.object.states.created", "modifiedAt": "2016-07-26T01:40:58.287Z", "createdAt": "2016-07-19T02:57:21.300Z", "labelName": null, "type": "object", "labelId": null, "collaborators": [{ "shareParentId": null, "shareName": null, "permissionSet": { "id": "2", "permissions": [{ "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.print", "id": "61" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.download", "id": "62" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.view", "id": "60" }], "scopes": ["object", "collection"], "nameI18nCode": "server.permissionset.name.download" }, "email": "adhoc.user@xy-company.com", "firstName": null, "lastName": null, "id": "736759315364757504" }, { "shareParentId": null, "shareName": null, "permissionSet": { "id": "3", "permissions": [{ "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.file.delete", "id": "66" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.print", "id": "61" }, { "scopes": ["collection"], "nameI18nCode": "server.permission.name.folder.delete", "id": "67" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.download", "id": "62" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.view", "id": "60" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.move", "id": "69" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.rename", "id": "68" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.view.other", "id": "71" }, { "scopes": ["collection"], "nameI18nCode": "server.permission.name.folder.create", "id": "65" }, { "scopes": ["collection"], "nameI18nCode": "server.permission.name.file.upload", "id": "64" }], "scopes": ["object", "collection"], "nameI18nCode": "server.permissionset.name.modify" }, "email": "chris.collaborator@xy-company.com", "firstName": "Chris", "lastName": "Collaborator", "id": "732856277868658688" }] } ``` **Example (GET response - from a request using the access token of an authenticated collaborator on the file object, where this collaborator does not have the 'View Other' permission on this file):** ```json theme={null} { "id": "734242448553197568", "shareStartTime": "2016-07-21T01:15:00.000Z", "shareEndTime": null, "shared": false, "name": "Executive Report.pdf", "sha512": "0X3iJ2keHhOBzrdJmUCw2QO0r7OOAwtaWDHGKU5cnkHVhdjeWtyvQAjjwAigT2dakgtM/BeZ/qvjuwAUtG9FdA==", "owner": { "email": "alex.originator@xy-company.com", "firstName": "Alex", "lastName": "Originator", "mfaEnabled": false, "id": "732856217122553856", "accountType": { "i18n": { "code": "server.useraccounttype.local", "arguments": [] }, "value": "LOCAL" } }, "hasView": false, "canGenerateView": true, "extension": "pdf", "organisation": { "name": "XY Company", "description": "", "mfaEnabled": false, "id": "732855142835470336" }, "permissions": [{ "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.print", "id": "61" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.download", "id": "62" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.view", "id": "60" }], "mimeType": null, "contentSize": "3596924", "parentId": "0", "originator": { "email": "alex.originator@xy-company.com", "id": "732856217122553856" }, "state": "server.object.states.created", "modifiedAt": "2016-07-26T01:27:10.291Z", "createdAt": "2016-07-19T02:57:21.300Z", "labelName": null, "type": "object", "labelId": null, "collaborators": [] } ``` **Example (PUT response - modifying a file object):** ```json theme={null} { "id": "736488108589498368", "shareStartTime": null, "shareEndTime": null, "shared": true, "name": "paraglider.jpg", "sha512": null, "owner": { "email": "alex.originator@xy-company.com", "firstName": "Alex", "lastName": "Originator", "mfaEnabled": false, "id": "732856217122553856", "accountType": { "i18n": { "code": "server.useraccounttype.local", "arguments": [] }, "value": "LOCAL" } }, "hasView": false, "canGenerateView": null, "extension": "jpg", "organisation": { "name": "XY Company", "description": "", "mfaEnabled": false, "id": "732855142835470336" }, "permissions": [{ "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.file.delete", "id": "66" }, { "scopes": ["collection"], "nameI18nCode": "server.permission.name.folder.delete", "id": "67" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.download", "id": "62" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.move", "id": "69" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.view", "id": "60" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.delete.other", "id": "72" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.copy", "id": "63" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.print", "id": "61" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.share", "id": "73" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.rename", "id": "68" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.view.other", "id": "71" }, { "scopes": ["collection"], "nameI18nCode": "server.permission.name.folder.create", "id": "65" }, { "scopes": ["collection"], "nameI18nCode": "server.permission.name.file.upload", "id": "64" }], "mimeType": "image/jpeg", "contentSize": null, "parentId": "736437666564194304", "originator": { "email": "chris.collaborator@xy-company.com", "id": "732856277868658688" }, "state": "server.object.states.incomplete", "modifiedAt": "2016-07-26T03:54:15.156Z", "createdAt": "2016-07-25T07:40:48.375Z", "labelName": null, "type": "object", "labelId": null, "collaborators": [{ "shareParentId": null, "shareName": null, "permissionSet": { "id": "2", "permissions": [{ "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.print", "id": "61" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.download", "id": "62" }, { "scopes": ["object", "collection"], "nameI18nCode": "server.permission.name.view", "id": "60" }], "scopes": ["object", "collection"], "nameI18nCode": "server.permissionset.name.download" }, "email": "chris.collaborator@xy-company.com", "firstName": "Chris", "lastName": "Collaborator", "id": "732856277868658688" }] } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.