Tasks

The primary unit within Flow; tasks track units of work and can be assigned, sorted, nested, and tagged. Tasks can either be part of a List, or "private" (meaning "without a list", essentially). Through this endpoint you are able to do anything you wish to your tasks in Flow, including create new ones.

Base URL

https://api.getflow.com/v2/tasks

Get Tasks

GET /

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Select resources belonging to an organization.

Optional Parameters

Parameter	Type	Description
`workspace_id`	`Integer`	Select resources belonging to the given workspace.
`include`	`String`	Comma-separated list of related resources to embed in the response. Supported values: `schedule` `files` `file_associations` `parent`
`order`	`String`	Sort resources (descending) based on the provided field. Supported values: `due_on` `starts_on` `created_at` `position` `account_id` `list_id` `section_id` `owner_id` `name` `completed_at` `updated_at`
`cursor`	`Integer`	Select resources after the given offset.
`limit`	`Integer`	Number of resources to return. Max: 100
`created_before`	`ISO-8601 DateTime`	Select resources created before a certain time.
`created_after`	`ISO-8601 DateTime`	Select resources created after a certain time.
`updated_before`	`ISO-8601 DateTime`	Select resources updated before a certain time.
`updated_after`	`ISO-8601 DateTime`	Select resources updated after a certain time.
`completed_after`	`ISO-8601 DateTime`	Select resources completed after a certain time.
`deleted`	`Boolean`	Select deleted resources.
`cleared`	`Boolean`	Select cleared resources.

Query Views

Name	Description	Parameters
`default`	When no view is specified.	`owner_id` (Optional) Select resources owned by given account. `list_id` (Optional) Select resources in given list. `group_id` (Optional) Select resources in given group. `schedule_id` (Optional) Select resources created by given schedule. `tag` (Optional) Select resources with given tag. `account_id` (Optional) Select resources belonging to an account. `parent_id` (Optional) Select resources that have a parent task with the given id. `section_id` (Optional) Select resources in a given section. `tag_id` (Optional) Select resources with a given tag. `due` (Optional) Select resources that have a due date. `completed` (Optional) Select resources that are completed.
`flagged`	Tasks you have flagged	`list_id` (Optional) Get tasks from the given List
`delegated`	Tasks you created but are not assigned to you	`list_id` (Optional) Get tasks from the given List
`scheduled`	Tasks that have a start or due date, sorted by start and due dates.	`require_due_on` (Optional) Only get tasks that have a due date, not just a start date. `workspace_id` (Optional) Get tasks in the given Workspace. `list_id` (Optional) Get tasks in the given List. `owner_id` (Optional) Get tasks assigned to the given account. `completed` (Optional) Get tasks that have been completed. `start_before` (Optional) Get tasks with a start date before the given date. `start_after` (Optional) Get tasks with a start date after the given date. `due_before` (Optional) Get tasks with a due date before the given date. `due_after` (Optional) Get tasks with a due date after the given date.
`unscheduled`	Tasks that have a neither a start nor due date.	`workspace_id` (Optional) Get tasks from the given Workspace. `list_id` (Optional) Get tasks from the given List. `owner_id` (Optional) Get tasks assigned to the given account. `completed` (Optional) Return tasks that have been completed.
`unassigned`	All accessible tasks that are unassigned.	`list_id` (Optional) Get tasks from the given List.
`recent`	Recently viewed tasks ordered by last viewed.	`workspace_id` (Required) Get tasks from the given workspace `list_id` (Optional) Get tasks from the given List `completed` (Optional) Return completed tasks if true
`owned`	Tasks that are assigned to you.	`list_id` (Optional) Get tasks from the given List
`inbox`	Tasks in your Inbox.
`subtasks`	Return Tasks that are subtasks of the given parent.	`parent_id` (Required) the ID of the parent task

Examples

Get all tasks for a list

To retrieve all tasks for a given list, simply provide it along with the organization_id.

GET /v2/tasks?organization_id=52&list_id=627486

You should get a response with the tasks in the given list with the HTTP status of "200 OK".

{
  "tasks": [
    {
      "id": 5646530,
      "account_id": 8,
      "owner_id": 8,
      "list_id": 627486,
      "section_id": 334,
      "name": "Don't disable submit button in Chat and Workspace creation forms",
      "due_on": null,
      "starts_on": null,
      "subscriber_ids": [
        8,
        167324,
        104009
      ],
      "position_list": 14401811658,
      "position_owner": 14395851197,
      "position_upcoming": 14395851197,
      "cleared": false,
      "comments_count": 0,
      "completed_at": null,
      "deleted_at": null,
      "created_at": "2015-08-14T13:43:24-07:00",
      "updated_at": "2015-08-21T11:19:25-07:00",
      "workspace_id": 1,
      "schedule_id": null,
      "deleted": false,
      "completed": false,
      "tags": [],
      "parent_id": null,
      "position": null,
      "mirror_parent_subscribers": null,
      "has_children": null,
      "flagger_ids": [],
      "mirror_parent_tags": null,
      "subtasks": []
    }
  ]
}

