Introduction

The Hyperlink API is the simplest and easiest way to integrate with and automate tasks in GetBusy.

It allows you to launch the GetBusy 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…

Get started

Before you go any further, make sure you have created a GetBusy account at https://app.getbusy.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.getbusy.com?create=todo

You can give the task a title:

Create new task with a title

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

And finally, attach a public web document:

Create a task with a title and attachment

https://app.getbusy.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.getbusy.com?create=signature

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

URL protocol and platform targeting

The GetBusy Hyperlink API is designed to work with all of the GetBusy 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 GetBusy 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 GetBusy 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).

• getbusy:// - opens or brings the GetBusy 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 GetBusy via the Hyperlink API only works with the getbusy:// protocol via the desktop apps.

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

URL encoding

🚨 All of the URLs you create for the GetBusy 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 ;

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 GetBusy application in which the link will open.

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

Navigation

Required - Controls where in the GetBusy 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.getbusy.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 theirAction 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

• more coming soon…

Action

The thing that’s going to happen in GetBusy.

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

Parameters

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

https://app.getbusy.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.getbusy.com?open=connection
&type={type}
&email={emailaddress}
&firstname={firstname}&lastname={lastname}
&relationships={relationships}

Parameters

type

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

&type=individual  OR  &type=org

email

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

&email=richard@piedpiper.com

firstname

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

&firstname=Richard

lastname

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

&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.

&name=Pied+Piper

notes

Optional - Currently only applies to organizations.

&notes=My+notes

relationships

Optional - Specifies which relationship(s) the connection has - relationships must be pre-configured in GetBusy. Multiple relationships can be separated with a comma e.g. Client,Supplier

&relationships=client,supplier

relationship properties

Optional - Specifies relationship type properties for the connection. These must be pre-configured in GetBusy. Multiple properties can be separated with a comma. Use ;key:true to define which property is the primary lookup by which an existing record in GetBusy will be matched with an external source.

&properties=customer_code:12348,netsuite_id:1060;key:true

Create threads

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

getbusy://app.getbusy.com?create=todo
&title=My+title
&extra=My+extra+information
&participants=person1@domain1.com,person2@domain2.com;assignee:true
&file=Users%2Fme%2FDesktop%2FSample%20.pdf;name:Sample%20document.pdf;source:local

participants

Optional - Adds participants to the new thread

&participants=person1@domain1.com,person2@domain2.com

assignee

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

&participants=person1@domain1.com,person2@domain2.com;assignee:true

title

Optional - Populates the title field in the create thread screen.

&title=My+title

extra

Optional - Populates the extra information field in the create thread screen.

&extra=My+extra+information

file

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

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

WEB FILE EXAMPLE
https://app.getbusy.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
getbusy://app.getbusy.com/?create=todo
&file=Users%2Fme%2FDesktop%2FSample%20.pdf;name:Sample%20document.pdf;source:local

Required (with file) - Specifies whether GetBusy 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 GetBusy, including multiple files from difference sources.

getbusy://app.getbusy.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

getbusy://app.getbusy.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