Intralinks Developer Portal

This guide provides a step-by-step outline for a common API use case - Uploading a document. The examples here are intended to show the parameters needed to make a successful API call and are presented in cURL since it is available on virtually every platform. Before beginning here you will need to create an app to get API keys. If you have not done this yet, please go through our getting started guide before continuing.

 

Logging in

The first thing you need to do is log in and get an access token. In this example we are going to use the client_credentials grant type since these will be your own credentials.
To log in you will need the following pieces of information:

Item Description
client_id You can find this in the "KEYS" section of the app in the "My Apps" area of the developers portal
client_secret You can find this in the "KEYS" section of the app in the "My Apps" area of the developers portal
email This username is what you use to log into Intralinks itself. NOTE: This is not the same as your username for logging into the developers portal.
password This password is what you use to log into Intralinks itself. NOTE: This is not the same as your username for logging into the developers portal.

API Reference: OAuth Token API

curl -X "POST" "https://test-api.intralinks.com/v2/oauth/token?grant_type=client_credentials" 
    -H "Content-Type: application/x-www-form-urlencoded" 
    --data-urlencode "email=<YOUR_EMAIL>" 
    --data-urlencode "password=<YOUR_PASSWORD>" 
    --data-urlencode "client_id=<YOUR_CLIENT_ID>" 
    --data-urlencode "client_secret=<CLIENT_SECRET>"

This API should return a response like this:

{
  "access_token": "7bSxew8sQbT9oODCAJAjR4sYqHYM",
  "token_type": "BearerToken",
  "expires_in": 3599,
  "email": "joe_user@intralinks.com"
}

You will need to keep track of the value for access_token as you will need it for the rest of your API calls.

 

List all my workspaces

Before you can upload a document you need to decide where you want to upload it to. So the next task after logging in is to probably list all workspaces that you have access to. To do this we will use the workspaces api. With this API you will pass in the access token you got in the response from Step #1 above.

API Reference: List All Workspaces

curl -X "GET" "https://test-api.intralinks.com/v2/workspaces"
    -H "Authorization: Bearer <YOUR ACCESS_TOKEN>"
    -H "Accept: application/json"

This API should return an array of workspaces and their properties. Look for the ID parameter and save that for the next step.

 "status": {
    "code": 200,
    "message": "Request completed fine, no errors"
  },
  "workspace": [
    {
      "workspaceName": "Demo API Workspace",
      "parentTemplateId": 554961,
      "description": "This is a demonstration workspace for users of the Intralinks API",
      "host": "Intralinks",
      "securityLevel": 1,
      "type": "ARC",
      "statistics": {
        "newTasks": 0,
        "newParticipantRequests": 0
      },
      "pvpEnabled": "F",
      "version": 5,
      "name": "Demo API Workspace",
      "id": 701421,
      "phase": "OPEN"
    }
  ]
}

 

Enter a workspace

Now that we have the ID of the workspace we want to work with, the next step is to enter the workspace. Some workspaces have additional security or restrictions configured by the owners to ask user to provide further proof they are who they say they are. For details about how entering workspaces works please review our Entering workspaces documentation

API Reference: Enter Workspace

curl -X "POST" "https://test-api.intralinks.com/v2/workspaces/<WORKSPACE_ID>/splash" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer <YOUR ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    -d "{\"acceptSplash\":true}"

If you pass all the requirements then you should receive a response back with a value of ALLOW in the state member like this:

{
  "status": {
    "code": 201,
    "message": "The entities have been created"
  },
  "state": "ALLOW"
}

 

Get folder contents

So far so good! Next step is to list the contents of the workspace. Documents cannot live in the root of a workspace, they must be placed in a folder. So, we will need to find a folder to put the content into. This is where the folders and folder contents APIs come in.

API Reference:
Get Workspace Folders
Get Folder Contents

curl -X "GET" "https://test-api.intralinks.com/v2/workspaces/<WORKSPACE_ID>/folders/" \
    -H "Authorization: Bearer <YOUR ACCESS_TOKEN>"

This API cal will return a list of folders in the current workspace. If a suitable folder returned in this call you can grab the ID and skip the next step. Otherwise, to find a sub folder, use the ID of the folder we want to dig into and call the /contents API like this:

curl -X "GET" "https://test-api.intralinks.com/v2/workspaces/<WORKSPACE_ID>/folders/<FOLDER_ID>/contents" \
    -H "Authorization: Bearer <YOUR ACCESS_TOKEN>"

This API returns a list of documents and folders within the specified folder. Identify a folder to upload the document to by looking for the value of FOLDER in the entityType member. When you find one you want, save the ID for the final step.

 

Create a placeholder document

OK, it's the moment of truth. Uploading a document first requires you to create a placeholder to store the file attachment in. If you are updating an existing document with a new attachment you can skip to the next step.

API Reference:
Create Document API
Update Document API

To create a place holder you use the /Documents API and supply a JSON body like this:

{
    "documents":[
        {
         "document": {
               "name":"name for document",
               "parentId":1234
            }
        }
    ]
}

This is an array of document objects with the following parameters specified at a minimim:

  • name: this is the name you want to give the document
  • parentId: this is the id of the parent folder where the document will be created (the ID parameter from the previous step)
curl -X "POST" "https://test-api.intralinks.com/v2/workspaces/<WORKSPACE_ID>/documents" \
    -H "Authorization: Bearer <YOUR ACCESS_TOKEN>" \
    -H "Content-Type: application/json" \
    -d $'{"documents":[{"document"{"name":"<NAME>","parentId":<FOLDER_ID>}}]}'

If successful, this call will return the ID of the new document and the version of that object. Make note of both of these values as you will need to supply them in the call used for uploading the actual file attachment.

Upload the file attachment

For this API you do not need to have the id for the document and the version of that document. The version is an important concept as it ensures that the object you are attempting to update has not been updated by someone else. With these two IDs you can use the /file API to upload the attachment.

API Reference:
Update document file API
Get document API

For this call, WORKSPACE_ID and DOCUMENT_ID are passed in the URL path itself, and VERSION is passed as a query parameter.
You also need to specify the file data in as multipart/form-data in a field called documentFile

curl -X "PUT" "https://test-api.intralinks.com/v2/workspaces/<WORKSPACE_ID>/documents/<DOCUMENT_ID>/file?version=<DOCUMENT_VERSION_NUM>" \
    -H "Authorization: Bearer <YOUR ACCESS_TOKEN>" \
    -H "Content-Type: multipart/form-data; boundary=__X_BOUNDARY_123456__" \
    -F "documentFile=<binary file data>"

The most common failure for this API is an HTTP error 400 with message Failed to lock the records optimistically. This simply means that the version number that you passed in the request was the the correct one (someone may have updated the document since you got the version number last). To fix this you need to pass the correct version. The latest version number is always returned in the version field of the document meta data returned with a GET on the document API.

curl -X "GET" "https://test-api.intralinks.com/v2/workspaces/<WORKSPACE_ID>/documents/<DOCUMENT_ID>" \
    -H "Authorization: Bearer <YOUR ACCESS_TOKEN>"