Working with Contact Documents

NB: This is PRE-RELEASE documentation. You can find upcoming feature release dates on our Notifications page.

Introduction

In this tutorial we explore how to work with contact documents using the Actionstep API. Contact documents are essential for managing files associated with contacts, such as contracts, agreements, AML, KYC, and other important documents. The contactdocuments endpoint is very similar to the actiondocuments endpoint in terms of functionality.

In this tutorial we cover the following topics:

1. Uploading a document
2. Creating a new contact document
3. Viewing contact documents
4. Retrieving contact documents
5. Updating a contact document
6. Deleting a contact document

How Documents Work in Actionstep

Adding a document to either a matter or a contact is a two-step process. The first step is to upload the document to Actionstep where it is placed in quarantine and scanned for viruses and malware. When all integrity checks are complete Actionstep returns a unique file id for the uploaded file.

The second step is to create a new contact document record that links the uploaded file to a contact. Think of this second step as creating an entry in a document index. Once the contact document record is created, the file is copied to its final location in the Actionstep document management system.

Uploading a Document

To upload a document or file to Actionstep use the files endpoint. For this example we are using Postman to make the request, but you can use any HTTP client that supports file uploads. See Uploading and Downloading Documents for more information and code samples. If you are unfamiliar with Postman, see our Quick Start Guide to using Postman. Upon successful upload, the response will include a unique file id for the uploaded file.

Creating a New Contact Document

When you create a new contact document, you are creating a record that links the uploaded file to a specific contact. You can specify a target folder into which the document should be stored, plus any additional metadata you want to associate with the document, for example, a document summary.

Specifying a Target Folder

To locate a contact folder, you can use the contactfolders endpoint to retrieve a list of folders associated with a contact. The following example retrieves the folder for contact 41845 and a folder name of 'Contractual Agreements':

Creating the Contact Document

To create a new contact document, you make a POST request to the contactdocuments endpoint using the file id obtained from the upload step. To specify a target folder populate the folder parameter with the id of the folder.

Please note the following when creating contact documents:

1. By default, the document will be stored in the root folder for the contact if no folder is specified.

2. The format of the file parameter is important. You need to include both the unique file id and the file name (including the file extension) in the format {file_id};{file_name_with_extension} as shown in the example below.

3. If you do not provide a value for the name parameter, the file name will be used as the document name.

4. POST requests are NOT idempotent. This means if you make the same request multiple times, it will create multiple contact document records, each one linked to a separate copy of the same underlying file.

5. Actionstep does not prevent you from creating multiple files under the same name in the same folder.

6. Keywords and tags cannot be set with this version of the contactdocuments endpoint.

7. For a list of unsupported file types, see the Uploading and Downloading Documents page.

Viewing Contact Documents in Actionstep

To view the contact documents in Actionstep, navigate to the contact record and select the "Documents" tab.

Retrieving Contact Documents

Retrieving contact documents is similar to retrieving action documents. Use the contactdocuments endpoint to retrieve a list of documents for a specific contact. You can apply filters to return only the documents you are interested in, for example, by specifying a specific folder, or a (partial) name.

Updating a Contact Document

While many of the properties of a contact document are readonly (e.g. the file size), you can update the document name, summary, and change the folder. Changing the folder is useful if you want to move a document to a different folder within the contact's folder hierarchy.

Deleting a Contact Document

Deleting a contact document is achieved by making a DELETE request to the contactdocuments endpoint using the unique id of the contact document record.

Please Note: Documents are permanently (hard) deleted.