NAV

Developing with Todoist

Thanks for your interest in developing apps with Todoist! In this guides section we'll provide an overview of the APIs we offer and cover some common topics for application development using our APIs.

If you are looking for reference documentation for our APIs please proceed to either the REST API Reference or Sync API Reference.

Our APIs

We offer two APIs for external developers, providing different models for sending and receiving data.

Rest API

The Todoist REST API offers the simplest approach to read and write data on the Todoist web service.

For most common application requirements this is our recommended API for external developers and uses an approach that should be familiar for anyone with experience calling RESTful APIs.

We've provided a Getting Started tutorial section within our REST API documentation to introduce you to the API and some common flows you'll encounter when developing Todoist applications. If you are totally new to our APIs or even unfamiliar with Todoist this is a great place to start.

Sync API

The Todoist Sync API is used by our web and mobile applications and is recommended for clients that will maintain a local representation of a user's full account data. It allows for incrementally sending and receiving account data by identifying positions in an account's state history using a sync token.

This API also contains additional endpoints for areas like account management and less common features that may not yet be implemented on the newer REST API.

Within the documentation for the Sync API you'll also find a Getting Started tutorial that will introduce you to using the Sync endpoint to send and receive data.

Integration Archetypes

You can leverage our APIs in countless ways. In this section, we'll introduce a few typical examples of integrations built on top of our APIs:

Authorization

In order to make authorized calls to the Todoist REST or Sync APIs, your application must first obtain an access token.

The following section describes the process for using the OAuth protocol to obtain an access token from the user.

OAuth

External applications can obtain a user authorized API token via the OAuth2 protocol. Before getting started, developers need to create their applications in the App Management Console and configure a valid OAuth redirect URL. A registered Todoist application is assigned a unique Client ID and Client Secret which are needed for the OAuth2 flow.

This procedure is comprised of 3 steps.

Step 1: Authorization request

An example of the URL to the authorization endpoint:

https://todoist.com/oauth/authorize?client_id=0123456789abcdef&scope=data:read,data:delete&state=secretstring

Redirect users to the authorization URL at the endpoint https://todoist.com/oauth/authorize, with the specified request parameters.

Required parameters

Name Description
client_id String The unique Client ID of the Todoist application that you registered.
scope String A comma separated list of permissions that you would like the users to grant to your application. See the below table for detail on the available scopes.
state String A unique and unguessable string. It is used to protect you against cross-site request forgery attacks.

Permission scopes

Name Description
task:add Grants permission to add new tasks (the application cannot read or modify any existing data).
data:read Grants read-only access to application data, including tasks, projects, labels, and filters.
data:read_write Grants read and write access to application data, including tasks, projects, labels, and filters. This scope includes task:add and data:read scopes.
data:delete Grants permission to delete application data, including tasks, labels, and filters.
project:delete Grants permission to delete projects.

Potential errors

