Introduction

The Hyperlink API is the simplest way to integrate with Workiro.

It allows you to launch the Workiro web, desktop and mobile apps from anywhere and trigger actions and navigation using parameters within a URL.

Whilst you can write scripts and code to use the Hyperlink API in powerful ways, you don’t have to - you don’t have to worry about connecting to services, managing authentication tokens, callbacks, overrides and a whole bunch of other complicated things that only developers know how to do…

In this guide:

Get started

Open and create connections

URL protocol and platform targeting

URL encoding

URL schema

Open and create connections

Create threads

Manifest (ideal for sending documents)

Get started

Before you go any further, make sure you have created a Workiro account at https://app.workiro.com.

Once you’ve created an account, you’ll be able to use the following link to trigger creation of a new task:

Create new task

The link we use to create a new task is pretty simple:

https://app.workiro.com?create=todo

You can give the task a title:

Create new task with a title

https://app.workiro.com?create=todo&title=Try+the+Hyperlink+API

And finally, attach a publicly accessible web document:

Create a task with a title and attachment

https://app.workiro.com?create=todo&title=Try+the+Hyperlink+API&file=file-examples.com/wp-content/uploads/2017/10/file-sample_150kB.pdf;name:Sample+web+document.pdf;source:web

https://app.workiro.com?create=signature

https://app.workiro.com?create=note 

URL protocol and platform targeting

The Workiro Hyperlink API is designed to work with all of the Workiro apps on web, desktop (Windows & Mac) and native mobile (iOS & Android).

Most users spend the majority of their time in the desktop and native mobile apps and rarely use the web application. The Hyperlink API can be specifically targeted to these platforms.

The Workiro Hyperlink API supports two URL protocols (the bit at the beginning of the URL).

• https:// - always opens a new browser tab in your default browser. If you’ve downloaded and installed a Workiro desktop or native mobile app on your device, the browser will ask if you want to open the link in the app (every time you click or tap an API link).

• workiro:// - opens or brings the Workiro desktop or native mobile apps into focus and executes the link within them, bypassing the browser for a much more streamlined experience.

In deciding which URL protocol to use, determine whether the audience is going to want a new browser tab to open for everything they do, or for the desktop or mobile apps to pop into focus.

It’s also worth noting that uploading local files to Workiro via the Hyperlink API only works with the workiro:// protocol via the desktop apps.

In the majority of cases, the best solution is to use workiro:// but feel free to give us a shout if you’re in any doubt.

URL encoding

🚨 All of the URLs you create for the Workiro Hyperlink API need to be encoded.

If you haven’t heard about URL Encoding, it’s the process of converting characters into an interpretable format on the web. There are certain characters that can’t be used in URLs, like spaces, which get encoded as %20.

So if you want the title of your task to be 'My to-do', you can’t use &title=My to-do, but instead use:

&title=My%20to-do

If you aren’t generating your URLs using code (in which case, encoding is straight forward) and you need some help to understand what your encoded link should look like, you’ll find https://www.urlencoder.org/ a useful resource.

Character stripping

Please note that you will have to strip out the following special characters from any values (for example from within the title of a to-do) as they are used to structure the API 

Colon :
Semicolon ;
Tilde ~
Asterisk *

The api does not currently support

en dash –
em dash —

URL schema

The URL schema for the Hyperlink API is made up of four parts:

Protocol - Navigation - Action - Parameters

{protocol}    {navigation}        {action}        {parameters}
https://      app.getbusy.com     ?create=todo    &title=My+new+todo

Protocol 

Required - Controls the Workiro application in which the link will open.

See the URL protocol and platform targeting section for further information.

Navigation

Required - Controls where in the Workiro application the action will be performed.

You must provide a navigation path when using the Hyperlink API with the https:// protocol. If you are using the getbusy:// protocol exclusively, then a navigation path isn’t really required but we’d recommend using it to avoid any future compatibility issues.

At a minimum, you must specify app.workiro.com

Generally, we don’t recommend navigating the user any further unless there is good reason - you could be changing the state of the users session unexpectedly. If no further navigation options are provided, the action will be executed for the user without switching their current view.

You can further navigate the user to key screens within the app before any action is performed. Supported navigation screens:

• /mytasks (known in the app as 'Assigned to me')

• /catchup

• /focus

Action

The thing that’s going to happen in Workiro.

https://app.workiro.com?{action}

Parameters

The properties of the things that’s going to happen in Workiro.

https://app.workiro.com?create=todo&{parameter1}&{parameter2}

The action ?open=connection opens an existing connection or populates the add connection screen with connection details if a connection does not already exist.

https://app.workiro.com?open=connection

Parameters

Type

Recommended - Specifies whether the connection being opened / created is a person (individual) {i} or an organization {o}. If the parameter doesn't exist the user will be prompted to select the connection type they would like to create.

&connection=type:i

&connection=type:o

Email

Required* - (where type=individual) - The email address of the connection to be opened or created.

&connection=type:i;email:richard@piedpiper.com

*The email address is optional when using relationship type properties to look up the record

Firstname

Optional - The first name of the connection, to be used to create the connection if it does not already exist.