Error Responses

HTTP 400 - Could not get records with the provided attributes. Check response for specific details.

Get Task

GET /:id

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Select resources belonging to an organization.

Optional Parameters

Parameter	Type	Description
`include`	`String`	Comma-separated list of related resources to embed in the response Supported values: `schedule` `files` `file_associations` `parent`

Examples

Fetch a task

Fetching a single task requires knowing its ID and the organization_id.

GET /v2/tasks/5646530?organization_id=52

If the task is found and accessible by your account, you should get the full task object back and a HTTP 200 OK status.

{
  "task": {
    "id": 5646530,
    "account_id": 8,
    "owner_id": 8,
    "list_id": 627486,
    "section_id": 334,
    "name": "Don't disable submit button in Chat and Workspace creation forms",
    "due_on": null,
    "starts_on": null,
    "subscriber_ids": [
      8,
      167324,
      104009
    ],
    "position_list": 14401811658,
    "position_owner": 14395851197,
    "position_upcoming": 14395851197,
    "cleared": false,
    "comments_count": 0,
    "completed_at": null,
    "deleted_at": null,
    "created_at": "2015-08-14T13:43:24-07:00",
    "updated_at": "2015-08-21T11:19:25-07:00",
    "workspace_id": 1,
    "schedule_id": null,
    "deleted": false,
    "completed": false,
    "tags": [],
    "parent_id": null,
    "position": null,
    "mirror_parent_subscribers": null,
    "has_children": null,
    "flagger_ids": [],
    "mirror_parent_tags": null,
    "subtasks": []
  },
  "includes": {
    "tasks": []
  }
}

Error Responses

HTTP 400 - Could not get record with the provided attributes. Check response for specific details.
HTTP 404 - Could not find record.

Create Task

POST /

Most parameters will be nested under a root-level task object. Any parameters prefixed with this key should be nested underneath it. Check out the examples if you're unsure what the payload should look like.

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Create resources under the given organization.
`task`	`Object`	Contains the parameters to create the task.
`task` → `workspace_id`	`Integer`	Create resources under the given workspace.
`task` → `name`	`String`	The title of the task.

Optional Parameters

Parameter	Type	Description
`task` → `owner_id`	`Integer`	The ID of the account to whom this task will be assigned.
`task` → `list_id`	`Integer`	Put the new task in a list ("project"). Omit this param to have the task be private.
`task` → `starts_on`	`Date`	The date on which the task should start.
`task` → `due_on`	`Date`	The date on which the task should be due.
`task` → `mirror_parent_subscribers`	`Boolean`	If this task will be a subtask, and this is true, the parent tasks's subscribers will be mirrored to this one.
`task` → `mirror_parent_tags`	`Boolean`	If this task will be a subtask, and this is true, the parent tasks's tags will be mirrored to this one.
`task` → `note_content`	`String`	Provide the content for the task's note.
`task` → `note_mime_type`	`String`	Identify which markup language is used to format the given note Supported values: `text/plain` `text/x-markdown` `text/html`
`task` → `parent_id`	`Integer`	If provided, this task will become a subtask of the given task.
`task` → `position_list`	`Integer`	Determines the sort order when showing tasks in, or grouped by, a list.
`task` → `position_owner`	`Integer`	Currently unused.
`task` → `position_upcoming`	`Integer`	Determines the sort order when showing tasks grouped by their `due_date`.
`task` → `position`	`Integer`	Determines the sort order of tasks.
`task` → `section_id`	`Integer`	Specify which section under which to create this task.
`task` → `workspace_id`	`Integer`	Specify which workspace under which to create this task.
`task` → `subscriptions`	`Array`	An array of objects with an `account_id` key with the account ID to subscribe to the task.
`task` → `subtasks`	`Array`	An array of minimal task objects that support a subset of the creation params. These will be created as subtasks on the new task. Supported values: `name` `owner_id` `due_on` `starts_on` `note_content` `note_mime_type` `completed` `position` `cid` `id`
`task` → `tags`	`Array`	A list of tag names to apply to the new task.

Examples

Create a task

In order to create a task, you will need a workspace_id and organization_id (the workspace must be part of the given organization). The new task will be created as a private task assigned to you in the given workspace.

