Navbar

  • Tasks
  • Comments
  • Lists
  • Workspaces
  • Memberships
  • Webhooks
  • Access Tokens
  • Activities
  • 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

    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

    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.
    taskworkspace_id Integer Create resources under the given workspace.
    taskname String The title of the task.

    Optional Parameters

    Parameter Type Description
    taskowner_id Integer The ID of the account to whom this task will be assigned.
    tasklist_id Integer Put the new task in a list ("project"). Omit this param to have the task be private.
    taskstarts_on Date The date on which the task should start.
    taskdue_on Date The date on which the task should be due.
    taskmirror_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.
    taskmirror_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.
    tasknote_content String Provide the content for the task's note.
    tasknote_mime_type String Identify which markup language is used to format the given note

    Supported values:

    • text/plain
    • text/x-markdown
    • text/html
    taskparent_id Integer If provided, this task will become a subtask of the given task.
    taskposition_list Integer Determines the sort order when showing tasks in, or grouped by, a list.
    taskposition_owner Integer Currently unused.
    taskposition_upcoming Integer Determines the sort order when showing tasks grouped by their `due_date`.
    taskposition Integer Determines the sort order of tasks.
    tasksection_id Integer Specify which section under which to create this task.
    taskworkspace_id Integer Specify which workspace under which to create this task.
    tasksubscriptions Array An array of objects with an `account_id` key with the account ID to subscribe to the task.
    tasksubtasks 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
    tasktags 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

    Update a Task

    PUT /:id

    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 Query for resources under the given organization.
    taskworkspace_id Integer Query for resources under the given workspace.

    Optional Parameters

    Parameter Type Description
    taskcompleted Boolean If set to `true`, will complete the task.
    taskstarts_on Date The date on which the task should start.
    taskdue_on Date The date on which the task should be due.
    tasklist_id Integer Put the new task in a list ("project"). Omit this param to have the task be private.
    taskmirror_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.
    taskmirror_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.
    taskname String The title of the task.
    tasknote_content String Provide the content for the task's note.
    tasknote_mime_type String Identify which markup language is used to format the given note

    Supported values:

    • text/plain
    • text/x-markdown
    • text/html
    taskowner_id Integer The ID of the account to whom this task will be assigned.
    taskparent_id Integer If provided, this task will become a subtask of the given task.
    taskposition_list Integer Determines the sort order when showing tasks in, or grouped by, a list.
    taskposition_owner Integer Currently unused.
    taskposition_upcoming Integer Determines the sort order when showing tasks grouped by their `due_date`.
    taskposition Integer Determines the sort order of tasks.
    tasksection_id Integer Specify which section under which to move this task.
    tasksubscriber_ids Array An array of objects with an `account_id` key with the account ID to subscribe to the task.
    tasksubtasks 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
    tasktags 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

    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.
    commentbody String Content of the comment.
    commentmime_type String Identify which markup language is used to format the given comment.

    Supported values:

    • text/plain
    • text/x-markdown
    • text/html

    Examples

    Post a comment

    To create a comment, you will need a workspace_id, organization_id and the task_id. The new comment would be appear in that task's activity timeline.

    POST /v2/comments?workspace_id=941&task_id=5706881&organization_id=1200
    
    {
      "comment": {
        "body": "Get things done.",
        "mime_type": "text/x-markdown"
      }
    }
    

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

    {
        "comment": {
            "id": 1281164,
            "account_id": 123456,
            "task_id": 5706881,
            "body": "Get things done.",
            "created_at": "2017-07-28T11:35:11-07:00",
            "updated_at": "2017-07-28T11:35:11-07:00",
            "deleted": false,
            "mime_type": "text/x-markdown",
            "cid": null
        },
        "request_uuid": "5c389adb-e71f-4b29-87d4-72e549bcae4a"
    }
    

    Error Responses

    Update a Comment

    PUT /:id

    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 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.
    commentbody String Content of the comment.

    Optional Parameters

    Parameter Type Description
    commentmime_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

    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

    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

    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

    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

    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

    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

    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

    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_webhookname String A human-friendly name for your, and your teammates', reference.
    integration_webhookurl String The HTTP endpoint that will consume events from us.
    integration_webhookresource_type String The type of resource you are creating a webhook for.

    Supported values:

    • List
    • Task
    integration_webhookresource_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

    Update a webhook

    PUT /:id

    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 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

    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

    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_tokenname 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

    Revoke an Access Token

    DELETE /:id

    Error Responses

    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

    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

    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