&connection=type:i;email:richard@piedpiper.com;firstname:Richard

Lastname

Optional - The last name of the connection, to be used to create the connection if it does not already exist.

&connection=type:i;email:richard@piedpiper.com;firstname:Richard;lastname:Hendricks

Name

Optional - The name of an organization connection, to be used to create the connection if it does not already exist. Note: if type was not specified, and the user decides to create an individual, this value is added to the Firstname field.

&connection=type:o;name:Pied+Piper

Notes

Optional - Currently only applies to organizations.

&connection=type:o;name:Pied+Piper;notes:My+notes

Relationships

Optional - Specifies which relationship(s) the connection has - relationships must be pre-configured in Workiro. Multiple relationships can be separated with a semi colon e.g. customer;vendor

&connection=type:o;name:Pied+Piper;customer;vendor

Relationship properties

Optional - Specifies relationship type properties for the connection. These must be pre-configured in Workiro. Properties are added to the relationship with a tilde ~. Use an asterisk * to define which property is the primary lookup by which an existing record in Workiro will be matched with an external source.

;customer~customer_code:12348;*customer~netsuite_id:1060

Example

Open or create an organisation (Pied Piper) which is a customer (code 123468) and should be found by matching against its NetSuite customer record (id 1060)

https://app.workiro.com?open=connection&connection=type:o;name:Pied+Piper;notes:A+fictonal+startup;customer~customer_code:12348;*customer~netsuite_id:1060

Create threads

The action ?create={thread} triggers creation of a new thread in Workiro. The create action accepts thread types todo, note or signature.

workiro://app.workiro.com?create=todo
&title=My+title
&extra=My+extra+information
&participants=type:i;email:one@participants.com;assignee:true,type:i;email:two@participants.com
&relcon=type:i;email:one@related.com;customer~customer_code:1234;*customer~netsuite_id:1060;vendor
&file=Users%2Fme%2FDesktop%2FSample%20.pdf;name:Sample%20document.pdf;source:local

&title=My+title

&extra=My+extra+information

Optional - Adds participants to the new thread

&participants=type:i;email:one@participants.com,type:i;email:two@participants.com

Name

You can optionally add their name.

&participants=type:i;email:one@participants.com;firstname:bob;lastname:smith,type:i;email:two@participants.com

The current user will always be added as a participant on new threads and therefore does not need to be specified. 

Assignee

Optional - Applicable to tasks only. Sets a specific participant as the assignee.

&participants=type:i;email:one@participants.com;assignee:true,type:i;email:two@participants.com

Relationships

Optional - Specifies which relationship(s) the participant has - relationships must be pre-configured in Workiro. Multiple relationships can be separated with a semi colon e.g. customer;vendor

&participants=type:i;email:one@participants.com;assignee:true;customer;vendor

Relationship properties

Optional - Specifies relationship type properties for the participant. These must be pre-configured in Workiro. Properties are added to the relationship with a tilde ~. Use an asterisk * to define which property is the primary lookup by which an existing record in Workiro will be matched with an external source.

&participants=type:i;email:one@participants.com;assignee:true;*customer~netsuite_id:1060

Related connections

🚨 Where related connections do not already exist as connections (for the current user) they will be created automatically.

Optional - An array of related connections may be passed, of mixed type (individual or organisation)

&relcon=type:i;email:one@related.com;firstname:bob;lastname:smith,type:o;name:organization1

Related connections may have relationships pre-configured in Workiro

&relcon=type:i;email:one@related.com;customer;vendor

They may also have relationship properties

&relcon=type:i;email:one@related.com;customer~customer_code:1234;*customer~netsuite_id:1060;vendor

File

Optional - Path to a publicly accessible file stored on the web, or a private file on the users device to be uploaded to Workiro and added as an attachment in the create thread screen.

If you do want to send files we would recommend using the Manifest API approach, detailed below.

&file={filepath};source:{local|web};name:{filename} 

WEB FILE EXAMPLE
https://app.workiro.com/?create=todo
&file=file-examples.com/wp-content/uploads/2017/10/file-sample_150kB.pdf;name:Sample+web+document.pdf;source:web 

LOCAL FILE EXAMPLE
workiro://app.workiro.com/?create=todo
&file=Users%2Fme%2FDesktop%2FSample%20.pdf;name:Sample%20document.pdf;source:local

Required (with file) - Specifies whether Workiro should look for the file on the web or on the users Windows or Mac device.

Values:

• web

• local

&file={filepath};source:web

Optional (with file) - The name given to the attachment in the create to-do screen. If name is not specified, the attachment will be named using the filename from the filepath.

&file={filepath};source:web;name:Sample+web+document.pdf

It is possible to pass multiple instances of the file parameter to upload multiple files to Workiro, including multiple files from difference sources.

https://app.workiro.com/?create=todo&file=Users%2Fme%2FDesktop%2FSample%201.pdf;name:Sample+document+1.pdf;source:local&file=Users%2Fme%2FDesktop%2FSample%202.pdf;name:Sample+document+2.pdf;source:local

When passing multiple files to the Hyperlink API, it is possible to omit the source:{local|web} command from each file and instead pass the global parameter filesource if the source of all the files is the same