POST /v2/tasks

{
  "organization_id": 52,
  "task": {
    "name": "My new task",
    "workspace_id": 19
  }
}

You will receive the full task object back, along with an HTTP 201 Created status.

{
  "task": {
    "id": 14,
    "account_id": 108,
    "owner_id": null,
    "list_id": null,
    "section_id": null,
    "name": "My new task",
    "due_on": null,
    "starts_on": null,
    "subscriber_ids": [
      108
    ],
    "position_list": null,
    "position_owner": null,
    "position_upcoming": null,
    "cleared": false,
    "comments_count": 0,
    "completed_at": null,
    "deleted_at": null,
    "created_at": "2017-08-22T08:55:12-07:00",
    "updated_at": "2017-08-22T08:55:12-07:00",
    "workspace_id": 19,
    "schedule_id": null,
    "deleted": false,
    "completed": false,
    "tags": [],
    "parent_id": null,
    "position": null,
    "mirror_parent_subscribers": null,
    "has_children": null,
    "flagger_ids": [],
    "mirror_parent_tags": null,
    "subtasks": []
  }
}

Error Responses

HTTP 422 - Could not create record with the provided attributes. Check response for specific details.

Update a Task

PUT /:id

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Query for resources under the given organization.
`task` → `workspace_id`	`Integer`	Query for resources under the given workspace.

Optional Parameters

Parameter	Type	Description
`task` → `completed`	`Boolean`	If set to `true`, will complete the task.
`task` → `starts_on`	`Date`	The date on which the task should start.
`task` → `due_on`	`Date`	The date on which the task should be due.
`task` → `list_id`	`Integer`	Put the new task in a list ("project"). Omit this param to have the task be private.
`task` → `mirror_parent_subscribers`	`Boolean`	If this task will be a subtask, and this is true, the parent tasks's subscribers will be mirrored to this one.
`task` → `mirror_parent_tags`	`Boolean`	If this task will be a subtask, and this is true, the parent tasks's tags will be mirrored to this one.
`task` → `name`	`String`	The title of the task.
`task` → `note_content`	`String`	Provide the content for the task's note.
`task` → `note_mime_type`	`String`	Identify which markup language is used to format the given note Supported values: `text/plain` `text/x-markdown` `text/html`
`task` → `owner_id`	`Integer`	The ID of the account to whom this task will be assigned.
`task` → `parent_id`	`Integer`	If provided, this task will become a subtask of the given task.
`task` → `position_list`	`Integer`	Determines the sort order when showing tasks in, or grouped by, a list.
`task` → `position_owner`	`Integer`	Currently unused.
`task` → `position_upcoming`	`Integer`	Determines the sort order when showing tasks grouped by their `due_date`.
`task` → `position`	`Integer`	Determines the sort order of tasks.
`task` → `section_id`	`Integer`	Specify which section under which to move this task.
`task` → `subscriber_ids`	`Array`	An array of objects with an `account_id` key with the account ID to subscribe to the task.
`task` → `subtasks`	`Array`	An array of minimal task objects that support a subset of the creation params. These will be created as subtasks on the new task. Supported values: `name` `owner_id` `due_on` `starts_on` `note_content` `note_mime_type` `completed` `position` `cid` `id`
`task` → `tags`	`Array`	A list of tag names to apply to the new task.

Examples

Update a task's name

To change attributes of an existing task, we need the ID of the task, the workspace_id of its workspace, and the organization_id.

PUT /v2/tasks/918273

{
  "organization_id": 52,
  "task": {
    "id": 918273,
    "workspace_id": 1,
    "name": "A new task name"
  }
}

If there are no errors, you will get the updated full task object in the response and an HTTP 200 OK status.

{
  "task": {
    "id": 14,
    "account_id": 108,
    "owner_id": null,
    "list_id": null,
    "section_id": null,
    "name": "My new task",
    "due_on": null,
    "subscriber_ids": [
      108
    ],
    "position_list": null,
    "position_owner": null,
    "position_upcoming": null,
    "cleared": false,
    "comments_count": 0,
    "completed_at": null,
    "deleted_at": null,
    "created_at": "2017-08-22T08:55:12-07:00",
    "updated_at": "2017-08-22T08:55:12-07:00",
    "workspace_id": 19,
    "schedule_id": null,
    "deleted": false,
    "completed": false,
    "tags": [],
    "parent_id": null,
    "position": null,
    "mirror_parent_subscribers": null,
    "has_children": null,
    "flagger_ids": [],
    "mirror_parent_tags": null,
    "subtasks": []
  }
}

Error Responses

HTTP 422 - Could not create record with the provided attributes. Check response for specific details.
HTTP 404 - Could not find the task to update.

