Legacy — frozen. This is the original Zapier-shaped v1 API, served at app.sortd.com/api/v1. It receives security and bug fixes only. New integrations should use the v2 reference.

Sortd API (Zapier) version 1.x

Authentication

The Sortd API (Zapier) uses a session based token which can be generated by first creating an API Key and API Secret from within the Sortd Chrome Extension. This can be done by installing the Sortd Chrome Extension for Gmail, and once logged in, going to the settings panel and selecting the API tab. From there, enter a name for the API, such as ‘Zapier’ and click “generate”. Two alphanumeric strings will be returned for the API Key and API Secret respectively which can then be used in Zapier, along with the name above to authenticate with Sortd through Zapier.

API Token Generation

A session token can be generated using the api_token API method, which requires the following query string parameters:

Name	Value	Comment or Example
email	Email Address which must match the email address used when logging into Sortd to generate the API keys	api@sortd.com
api_key	Alphanumeric string generated from Sortd API Settings panel	c22a4398d6535d209cb1
api_secret	Alphanumeric string generated from Sortd API Settings panel	b6c7b9555ddafd528b9ee32 bc68d35f8173b7501fda90ef 34d797d6c94dd793b5f4c8af b8be82a0c
api_key_name	Name provided in Sortd API Settings panel	Zapier

The response will be a JWT based session token which will be valid for about 20 minutes, thereafter a new call to api_token will need to be undertaken to get an updated session token.

URL	https://app.sortd.com/auth/api_token
METHOD	POST
QUERY PARAMETERS	email, api_key, api_secret, api_key_name
RESPONSE	Content-Type application/json; charset=utf-8 Body { "x-access-token": "eyJhbGciOiJIUzI1N…." }
EXAMPLE	Request: curl --location --request POST 'https://app.sortd.com/auth/api_token' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "api@sortd.com", "api_key": "c22a4398d6535d209cb2", "api_secret":"b6c7b9555ddafd528b9ee32bc68d35f8173b7501fda90ef34d79 7d6c94dd793b5f4c8afb8be82a0b", "api_key_name": "Zapier'" }' Response: { "x-access-token": "eyJhbGciOiJIUzI1N…." }

All of the Sortd API methods will require this session token to be sent as the value for the HTTP header ‘x-access-token’.

Retrieving data - API List Methods

The Sortd API allows one to obtain information about the Teams, Boards, Lists and Items (Tasks) that the user has access to. Each of these object types provides some information via a REST based API.

All of the Sortd API methods will return a JSON response, many with identifiers (id) that will be required in other API calls. These Id values will be returned as a GUID.

Teams

The teams API will allow the end user to get a list of teams that the user is a member of, within Sortd.

URL	https://app.sortd.com/api/v1/teams
METHOD	GET
QUERY PARAMETERS	None
RESPONSE	Content-Type application/json; charset=utf-8 Body [ { "id": "544808a34aca9916a8914fd1", "name": "Team 1" } ]
EXAMPLE	Request: curl --location --request GET 'https://app.sortd.com/api/v1/teams \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ Response: [ { "id": "544808a34aca9916a8914fd1", "name": "Team 1" }, { "id": "59312e962802aabfeb200a41", "name": "Team 2" } ]

Boards

In Sortd each team can have many boards. The boards API will allow the end user to get a list of boards that the user is a member of for a specified team.

URL	https://app.sortd.com/api/v1/boards
METHOD	GET
QUERY PARAMETERS	teamId
RESPONSE	Content-Type application/json; charset=utf-8 Body [ { "id": "544808a34aca9916a8914fd2", "name": "Board 1" } ]
EXAMPLE	Request: curl --location --request GET 'https://app.sortd.com/api/v1/boards?teamId=544808a34aca9916a8914fd1 \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ Response: [ { "id": "544808a34aca9916a8914fd2", "name": "Board 1" }, { "id": "59312e962802aabfeb200a42", "name": "Board 2" } ]