workiro://app.workiro.com/?create=todo&file=Users%2Fme%2FDesktop%2FSample%201.pdf;name:Sample+document+1.pdf&file=Users%2Fme%2FDesktop%2FSample%202.pdf;name:Sample+document+2.pdf&filesource:local

Manifest (ideal for sending documents)

If you want to send documents with Workiro, but don’t want to deal with the hassle of authentication and complex API endpoints, then the manifest API is made for you. It has all the functionality of the Hyperlink API with added benefits for integrators that deal with documents.

The manifest API is a publicly accessible unauthenticated API endpoint that you can post your request to, including files. You will receive a manifest ID in return. You can then use this manifest ID in a URL which takes the user to a Workiro screen as you’ve defined in your original request; for example: create a new thread, sign a document, open a connection. This is a secure way to transfer documents.

Security

Once a Workiro user has used the manifest ID that user owns that data and no-one else can claim it. The manifest IDs are one-use only. The Manifest ID is complex and cannot be guessed.

All data is encrypted in transit and in storage on our servers, and it is disposed off when it’s no longer required.

When you launch the URL the user will be asked to log in to Workiro if they’ve not done so previously in that browser session. Workiro will handle all of the authentication for you.

Getting started

1) Create a string of text in JSON format with the information about the thing you want the user to do, e.g. the thread you want the user to create. Here is a simple example:

{
    "create": 'todo',
    "title": 'The title of the thread',
    "extra": 'The first comment of the thread'
}

2) POST the JSON above to this Workiro API endpoint:

1. • https://api.getbusy.com/api/v1/hyperlink/manifest

   • The endpoint will return an ID. Here’s an example of the response:

{
    "result": "79100d10-e5c4-4f02-bbe3-9bd6b32b6148"
}

3) Generate a URL which uses the manifest ID returned above:

1. • https://app.workiro.com/myTasks?manifest={id}

4) Launch the URL in a new tab and the user will see what you sent over in your original request, for example a new thread window with all the information you sent over pre-populated. They can then make adjustments to the thread and add additional information before sending it. If the user needs to they will be prompted to log in to Workiro

Create a thread

"create": "todo",

"title": "Review tax returns",

"extra": "Hi Bob, please see attached docs.",

"participants": [
    {
     "type": "i",
     "firstname": "Bob",
     "lastname": "Smith",
     "email": "bob.smith9381@gmail.com"
   },
   {
     "type": "i",
     "firstname": "Jane",
     "lastname": "Smith",
     "email": "jane.smith4102@gmail.com"
   }
 ]

"files":[
    {
     "source": "attached", 
     "location": "file1", 
     "name": "Example contract.pdf"
   },
   {
     "source": "attached", 
     "location": "file2", 
     "name": "Supporting documents.docx"
  }
]

"relcon": [
   {
    "type": "o",
    "name": "ABC Ltd",
    "*Customer~netsuite_ID": "0000001"
   },
   {
    "type": "i",
    "firstname": "Bob",
    "lastname": "Smith",
    "email": "email:one@related.com",
    "*Customer~netsuite_ID": "0124345"
   }
  ]

 "relproj:" [
    { 
     "name": "Office Move", 
     "description": "More detailed desc", 
     "properties": [{ 
         "name": "Netsuite_ID",
         "value": "OM001", 
         "is_key": "true" 
     }
   ]
  }
]

Open/Create Connection

You may want to navigate the user to a connection in Workiro so that they can see all the work going on with that connection. You can even embed this experience in an iFrame within your application (only supported in Chrome at this point).

Workiro will try to find the connection based on the details you supply. If a connection can’t be found it will prompt the user to create a new connection with the details that you’ve provided. Order of how Workiro looks for connections..

• IF match on relationship type property value THEN open connection

• ELSE IF match on organization name THEN open connection

• ELSE IF match on individual email THEN open connection

• ELSE prompt the user to create the connection

"open": "connection",

"type": "individual"

"firstname": "Bob",

"lastname": "Smith",

"email": "bob.smith9381@gmail.com",

"name": "ABC Financials Ltd",

"notes": "6 person firm",

"relationships": [
    "client",
    "supplier"
]

"properties": [
    {
      "name": "supplier_code",
      "value": "ABC001"
    },
    {
     "name": "clientid",
     "value": "1060",
     "key": "true"
    }
  ]

New Document

You can upload a document to Workiro and classify it against connections or projects.

"create": "document",

"files":[
{
    "source": "attached",
    "location": "file1", 
    "name": "Example contract.pdf"
  }
]

"relcon": [
   {
    "type": "o",
    "name": "ABC Ltd",
    "*Customer~netsuite_ID": "0000001"
   },
   {
    "type": "i",
    "firstname": "Bob",
    "lastname": "Smith",
    "email": "email:one@related.com",
    "*Customer~netsuite_ID": "0124345"
   }
  ]

"relproj:" [
    { 
     "name": "Office Move", 
     "description": "More detailed desc", 
     "properties": [{ 
         "name": "Netsuite_ID",
         "value": "OM001", 
         "is_key": "true" 
     }
   ]
  }
]