Comments

Comments represent a linear interaction that happens between different stake holders within the context of a task and are captured as activities. They provide an avenue to hold discussions, usually related to the task, and also help with communicating updates. These endpoints allow creating, updating and deleting comments for a given task. Currently, you can get a list of comments through the activities endpoint.

Base URL

https://api.getflow.com/v2/comments

Create Comment

POST /

Most parameters will be nested under a root-level comment object. Any parameters prefixed with this key should be nested underneath it. Check out the examples if you're unsure what the payload should look like.

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Create resources under the given organization.
`workspace_id`	`Integer`	Create resources under the given workspace; must be a workspace under the given organization.
`task_id`	`Integer`	Create a comment for the given task.
`comment`	`Object`	Contains the parameters to create the comment.
`comment` → `body`	`String`	Content of the comment.
`comment` → `mime_type`	`String`	Identify which markup language is used to format the given comment. Supported values: `text/plain` `text/x-markdown` `text/html`

Examples

Error Responses

HTTP 400 - Could not create record with the provided attributes. Check response for specific details.
HTTP 404 - Could not find an associated record to create the resource.

Update a Comment

PUT /:id

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Query for resources under the given organization.
`workspace_id`	`Integer`	Query for resources under the given workspace; must be a workspace under the given organization.
`task_id`	`Integer`	Query for resources under the given task.
`comment` → `body`	`String`	Content of the comment.

Optional Parameters

Parameter	Type	Description
`comment` → `mime_type`	`String`	Identify which markup language is used to format the given comment. Supported values: `text/plain` `text/x-markdown` `text/html`

Examples

Update a comment

To change an existing comment, we need the ID of the comment, the workspace_id, organization_id and the task_id.

PUT /v2/comments/1281164?workspace_id=941&task_id=5706881&organization_id=1200

{
  "comment": {
    "body": "Get things done by the weekend."
  }
}

If there are no errors, you will get the updated full comment object in the response and an HTTP 200 OK status.

{
    "comment": {
        "id": 1281164,
        "account_id": 123456,
        "task_id": 5706881,
        "body": "Get things done by the weekend.",
        "created_at": "2017-07-28T11:35:11-07:00",
        "updated_at": "2017-07-28T11:36:31-07:00",
        "deleted": false,
        "mime_type": "text/x-markdown",
        "cid": null
    },
    "request_uuid": "ef4f86dc-427a-4b36-ac35-95511e58c086"
}

Error Responses

HTTP 400 - Could not get record with the provided attributes. Check response for specific details.
HTTP 404 - Could not find record.

Delete a Comment

DELETE /:id

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Query for resources under the given organization.
`workspace_id`	`Integer`	Query for resources under the given workspace; must be a workspace under the given organization.
`task_id`	`Integer`	Query for resources under the given task.

Examples

Delete a comment

To remove an existing comment, we need the ID of the comment, the workspace_id, organization_id and the task_id.

DELETE /v2/comments/1281164?workspace_id=941&task_id=5706881&organization_id=1200

If there are no errors, the comment would be removed and you would receive an HTTP 204 No Content status.

Error Responses

HTTP 400 - Could not remove record with the provided attributes. Check response for specific details.
HTTP 404 - Could not find record.

Lists

Lists, perhaps known better as "Projects", are collections of tasks within Flow. Lists can be private ("invite-only") or public. These endpoints provide read-only access to your Lists in Flow to help when working with other resources. Currently you cannot create or modify Lists through the Public API.

Base URL

https://api.getflow.com/v2/lists

Get Lists

GET /

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Select lists from the given organization.
`workspace_id`	`Integer`	Select lists from the given workspace; must be a workspace under the given organization.

Optional Parameters

Parameter	Type	Description
`archived`	`Boolean`	Select only archived lists.
`archived_date_before`	`Time`	This acts a pagination cursor for archived lists in combination with `limit`. Set before to the archived_at of the last list in the previous results to fetch the next page. Time should be formatted as YYYY-MM-DD (ISO 8601). Remember to add a timezone or specify times in UTC.
`include`	`String`	Additionally return the given related resources. Supported values: `sections` `files` `file_associations`
`limit`	`Integer`	Number of lists to return (only available for archived lists in conjunction with `before`)
`start_date_after & start_date_before`	`ISO-8601 Date`	Used to return archived lists started within a certain time frame. These attributes can be passed in together or separately.

Examples

Get lists with their sections

To query for lists in a particular workspace, and return the sections in those lists alongside, simply provide the include parameter.

GET /v2/lists?organization_id=52&include=sections