Lists

In Sortd each board can have many lists. The lists API will allow the end user to get the collection of lists for a specified board.

URL	https://app.sortd.com/api/v1/lists
METHOD	GET
QUERY PARAMETERS	boardId
RESPONSE	Content-Type application/json; charset=utf-8 Body [ { "id": "544808a34aca9916a8914fd3", "name": "List 1" } ]
EXAMPLE	Request: curl --location --request GET 'https://app.sortd.com/api/v1/lists?boardId=544808a34aca9916a8914fd2 \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ Response: [ { "id": "544808a34aca9916a8914fd3", "name": "List 1" }, { "id": "59312e962802aabfeb200a44", "name": "List 2" } ]

Items/Tasks

In Sortd each list can have many items or tasks. The items API will allow the end user to get the collection of items for a specified list or board. This API call can either provide a list of all the items on a board or just the items on a specified list. To obtain the items on a list, the listId needs to be provided, whereas for all the items on a board, the boardId needs to be provided in the query string parameters.

URL	https://app.sortd.com/api/v1/items
METHOD	GET
QUERY PARAMETERS	One of: boardId listId
RESPONSE	Content-Type application/json; charset=utf-8 Body [ { "id": "5a86d680da96e432032bff97", "title": "Russell, do you want to join our beta?", "dateCreated": "2020-10-14T10:44:02.307Z", "dueDate": null, "notes": null, "firstThread": { "title": "Re: Russell, do you want to join our beta?", "received": "2020-10-14T11:02:21.000Z", "from": "russell@some.email.address.com" } "completed": false } ]
EXAMPLE	Request: curl --location --request GET 'https://app.sortd.com/api/v1/items?listId=544808a34aca9916a8914fd3 \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ Response: [ { "id": "5a86d680da96e432032bff97", "title": "Russell, do you want to join our beta?", "boardName": "Projects Board", "boardId": "60d9f1a18748d22062bc41b6", "listName": "Ideas", "listId": "60d9f1a27f6c0f020773e253", "dateCreated": "2020-10-14T10:44:02.307Z", "dueDate": null, "notes": null, "firstThread": { "title": "Re: Russell, do you want to join our beta?", "received": "2020-10-14T11:02:21.000Z", "from": "russell@some.email.address.com" } "completed": false, "assignedTo": "", "assignedToEmail": "" }, { "id": "5a6db4fdb11f0baceb29cd28", "title": "Ability to assign", "boardName": "Projects Board", "boardId": "60d9f1a18748d22062bc41b6", "listName": "Ideas", "listId": "60d9f1a27f6c0f020773e253", "dateCreated": "2020-09-25T09:14:37.687Z", "dueDate": "2020-10-25T09:14:37.687Z", "notes": "I am some notes", "firstThread": null, "completed": false, "assignedTo": "Joe Bloggs", "assignedToEmail": "jbloggs@test.com" } ]

Changing Data - Actions

Creating Tasks

The Sortd API allows users to create new tasks/items in Sortd. Using a POST to the items endpoint a new task can be created on a List in a Sortd board, either simply with a title or linked to an existing email thread in Gmail.

Required Body Parameters:

Name	Value	Comment
listId	The Id of List to create the tasks on	Always required
title	Name of the task	Simple Task ONLY
notes	Text to be added as notes or a description for the task	Simple Task ONLY optional
dueDate	The dueDate of the task. This must be in extended ISO8601 UTC format	Simple Task ONLY optional
providerId	Always ‘gmail’	Email Task ONLY
messageId	This maps to the Gmail message_id property which will have a value similar to 175c08677bc89318. In the drop downs this will appear something like "1. Message ID 175c08677bc89318" or "1. Message Message ID 175c08677bc89318".	Email Task ONLY
threadId	This maps to the Gmail thread_id property which will have a value similar to 175be310c94c6576. In the Zapier drop downs this will appear something like "1. Thread ID 175be310c94c6576" or "1. Message Thread ID 175be310c94c6576"	Email Task ONLY
archive	Boolean	Email Task ONLY. Setting this to "true" will archive the email thread in Gmail
~~listItem.title~~	~~Name of the task~~	~~Email Task ONLY~~
listItem.contentType	“task” or “sale”	Email Task ONLY. A "task" is a normal task or item on a Sortd board. If you are adding the task to a Sales board, choose the "sale" type.

