URL Schemes

2Do v1.5 (Mac) supports the following URL scheme. For v2.0 and above, please see the next section.

twodo:///add?task=[prompt:Task Title]&forlist=[prompt:List Name]

2Do v3 on iOS and v2 on Mac support the following URL scheme and the x-callback-url protocol:

Show ’All’ Focus List


Show ’Today’ Focus List


Show ’Starred’ Focus List


Show ’Scheduled’ Focus List


Show List with a given name

twodo://x-callback-url/showList?name=[prompt:List Name]

Supplied parameter value must be URL-encoded

Launching app with New Task Screen

twodo://x-callback-url/addNewTask?ignoreDefaults=[prompt-num:Ignore Due Date Defaults]

ignoreDefaults (iOS 3.8.3+, Mac 2.2.2+): 0 (apply any default due date / time settings in app), 1 (ignore default dates / times)

Launching app with Search pre-filled (iOS 3.8.3+, Mac 2.2.2+)

twodo://x-callback-url/search?text=[some URL search text here]

Supplied parameter value must be URL-encoded. Here are some examples:

Searching for "John":

Searching for overdue tasks:



Get a Task’s internally used Unique Identifier (iOS 3.8.3+, Mac 2.2.2+)

twodo://x-callback-url/getTaskID?task=[known task’s title]&forList=[containing list name]&saveInClipboard=[prompt-num:Save UID in clipboard]

Supplied parameter value must be URL-encoded. Returns the internally used unique identifier for the task. x-success is filled with a key named uid.

Pasting Text (iOS 3.8.3+, Mac 2.2.2+)

twodo://x-callback-url/paste?text=[some URL encoded text to convert into tasks]&inProject=[Title of project to paste into]&forList=[List that contains the project]

Supplied parameter value must be URL-encoded. Use this URL scheme to turn text into tasks. Other than text, the rest of the following parameters are optional:

text: The text to paste

inProject: Title of the Parent project task to add tasks to

forList: The list to add to. If inProject is used, this field must also be set.

Adding Tasks

twodo://x-callback-url/add?task=[prompt:Text]&type=[prompt-num:Task Type]&forlist=[prompt:List Name]&forParentName=[prompt:Parent Task Name]&forParentTask=[prompt:Parent Task’s Unique Identifier]&note=[prompt:Notes]&priority=[prompt-num:Priority]&starred=[prompt-num:Is Starred]&tags=[prompt:Tags]&locations=[prompt:Locations]&due=[prompt:Due Date]&dueTime=[prompt:Due Time]&start=[prompt:Start Date]&repeat=[prompt-num:Repeat]&action=[prompt:Task Action]&picture=[prompt:Picture]&ignoreDefaults=[prompt-num:Ignore Due Date Defaults]&saveInClipboard=[prompt-num:Save UID in clipboard]&useQuickEntry=[prompt-num:OS X Only, will present Quick Entry Window]

All parameters are optional. Supplied parameters must be URL-encoded. This callback will also return the internally used, unique identifier of the newly created task (for the key named add), which can be used in pace of the forParentTask parameter for future callbacks.

task: Title of the task

type: Type of task to create. Following options are supported:

0 - Task (default)

1 - Project

2 - Checklist

forList: Name of an existing list in app, case-insensitive. Default list or the currently visible list on screen is selected if not used.

forParentName (v3.8.1+ on iOS and v2.2+ on Mac): The name of the project or checklist you wish to add this task to. When using this parameter, you must also provide the name of the List this project belongs to, by using the forList parameter. Please remember to URL-encode all strings.

forParentTask (v3.8.3+ on iOS and v2.2.2+ on Mac): The internally used, unique identifier of a task. If supplied, this task will be added as a sub-task to the parent task. If the parent task was previously created as a normal task (vs. a project or a checklist), the parent task will automatically be converted into a project for you.

note: Notes for the task

priority: 0 (none), 1 (low), 2 (medium), 3 (high)

starred: 0 (no), 1 (yes)

tags: Comma separated list of tags to assign to the task

locations: (iOS 3.8.3+, Mac 2.2.2+) Comma separated list of locations to assign to the task

due: Due Date. Supports the format below:

yyyy-MM-dd - Sets on the date on default due time (based on your settings, unless due time is specified separately or ignoreDefaults is set to 1)

Any number - Number of days from Today, starting from 0. e.g. 0 = Today, 1 = Tomorrow and so on

dueTime: Due Time. Supports format HH:mm or hh:mm am/pm

start: Start Date and time. Supports the format below:

yyyy-MM-dd HH:mm - Sets on the start date on the date and time specified

Any number - Number of days from Today, starting from 0. e.g. 0 = Today, 1 = Tomorrow and so on

repeat: 1 (daily), 2 (weekly), 3 (bi-weekly), 4 (monthly)

action: Supports the following formats:
call:<number> - Add a Call action to call the specified number (without angle brackets)
message:<number> - Add a Message action to message the specified number (without angle brackets)
mail:<email> - Add a Email action to email the specified email address (without angle brackets)
url:<url to visit> - Add a Browse action to visit the specified URL address (without angle brackets)
visit:<address> - Add a Visit action to visit the specified address (without angle brackets)
google:<search term> - Add a Google action to search the specified keyword (without angle brackets)

picture: (iOS 3.8.3+, Mac 2.2.2+) This can be one of two things. If the value passed is ‘lastphoto’ (iOS only), 2Do will grab the most recent photo placed on your camera roll. If the pass value is a base64 encoded string, 2Do will convert it into an image and use that as the attachment.

audio: (iOS 3.8.3+, Mac 2.2.2+) Provide a base64 encoded audio attachment

ignoreDefaults: 0 (apply any default due date / time settings in app), 1 (ignore default dates / times)

useQuickEntry (Mac Only): 0 (add a task without allowing you to edit), 1 (show pre-filled in a Quick Entry window)

saveInClipboard: (iOS 3.8.3+, Mac 2.2.2+) 0 (no), 1 (yes). The newly created task’s unique identifier (UID) will be saved in the clipboard for easier retrieval.


Add a task due Tomorrow:

Add a task with high priority:

Add a weekly repeating task:

Add a task due at 6pm today

Add a task with tags:

Adding a task to a project "Shopping List" under the list "Home" (coming in the next update):

Searching for tasks with tag ’call’ (coming in the next update):

Article ID: 601
Created On: Mon, Sep 23, 2013 at 2:51 AM
Last Updated On: Mon, Dec 5, 2016 at 2:36 PM

Online URL: https://www.2doapp.com/kb/article/url-schemes.html