The response should have an HTTP 200 OK status and will include all lists that match the filters, as well as a top-level sections with all the sections for the lists that have been returned.

{
  "lists": [
    {
      "id": 633082,
      "workspace_id": 1,
      "name": "Group Test List",
      "invite_only": false,
      "position": 1,
      "default_view": "row",
      "group_id": 492,
      "default_section_id": null,
      "tasks_count": 0,
      "subscriber_ids": [
        168284,
        168283,
        168282,
      ],
      "archived_at": null,
      "archived": false,
      "deleted": false,
      "deleted_at": null,
      "created_at": "2017-06-23T11:32:41-07:00",
      "updated_at": "2017-06-23T16:39:35-07:00",
      "starts_on": null,
      "ends_on": null,
      "include_weekends": true,
      "completed_tasks_count": 0
    },
    {
      "id": 633076,
      "workspace_id": 1,
      "name": "Eric Test Project",
      "invite_only": false,
      "position": 0,
      "default_view": "row",
      "group_id": null,
      "default_section_id": null,
      "tasks_count": 3,
      "subscriber_ids": [
        168284,
        168283,
        168282,
      ],
      "archived_at": null,
      "archived": false,
      "deleted": false,
      "deleted_at": null,
      "created_at": "2016-09-30T11:24:28-07:00",
      "updated_at": "2017-06-23T16:39:17-07:00",
      "starts_on": null,
      "ends_on": null,
      "include_weekends": true,
      "completed_tasks_count": 0
    }
  ],
  "sections": [
    {
      "id": 16299,
      "list_id": 633076,
      "name": "test",
      "position": 1
    },
    {
      "id": 15729,
      "list_id": 633076,
      "name": "asdf",
      "position": 1482252068
    }
  ]
}

Error Responses

HTTP 400 - Could not satisfy request with the given params. Check the response for more details.

Get List

GET /:id

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Select lists from the given organization

Optional Parameters

Parameter	Type	Description
`include`	`String`	Additionally return the given related resources. Supported values: `sections` `files` `file_associations`

Examples

Get a List

To fetch all information about a List, simply provide its ID, organization_id, and the workspace_id it belongs to.

GET /v2/lists/633082?organization_id=52&workspace_id=1

You will receive the full list object and get an HTTP 200 OK status.

{
  "list": {
    "id": 633082,
    "workspace_id": 1,
    "name": "Group Test List",
    "invite_only": false,
    "position": 0,
    "default_view": "row",
    "group_id": 492,
    "default_section_id": null,
    "tasks_count": 0,
    "subscriber_ids": [
      168284,
      168283,
      168282
    ],
    "archived_at": null,
    "archived": false,
    "deleted": false,
    "deleted_at": null,
    "created_at": "2017-06-23T11:32:41-07:00",
    "updated_at": "2017-06-23T16:39:35-07:00",
    "starts_on": null,
    "ends_on": null,
    "include_weekends": true,
    "completed_tasks_count": 0
  },
  "files": [],
  "file_associations": [],
  "sections": []
}

Error Responses

HTTP 404 - The given list could not be found.

Workspaces

Perhaps better known as "teams", workspaces are for organizing people and lists (lists perhaps better known as "projects"). Both lists and tasks are given a workspace for easy organization and permissions management. Any member of a workspace can access its public lists, or work with private tasks directly under the workspace itself.

These endpoints provide read-only access to your workspaces in Flow. Currently you cannot create or modify workspaces through the Public API.

Base URL

https://api.getflow.com/v2/workspaces

Get Workspaces

GET /

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`

Optional Parameters

Parameter	Type	Description
`order`	`String`	Sort resources (descending) based on a given field.
`include`	`String`	Additionally return the given related resources. Supported values: `memberships` `accounts`
`before`	`ISO-8601 DateTime`	Select resources created before a given date.
`after`	`DateTime`	Select resources created after a given date.
`cursor`	`Integer`	Select resources after the given offset.
`limit`	`Integer`	Number of resources to return.

Error Responses

HTTP 400 - Could not get records with the provided attributes. Check response for specific details.

Get a Workspace

GET /:id

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`

Optional Parameters

Parameter	Type	Description
`include`	`String`	Additionally return the given related resources. Supported values: `memberships` `accounts`

Error Responses

HTTP 404 - The workspace could not be found.

Memberships

A membership is the glue between a workspace and an account. In order to be a member of a workspace, a Membership record specifying the account and workspace must exist. These endpoints, however, only provide read-only access to existing memberships to help you work with other data. Currently it is not possible to modify or create memberships through the Public API.

Base URL

https://api.getflow.com/v2/memberships

Get Memberships