TYPE	Simple Task
URL	https://app.sortd.com/api/v1/items
METHOD	POST
BODY	Simple Task { "listId": "5f0892bf3ee7a675609a224f", "title": "Test API Create", "notes": "Some Notes", "dueDate": "2020-10-25T09:14:37.687Z", }
RESPONSE	Content-Type application/json; charset=utf-8 Body { "id": "5a86a580da56e432032bff96" }
EXAMPLE	Simple Task Request: curl --location --request POST 'https://app.sortd.com/api/v1/items' \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ --header 'Content-Type: application/json' \ --data-raw '{ "listId": "5f0892bf3ee7a675609a224f", "title": "Test API Create", "notes": "Some Notes", "dueDate": "2020-10-25T09:14:37.687Z" }' Response: { "id": "5a86a580da56e432032bff96" }

TYPE	Task From Email
URL	https://app.sortd.com/api/v1/items/createFromEmail
METHOD	POST
BODY	{ "providerId": "gmail", "listId": "544808a34aca9916a8914fd3", "messageId": "174fa32c0be301ba", "threadId": "174fe32b0be301ba", "archive": false, "listItem": { "contentType": "task" } }
RESPONSE	Content-Type application/json; charset=utf-8 Body { "id": "5a86a580da56e432032bff96" }
EXAMPLE	Request: curl --location --request POST 'https://app.sortd.com/api/v1/items/createFromEmail' \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ --header 'Content-Type: application/json' \ --data-raw '{ "providerId": "gmail", "listId": "544808a34aca9916a8914fd3", "messageId": "174fe32c0be301ba", "threadId": "174fe32c0be301ba", "archive": false, "dueDate": "2020-10-25T09:14:37.687Z", "listItem": { "title": "Zapier Task from Email Creation Test (MANUAL)", "contentType": "task" } }' Response: { "id": "5a86a580da56e432032bff86" }

Completing a Task

Required Body Parameters:

Name	Value	Comment
itemId	The Id of the Task to Complete	Always required

URL	https://app.sortd.com/api/v1/items/markComplete
METHOD	POST
BODY	{ "itemId": "5f0892bf3ee7a675609a224f", }
RESPONSE	Content-Type application/json; charset=utf-8 Body { "success": true }
EXAMPLE	Request: curl --location --request POST 'https://app.sortd.com/api/v1/items/markComplete' \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ --header 'Content-Type: application/json' \ --data-raw '{ "itemId": "5f0892bf3ee7a675609a224f" }' Response: { "success": true }

Marking a Task as Incomplete

Required Body Parameters:

Name	Value	Comment
itemId	The Id of the Task to Mark as Incomplete	Always required

URL	https://app.sortd.com/api/v1/items/markIncomplete
METHOD	POST
BODY	{ "itemId": "5f0892bf3ee7a675609a224f", }
RESPONSE	Content-Type application/json; charset=utf-8 Body { "success": true }
EXAMPLE	Request: curl --location --request POST 'https://app.sortd.com/api/v1/items/markIncomplete' \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ --header 'Content-Type: application/json' \ --data-raw '{ "itemId": "5f0892bf3ee7a675609a224f" }' Response: { "success": true }

Assign a Task

Required Body Parameters:

Name	Value	Comment
itemId	The Id of the Task to Assign	Always required
assigneeEmail	The email address of the the Sortd board member to whom the Task should be assigned	Always required

