JSON Data Format

Use UUID v4 for the id field

When creating new items via the import feature, you have to generate a random universally unique id for each new item and tag. When there’s a collision, the import code silently overwrites the existing item. To avoid a collision, always use a random UUID (v4) generator when creating the import objects (unless you do want to update existing items).

List of fields which use the UUID data type

• id
• parent_id (reference to the project’s/notebook’s id)
• contact_id (reference to the contact tag’s id)

UUID formating

id, parent_id and other UUID fields need to be specified as an uppercase string without dashes, as follows.

id: "709632E58EF74A55A18E9347F24ED948"

Timestamps

All timestamps are integers representing Unix time in seconds. Millisecond-valued timestamps will not work.

The root object

The .json file you’ll import must contain a single object with two array properties - tags and items. Each array may contain zero or more elements.

{
  "items": [],
  "tags": []
}

You only need to specify the items you wish to add or update. The import feature does not delete missing items or tags, so you can import a completely empty file without problem.

The item object

These fields are required for all items:

• id
• type
• list
• title
• created_on
• is_focused
• start_date or schedule for scheduled items.

type

• "a": action
• "p": project
• "n": note
• "l": notebook

list

• "i": inbox (actions only)
• "a": active/next (based on item type)
• "m": someday
• "s": scheduled (must also specify start_date or schedule field)
• "w": waiting
• "d": deleted
• "r": archived (must also specify completed_on)

completed_on

Completion timestamp (see Timestamps for format description). Null/undefined for incomplete items. Not null for completed items.

created_on

Creation timestamp. Required.

is_focused

Values: 0 or 1. Warning: True and False will not work.

energy

Energy estimate. Values: null, 1, 2, 3

time

Time estimate. Value: number of minutes

due_date

Optional due date. The timestamp’s time must be set to 0 Hours, 0 Minutes, 0 Seconds.

start_date

For one-time scheduled items only. The timestamp’s time must be set to 0 Hours, 0 Minutes, 0 Seconds.

schedule

For repeating items only. This is a complex object. Try exporting some pre-scheduled items to get an idea how it works.

recurrent_task_id

The “template” action that was used to create an instance of this specific repeating action.

contact_id

Optional contact tag to wait for. The value is tag id.

tags

An array of tag ids. Don’t pass whole objects here, only string IDs.

position_child, position_parent, position_focus, position_global

Item’s position in a specific list:

• child: position in a list of all sub-items (project actions / notes)
• parent: position in a list of all parent items (projects/notebooks)
• focus: position in a global focus list
• global: position in a the list of all items

Examples

Create an inbox action

{
  "id": "709632E58EF74A55A18E9347F24ED948" ,
  "type": "a"
  "title": "Example Inbox Action",
  "list": "i",
  "note": "optional description",
  "created_on": 1549619289,
  "is_focused" : 0
}

Create an empty active project

{
  "id": "B4F96775965F4F73A611365056301220" ,
  "type": "p"
  "title": "Example Project",
  "list": "a",
  "note": "optional description",
  "created_on": 1549619289,
  "is_focused" : 0
}

Create a project action (active and focused)

{
  "id": "B4F96775965F4F73A611365056301220" ,
  "type": "a"
  "list": "a",
  "title": "Example Project Action",
  "created_on": 1549619289,
  "is_focused" : 1,
  "parent_id": "709632E58EF74A55A18E9347F24ED948"
}

Create a tag (label)

{
  "id": "709632E58EF74A55A18E9347F24ED948",
  "title": "Example Tag",
  "type": "l"
}