GET /

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`
`workspace_id`	`Integer`

Optional Parameters

Parameter	Type	Description
`order`	`String`	Sort resources (descending) based on a given field.
`include`	`String`	Additionally return the given related resources. Supported values: `accounts`
`before`	`DateTime`	Select resources created before a given date.
`after`	`DateTime`	Select resources created after a given date.
`cursor`	`Integer`	Select resources after the given offset.
`limit`	`Integer`	Number of resources to return.

Examples

Get all memberships with accounts

To get all memberships for a workspace, provide the workspace_id and the organization_id. We'll also request the account objects be returned alongside the memberships for ease.

GET /v2/memberships?organization_id=52&workspace_id=1&include=accounts

You will be given the memberships and the related account objects, with an HTTP 200 OK status.

{
  "memberships": [
    {
      "id": 7506,
      "workspace_id": 1,
      "position": 0,
      "role": "member",
      "account_id": 168284,
      "inviter_id": 167693,
      "deleted": false
    }
  ],
  "accounts": [
    {
      "id": 168284,
      "email": "what@what.com",
      "demo": false,
      "name": "what@what.com"
    }
  ]
}

Error Responses

HTTP 400 - Could not get records with the provided attributes. Check response for specific details.

Get a Membership

GET /:id

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`

Optional Parameters

Parameter	Type	Description
`include`	`String`	Additionally return the given related resources. Supported values: `accounts`

Examples

Get a single membership

Simply provide the ID of the membership to fetch with the organization_id.

GET /v2/memberships/1234?organization_id=52

HTTP 200 OK

{
  "membership": {
    "id": 7506,
    "workspace_id": 1,
    "position": 0,
    "role": "member",
    "account_id": 168284,
    "inviter_id": 167693,
    "deleted": false
  },
  "accounts": []
}

Error Responses

HTTP 404 - The membership couldn't be found.

Webhooks

Integration Webhooks allow you to integrate external services with Flow by sending requests to external services when activities happen in Flow. For example, with webhooks you could trigger CI jobs when certain things happen in Flow, or integrate with a service like Zapier for even more integration and automation capability. The URL you provide will be sent an HTTP POST every time an activity happens on the target Task or a Task within the target List, with some minimal details on what happened (enough to allow you to make a separate request yourself to fetch the full records, if necessary).

Base URL

https://api.getflow.com/v2/integration_webhooks

Get webhooks

GET /

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Select webhooks under this organization.

Examples

Get all webhooks for an organization

To list all webhooks (on public resources) for an organization, just pass the organization_id.

GET /v2/integration_webhooks?organization_id=6758493

The response will have HTTP 200 OK status and contain the Integration Webhooks.

{
  "integration_webhooks": [
    {
      "id": 1234,
      "account_id": 98761234,
      "activity_verbosity": "everything",
      "organization_id": 6758493,
      "accepts": "application/vnd.flow.v2+json",
      "name": "My service",
      "resource_type": "Task",
      "resource_id": 12345678,
      "url": "https://example.com/flow-webhook/"
    },
    ...
  ]
}

Create a webhook

POST /

Most parameters will be nested under a root-level integration_webhook object. Any parameters prefixed with this key should be nested underneath it. Check out the examples if you're unsure what the payload should look like.

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Create the webhook under this organization.
`integration_webhook` → `name`	`String`	A human-friendly name for your, and your teammates', reference.
`integration_webhook` → `url`	`String`	The HTTP endpoint that will consume events from us.
`integration_webhook` → `resource_type`	`String`	The type of resource you are creating a webhook for. Supported values: `List` `Task`
`integration_webhook` → `resource_id`	`Integer`	the ID of the List or Task record.

Examples

Create a webhook for a Task

To add a webhook to a task, just send along a few details about which task and where to send the payloads.

POST /v2/integration_webhooks

{
  "organization_id": 52,
  "integration_webhook": {
    "name": "My service",
    "url": "https://example.com/flow-webhook/",
    "resource_type": "Task",
    "resource_id": 12345678
  }
}

You'll receive an HTTP 201 Created status with the new webhook record. Activities on the Task should now be getting sent to your webhook URL.

{
  "integration_webhook": {
    "id": 1234,
    "account_id": 98761234,
    "activity_verbosity": "everything",
    "organization_id": 6758493,
    "accepts": "application/vnd.flow.v2+json",
    "name": "My service",
    "resource_type": "Task",
    "resource_id": 12345678,
    "url": "https://example.com/flow-webhook/"
  }
}

Error Responses

HTTP 400 - Could not create the record with the given attributes. Check the response for more details.

Update a webhook

PUT /:id

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Find the webhook under this organization.

Examples

Update a webhook