URL	https://app.sortd.com/api/v1/items/assignTask
METHOD	POST
BODY	{ "itemId": "5f0892bf3ee7a675609a224f", "assigneeEmail": "someone@test.com" }
RESPONSE	Content-Type application/json; charset=utf-8 Body { "success": true }
EXAMPLE	Request: curl --location --request POST 'https://app.sortd.com/api/v1/items/assignTask' \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ --header 'Content-Type: application/json' \ --data-raw '{ "itemId": "5f0892bf3ee7a675609a224f", "assigneeEmail": "someone@test.com" }' Response: { "success": true }

Unassign a Task

Required Body Parameters:

Name	Value	Comment
itemId	The Id of the Task to Unassign	Always required
assigneeEmail	The email address of the the Sortd board member who should be unassigned from the Task	Always required

URL	https://app.sortd.com/api/v1/items/unassignTask
METHOD	POST
BODY	{ "itemId": "5f0892bf3ee7a675609a224f", "assigneeEmail": "someone@test.com" }
RESPONSE	Content-Type application/json; charset=utf-8 Body { "success": true }
EXAMPLE	Request: curl --location --request POST 'https://app.sortd.com/api/v1/items/unassignTask \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ --header 'Content-Type: application/json' \ --data-raw '{ "itemId": "5f0892bf3ee7a675609a224f", "assigneeEmail": "someone@test.com" }' Response: { "success": true }

Move a Task To a List

Required Body Parameters:

Name	Value	Comment
itemId	The Id of the Task to Move	Always required
listId	The Id of the List to move the tasks to (User must have access to the item as well as the destination board/list)	Always required

URL	https://app.sortd.com/api/v1/items/moveTaskToList
METHOD	POST
BODY	{ "itemId": "5f0892bf3ee7a675609a224f", "listId": "6385ed8223ae0d2ce53f8133" }
RESPONSE	Content-Type application/json; charset=utf-8 Body { "success": true }
EXAMPLE	Request: curl --location --request POST 'https://app.sortd.com/api/v1/items/moveTaskToList \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ --header 'Content-Type: application/json' \ --data-raw '{ "itemId": "5f0892bf3ee7a675609a224f", "listId": "6385ed8223ae0d2ce53f8133", }' Response: { "success": true }

Event Triggers - REST Hooks (API Subscriptions)

The Sortd API allows one to subscribe for certain types of events or actions that occur within Sortd that will then cause Sortd to call a specified webhook url. In order to achieve this, one first needs to create a subscription which can be done with the Subscribe method for the type of object (task/item, list, board) and action that one wishes to subscribe to. Currently only actions pertaining to a subset of objects can be subscribed to.

URL	https://app.sortd.com/api/v1/{{object}}/subscribe
METHOD	POST
BODY	{ "email": "{{email}}", "action": "{{action}}", "entityId": "{{entityId}}", "webhookURL": "{{webhookURL}}", "apiService": "{{apiService}}" }
RESPONSE	Content-Type application/json; charset=utf-8 Body { "id": "{{subscriptionId}}", "action": "{{action}}", "entityId": "{{entityId}}", "webhookURL": "{{webhookURL}l", "apiService": "{{apiService}}" }
EXAMPLE	Request: curl --location --request POST 'https://app.sortd.com/api/v1/items/subscribe' \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "api@sortd.com", "action": "createOnBoard", "entityId": "544808a34aca9916a8914fd2", "webhookURL": "https://hooks.zapier.com/fake-subscription-url", "apiService": "Zapier" }' Response: { "id": "5a86a580da56e432132cff95”, "action": "createOnBoard", "entityId": "544808a34aca9916a8914fd2", "webhookURL": "https://hooks.zapier.com/fake-subscription-url", "apiService": "Zapier" }

The following table outlines the actions supported:

Object	Action	Meaning	EntityId
Lists	movedToList	Triggers when a task or item is moved to the specified List	EntityId must be the List to watch for items/tasks
Items	createOnList	Triggers when a task or item is created on the specified List	EntityId must be the List to watch for new items/tasks
Items	createOnBoard	Triggers when a task or item is created on the specified Board	EntityId must be the Board to watch for new items/tasks
Items	itemCompleted	Triggers when a task or item is marked as complete	EntityId must be the Board to watch for completed items/tasks
Items	itemArchived	Triggers when a task or item is archived	EntityId must be the Board to watch for archived items/tasks
Items	itemDeleted	Triggers when a task or item is deleted	EntityId must be the Board to watch for deleted items/tasks
Items	assignedTo	Triggers when a task or item is assigned	EntityId must be the Board to watch for assigned items/tasks

Trigger Data

When an event for which a subscription has been created occurs, Sortd will call the associated subscriptions Webhook URL and POST the data as JSON with the following properties:

Name	Type/ Description	Example
id	String - The Id of task	5a86d680da96e432032bff97
title	String - Name/Title of the task	Russell, do you want to join our beta?
boardName	String - Name/Title of the Board the task is on	Board 1
boardId	String - The Id of the Board the task is on	7a86d650da96f432032bff99
listName	String - Name/Title of the List the task is on	List 1
listId	String - The Id of the List the task is on	4a86d650da96c432032bef236
dateCreated	ISO8601 UTC Date	2020-10-14T10:44:02.307Z
dueDate	(Nullable) ISO8601 UTC Date	2020-10-24T10:44:02.307Z
notes	String - notes associated with the task	Some notes
firstThread	(Nullable) JSON Object with “title”, “received” and “from”. String - title ISO8601 UTC Date - received String - from	"firstThread": { "title": "Re: Russell, do you want to.. beta?", "received": "2020-10-14T11:02:21.000Z", "from": "russell@some.email.address.com" }
completed	Boolean - Whether the task has been completed or not	false
assignedTo	Name of person to whom the task is assigned	Joe Bloggs
assignedToEmail	Email of person to whom the task is assigned	joe.bloggs@test.com

Unsubscribe

To delete or cancel a subscription one needs to call the relevant unsubscribe method for the object in question along with the id (subscription id) provided in the subscribe methods response.

URL	https://app.sortd.com/api/v1/{{object}}/unsubscribe
METHOD	POST
BODY	{ "subscriptionId": "{{subscriptionId}}" }
RESPONSE	200 OK
EXAMPLE	Request: curl --location --request POST 'https://app.sortd.com/api/v1/items/unsubscribe' \ --header 'x-access-token: eyJhbGciOiJIUzI1N….' \ --header 'Content-Type: application/json' \ --data-raw '{ "subscriptionId": "5a86a580da56e432132cff95" }' Response: None

Document Control

Revision History

Date	API Version	Responsible	Summary of Change
2020/11/18	1.0	Bradley Greathead (CTO)	Initial Draft
2021/02/04	1.1	Bradley Greathead (CTO)	Change API Token Generation request to be POST instead of GET
2022-01-21	1.2	Bradley Greathead (CTO)	Added Task Assignment Trigger
2023/02/22	1.3	Bradley Greathead (CTO)	Added ability to perform the following actions: Complete Task Mark Task as Incomplete Assign Task Unassign Task Move a Task to a List Added BoardId and ListId fields to various responses Added assignedTo and assignedToEmail to various Items List method and Trigger Data
2025/07/18	1.4	Bradley Greathead (CTO)	Fixed documentation to correctly show the endpoint for creating tasks with email. Removed listItem.title as it is ignored as the title of the email is used
2026/05/30	1.5	Pieter Joubert	Corrected documentation errors verified against the live API: Move-a-Task endpoint URL (was `/items/unassignTask`, now `/items/moveTaskToList`); assignment trigger action value (was `itemAssigned`, now `assignedTo`); Items list & trigger title field (was `name`, now `title`); fixed subscribe-response `id` key and invalid example date `2020-010-25`