Error Description
User Rejected Authorization Request When the user denies your authorization request, Todoist will redirect the user to the configured redirect URI with the error parameter: http://example.com?error=access_denied.
Redirect URI Not Configured This JSON error will be returned to the requester (your user's browser) if redirect URI is not configured in the App Management Console.
Invalid Application Status When your application exceeds the maximum token limit or when your application is being suspended due to abuse, Todoist will redirect the user to the configured redirect URI with the error parameter: http://example.com?error=invalid_application_status.
Invalid Scope When the scope parameter is invalid, Todoist will redirect the user to the configured redirect URI with error parameter: http://example.com?error=invalid_scope.

Step 2: Redirection to your application site

When the user grants your authorization request, the user will be redirected to the redirect URL configured for your application. The redirect request will come with two query parameters attached: code and state.

The code parameter contains the authorization code that you will use to exchange for an access token. The state parameter should match the state parameter that you supplied in the previous step. If the state is unmatched, your request has been compromised by other parties, and the process should be aborted.

Step 3: Token exchange

An example of exchanging the token:

$ curl "https://todoist.com/oauth/access_token" \
    -d "client_id=0123456789abcdef" \
    -d "client_secret=secret" \
    -d "code=abcdef" \
    -d "redirect_uri=https://example.com"

On success, Todoist returns HTTP 200 with token in JSON object format:

{
  "access_token": "0123456789abcdef0123456789abcdef01234567",
  "token_type": "Bearer"
}

Once you have the authorization code, you can exchange it for the access token by sending a POST request to the following endpoint:

https://todoist.com/oauth/access_token.

Required parameters

Name Description
client_id String The Client ID of the Todoist application that you registered.
client_secret String The Client Secret of the Todoist application that you registered.
code String The code that was sent in the query string to the redirect URL in the previous step.

Potential errors

Error Description
Bad Authorization Code Error Occurs when the code parameter does not match the code that is given in the redirect request: {"error": "bad_authorization_code"}
Incorrect Client Credentials Error Occurs when the client_id or client_secret parameters are incorrect: {"error": "incorrect_application_credentials"}

Colors

Some objects (like projects, labels, and filters) returned by our APIs may have colors defined by an id or name. The table below shows all information you may need for any of these colors.

ID Name Hexadecimal ID Name Hexadecimal
30 berry_red #b8256f 40 light_blue #96c3eb
31 red #db4035 41 blue #4073ff
32 orange #ff9933 42 grape #884dff
33 yellow #fad000 43 violet #af38eb
34 olive_green #afb83b 44 lavender #eb96eb
35 lime_green #7ecc49 45 magenta #e05194
36 green #299438 46 salmon #ff8d85
37 mint_green #6accbc 47 charcoal #808080
38 teal #158fad 48 grey #b8b8b8
39 sky_blue #14aaf5 49 taupe #ccac93

Mobile app URL schemes

Our applications for Android and iOS support custom URL schemes for launching to specific views and initiating some common actions.

Views

The following schemes are available to open a specific view:

Scheme Description
todoist:// Opens Todoist to the user's default view.
todoist://today Opens the today view.
todoist://upcoming Opens the Upcoming view.
todoist://profile Opens the profile view.
todoist://inbox Opens the inbox view.
todoist://teaminbox Opens the team inbox view. If the user doesn't have a business account it will show an alert and redirect automatically to the inbox view.
todoist://notifications Opens notifications view.

Tasks

Example of adding a task:

todoist://addtask?content=mytask&date=tomorrow&priority=4

Here's an example of a content value:

Create document about URL Schemes!

And how it should be supplied using Percent-encoding:

Create&20document%20about%20URL%20Schemes%21

Here's an example of a date value:

Tomorrow @ 14:00

And how it should be supplied using Percent-encoding:

Tomorrow%20@%2014:00

The following schemes are available for tasks:

Scheme Description
todoist://task?id={id} Opens a task by ID.
todoist://addtask Opens the add task view to add a new task to Todoist.

The todoist://addtask scheme accepts the following optional values:

Value Description
content URL encoding The content of the task, which should be a string that is in Percent-encoding (also known as URL encoding).
date URL encoding The due date of the task, which should be a string that is in Percent-encoding (also known as URL encoding). Look at our reference to see which formats are supported.
priority Integer The priority of the task (a number between 1 and 4, 4 for very urgent and 1 for natural).
Note: Keep in mind that very urgent is the priority 1 on clients. So, p1 will return 4 in the API.

This URL scheme will not automatically submit the task to Todoist, it will just open and pre-fill the add task view. If no values are passed, the add task view will just be opened.

Projects

The following schemes are available for tasks:

Scheme Description
todoist://projects Opens the projects view (shows all projects).
todoist://project?id={id} Opens a specific project by ID.

Example of opening a specific project:

todoist://project?id=128501470

The todoist://project scheme accepts the following required value:

Value Description
id Integer The ID of the project to view. If the ID doesn't exist, you don't have access to the project, or the value is empty, an alert will be showed and the user will be redirected to the projects view.

Labels

The following schemes are available for labels:

Scheme Description
todoist://labels Opens the labels view (shows all labels)
todoist://label?name={name} Opens a specific label by name.

Example of opening a specific label:

todoist://label?name=Urgent

The todoist://label scheme accepts the following required value:

Value Description
name String The name of the label to view. If the label doesn't exist, you don't have access to the label, or the value is empty, an alert will be shown.

Filters

The following schemes are available for filters:

Scheme Description
todoist://filters Opens the filters view (shows all filters)
todoist://filter?id={id} Opens a specific filter by ID.

Example of opening a specific filter:

todoist://filter?id=9

The todoist://filter scheme accepts the following required value:

Value Description
id Integer The ID of the filter to view. If the ID doesn't exist, you don’t have access to the filter, or the value is empty, an alert will be showed and the user will be redirected to the filters view.

The following scheme is available for searching (Android only):

Scheme Description
todoist://search?query={query} Used to search in the Todoist application.

Example of searching for "Test & Today":

todoist://search?query=Test%20%26%20Today

The todoist://search scheme accepts the following required value:

Value Description
query URL encoding The query to search in the Todoist application, which should be a string that is in Percent-encoding (also known as URL encoding).

Market your app

Market your app to millions of Todoist users with a custom integration page. Our searchable directory lets our audience easily find, install, and use your app — making it an effortless yet effective way to promote your work!

Get started today.

Submissions

To begin, fill out the app submissions form. Just add a marketing description, installation instructions, and links to your website and privacy policy.

We'll also ask you for some images, in the following format:

Review

After you've submitted your app, we'll email you a confirmation. We aim to review submissions and respond with any feedback within 10 business days.

During the review, we'll make sure:

If we find any issues along the way, we'll be in touch via email and work with you to resolve them. If you have any questions or updates at any time, you can reply to any of the emails you've received during the submissions process. We'll aim to get back to you within 2 business days.

Publishing

Once your submission has passed our review, we'll publish your listing and provide you with a public link that you can share! We'll also translate your listing to expand the reach of your marketing.

If you have any further questions or updates to provide after we've published your integration page, you can always reach out to our app submissions team at submissions@doist.com. We're happy to help!

Brand usage

Thanks for using Todoist's APIs to build an application!

If you plan to utilize Todoist's logo or branding in the visual design of your application or website, please adhere to Todoist's brand guidelines.

In addition, please take note of the following:

By using the Todoist marks you agree to properly follow the above brand guidelines as well as our Terms of Service. For further information about the use of the Todoist brand, please contact press@doist.com.

Get in touch

Interested in developing an integration for Todoist but unsure where to start? Get in touch with us at integrations@doist.com, and we'll be happy to help.