PUT /v2/integration_webhooks/1234

{
  "organization_id": 6758493,
  "integration_webhook": {
    "name": "A new name"
  }
}

You will receive the updated record in the response with HTTP 200 OK status.

{
  "integration_webhook": {
    "id": 1234,
    "account_id": 98761234,
    "activity_verbosity": "everything",
    "organization_id": 6758493,
    "accepts": "application/vnd.flow.v2+json",
    "name": "A new name",
    "resource_type": "Task",
    "resource_id": 12345678,
    "url": "https://example.com/flow-webhook/"
  }
}

Error Responses

HTTP 400 - Could not update the record with the given attributes. Check the response for more details.
HTTP 404 - Could not find the record to update.

Destroy a webhook

DELETE /:id

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	Find the webhook under this organization.

Examples

Delete a webhook

To destroy a webhook, simply send a delete request with the organization_id.

DELETE /v2/integration_webhooks/1234?organization_id=52

You will receive an HTTP 204 No Content status as a response, if successful.

HTTP 204 No Content

Error Responses

HTTP 404 - Could not find the record to destroy.

Access Tokens

In order to access the Flow API, you will need a Personal Access Token. This is an identifying string of random-looking gibberish that tells the API who you are (and thus what you have access to).

You cannot generate your first Personal Access Token via the API. Simply, you need a Personal Access Token to access the API, so without your first token there is no way for you to provison any others. Please refer to our introduction document for instructions on how to generate your first token through the Flow Web or Desktop apps.

Base URL

https://api.getflow.com/v2/access_tokens

Get Access Tokens

GET /

Examples

Get all your tokens

To get a list of all your Personal Access Tokens, simply provide the organization_id.

GET /v2/access_tokens?organization_id=52

You will get a response with all the tokens for your account, with an HTTP 200 OK status.

{
  "access_tokens": [
    {
      "id": 8435191,
      "name": "For CI",
      "token": "3af2c61b1cae3a0c396afac2ee6b8f702b93caf8c01fc43c235c904f52329216",
      "account_id": 41,
      "organization_id":42,
      "enabled": true
    }
  ]
}

Create an Access Token

POST /

Most parameters will be nested under a root-level access_token object. Any parameters prefixed with this key should be nested underneath it. Check out the examples if you're unsure what the payload should look like.

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`	the organization to which the token will have access.
`access_token` → `name`	`String`	a "friendly" name for the token, to identify it.

Examples

Generate a new token

To generate a new Personal Access Token for your account, just provide a name and the organization under which to create it.

POST /v2/access_tokens

{
  "access_token": {
    "organization_id": 52,
    "name": "Secret Things"
  }
}

You will receive the full token object back, including the token string itself, with an HTTP 201 Created status.

{
  "access_token": {
    "id": 8435191,
    "name": "Secret Things",
    "token": "3af2c61b1cae3a0c396afac2ee6b8f702b93caf8c01fc43c235c904f52329216",
    "account_id": 41,
    "organization_id": 52,
    "enabled": true
  }
}

Error Responses

HTTP 400 - Could not locate organization with the given ID for the current account.
HTTP 422 - Could not save record with the provided attributes. Check response for specific details.

Revoke an Access Token

DELETE /:id

Error Responses

HTTP 404 - The token could not be found.

Activities

An Activity is something that happened. It describes an action done by a particular person to a single resource. Activities are generated automatically as you take actions in Flow (including actions you take with the Public API); you cannot manually create an Activity.

Glossary

Audience - The audience of an activity is anyone who can see it.
Subscriber - An activity subscriber is used so we can find activities via the subscribed filter.
Recipient - A recipient of an activity is presumably someone that really cares about it. It’s typically something directed right at a particular account (or set of accounts).
Activity Actions
An Activity will always define an “action”, which indicates which event has created the activity. Different actions are supported by different targets, a target being either a Task, a List, or another Activity.
Task Targets may generate create, complete, reopen, delete, add_comment, set_due, unset_due, change_due, set_list, unset_list, change_list, set_section, unset_section, change_section, set_owner, unset_owner, change_owner, attachments_added, tags_added, tags_removed, set_note, or change_note activities.
List Targets may generate archive, add_subscribers, remove_subscribers, set_note, change_note, set_time_period, unset_time_period, or change_time_period activites.
Activity Targets will only generate like activities.

Base URL

https://api.getflow.com/v2/activities

Get Activities

GET /

Required Parameters

Parameter	Type	Description
`limit`	`Integer`
`organization_id`	`Integer`

Optional Parameters

Parameter	Type	Description
`order`	`String`	Sort resources (descending) based on a given field.
`include`	`String`	Additionally return the given related resources. Supported values: `tasks` `lists` `workspaces`
`before`	`ISO-8601 DateTime`	Select resources created before a given date.
`after`	`ISO-8601 DateTime`	Select resources created after a given date.
`cursor`	`Integer`	Select resources after a given offset.
`limit`	`Integer`	Number of resources to return.
`pagination`	`String`	Currently the only option for pagination is "linear"

Query Views

Name	Description	Parameters
`default`	When no view is specified.	`task_owner_id` (Optional) `resource_id` (Optional) `only_action` (Optional) `except_action` (Optional)
`notified`	Important Activities that you should be notified of.	`read` (Required) Include activities that have been marked as read
`resource`		`resource_type` (Required) Select activities for a particular resource type Supported values: `Task` `resource_id` (Required) the ID of the resource whose activities to fetch

Examples

Get all activities for a workspace

Simply provide the organization_id and workspace_id whose activities you wish to retrieve.

GET /v2/activities?organization_id=52&workspace_id=1

The response will have an HTTP status of 200 OK and have a Link header with the URL to fetch for the next page of results.

Link: next=https://api.getflow.com/activities?organization_id=52&read_after=2016-06-14T20:37:39Z&read_before=2016-06-15T20:37:39Z

The response body will contain all the activity objects and any related resources, if requested via the include parameter.

{
  "activities": [
    {
      "id": 23901805,
      "workspace_id": 1,
      "account_id": 167693,
      "action": "complete",
      "target_id": 6113462,
      "target_type": "Task",
      "created_at": "2017-05-05T10:58:53-07:00",
      "updated_at": "2017-05-05T10:58:53-07:00",
      "payload": {
        "owner_id": 167693
      },
      "subscriber_ids": [
        22345,
        167693
      ],
      "recipient_ids": [
        22345
      ]
    }
  ],
  "tasks": [],
  "lists": [],
  "workspaces": []
}

Note: The related resources for the activities have been omitted in this example response for brevity.

Error Responses

HTTP 400 - Could not get records with the provided attributes. Check response for specific details.

Get Activity

GET /:id

Required Parameters

Parameter	Type	Description
`organization_id`	`Integer`

Optional Parameters

Parameter	Type	Description
`include`	`String`	Additionally return the given related resources. Supported values: `tasks` `lists` `workspaces`

Examples

Fetch a single activity

To get just a single activity record, just pass its ID and organization_id.

GET /v2/activites/23902125?organization_id=52

The response will contain the activity object, and have an HTTP 200 OK status.

If you provide resources in the include parameter, they will be included in the response alonside the activity.

{
  "activity": {
    "id": 23902125,
    "workspace_id": 1,
    "account_id": 22345,
    "action": "create",
    "target_id": 6113631,
    "target_type": "Task",
    "created_at": "2017-07-14T16:52:00-07:00",
    "updated_at": "2017-07-14T16:52:00-07:00",
    "payload": {
      "owner_id": 167693,
      "list_id": 628763,
      "list_name": "Test copy"
    },
    "subscriber_ids": [
      167693,
    22345
    ],
    "recipient_ids": [
      167693
    ]
  },
  "tasks": [],
  "lists": [],
  "workspaces": []
}

Note: the related resources in the response have been omitted for brevity.

Error Responses

HTTP 400 - Could not get record with the provided attributes. Check response for specific details.
HTTP 404 - The record could not be found.

Tasks

Base URL

Get Tasks

Required Parameters

Optional Parameters

Query Views

Examples

Get all tasks for a list

Error Responses

Get Task

Required Parameters

Optional Parameters

Examples

Fetch a task

Error Responses

Create Task

Required Parameters

Optional Parameters

Examples

Create a task

Error Responses

Update a Task

Required Parameters

Optional Parameters

Examples

Update a task's name

Error Responses

Comments

Base URL

Create Comment

Required Parameters

Examples

Post a comment

Error Responses

Update a Comment

Required Parameters

Optional Parameters

Examples

Update a comment

Error Responses

Delete a Comment

Required Parameters

Examples

Delete a comment

Error Responses

Lists

Base URL

Get Lists

Required Parameters

Optional Parameters

Examples

Get lists with their sections

Error Responses

Get List

Required Parameters

Optional Parameters

Examples

Get a List

Error Responses

Workspaces

Base URL

Get Workspaces

Required Parameters

Optional Parameters

Error Responses

Get a Workspace

Required Parameters

Optional Parameters

Error Responses

Memberships

Base URL

Get Memberships

Required Parameters

Optional Parameters

Examples

Get all memberships with accounts

Error Responses

Get a Membership

Required Parameters

Optional Parameters