NAV
shell

Introduction

Welcome to the Favro API! This page describes all endpoints and outgoing webhooks in the API. It is highly recommended to read the introductory sections regarding routing, pagination and rate limiting so that you are aware of the expected request headers.

If you have any problems or requests please contact support.

Authentication

The Favro API currently supports basic authentication with password or API tokens. In future versions, support for other forms of authentication such as OAuth2 tokens will be provided. Examples of how to authenticate with the API when making requests can be seen on all endpoint examples.

Tokens

As an alternative to using your password you can now use API tokens. They can be restricted to read-only endpoints and revoked at any time. You can generate API tokens from your user profile inside Favro.

curl -X GET "https://favro.com/api/v1/organizations" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"token"

Routing

Every response from the Favro REST API will include a header called X-Favro-Backend-Identifier. This is the unique identifier of the Favro server process that handled your request. If subsequent requests need to be routed to the same instance, you should include this identifier in the request header under the key X-Favro-Backend-Identifier. This is important, for example, when requesting the next page of a paginated response.

Pagination

Requests that return multiple items will be paginated to 100 items by default. The response for paginated requests will return in the response body the following information:

Name Description
requestId The requestId to be included in subsequent requests for further pages.
entities An array containing the entities returned for the given page.
page The index of the page that the entities returned belong to.
pages The total number of pages available.
limit The number of entities per page. This should always be 100.

It is important to note that since the results of paged requests are cached, if an entity that was returned by the original request is deleted in between calls, it will not be returned when requesting subsequent pages. Therefore, you might not always receive 100 items per page. In order to request subsequent pages for a paged response, you should include the following query parameters:

Name Description
requestId The requestId returned by the original request to the paged endpoint.
page The index of the page to request.

When requesting subsequent pages for paginated endpoints you must also include backend routing headers to ensure your request is handled by the same Favro server process.

Rate limiting

Rate limiting is applied on two levels - user level and organization level. User level routes are:

User level routes are rated limited at 50 calls per hour.

All other routes are considered organization routes. The API will reject calls to these routes that do not include in the headers an organizationId. For organization routes, the number of calls per hour depends on the payment plan of the organization.

Payment plan Number of calls per hour per user
Trial 100
Lite 0
Standard 1000
Enterprise 10000

All API calls will return information in the response headers about your current rate limit status:

Header name Description
X-RateLimit-Limt The maximum number of requests permitted to make per hour.
X-RateLimit-Remaining The number of requests remaining in the current rate limit window.
X-RateLimit-Reset The time at which the current rate limit window resets in UTC.

Errors

Favro uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP status code summary

Status Description
200 - OK Everything worked as expected (GET, PUT methods).
201 - Created The object was created (POST methods).
202 - Accepted The request has been accepted for processing, but the processing has not been completed (PUT methods).
204 - No Content The server successfully processed the request and is not returning any content (DELETE methods).
400 - Bad Request The request was not valid. This often occurs due to missing a required parameter.
401 - Unauthorized Similar to 403 - Access Denied, but specifically for use when authentication is required and has failed or has not yet been provided.
402 - Request Failed The parameters were valid but the request failed.
403 - Access Denied Incorrect credentials were supplied to perform the requested action.
404 - Not Found The requested resource doesn't exist.
429 - Too Many Requests Too many requests hit the API too quickly.
500 - Internal error There was an error with the Favro server.

Users

User

Field Type Description
userId string The id of the user.
name string The name of the user.
email string The main account email of the user.
organizationRole string The role of the user in the organization. Refer to organization roles.

Get all users

curl -X GET "https://favro.com/api/v1/users" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be an array of users.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "userId": "67973f72db34592d8fc96c48",
        "name": "Favro user",
        "email": "user@favro.com",
        "organizationRole": "administrator"
    }]
}

This endpoint retrieves a paginated list of all users in the organization.

HTTP Request

GET https://favro.com/api/v1/users

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Get a user

curl -X GET "https://favro.com/api/v1/users/:userId" \
    -u "user@example.com":"password"

The response returns a user object.

    {
        "userId": "67973f72db34592d8fc96c48",
        "name": "Favro user",
        "email": "user@favro.com",
        "organizationRole": "administrator"
    }

This endpoint retrieves a specific user.

HTTP Request

GET https://favro.com/api/v1/users/:userId

Query Parameters

Parameter Type Description
userId string The id of the user to be retrieved. Required.

Organizations

Organization

Field Type Description
organizationId string The id of the organization.
name string The name of the organization.
sharedToUsers array The users that are members of the organization. Refer to organization members.

Organization roles

Value Description
administrator Administrator/Owner of the organization. Has full control over the organization.
fullMember Full member of the organization.
externalMember External member of the organization. Not shared organization collections by default.
guest Guest user in the organization. A restricted user account.
disabled Disabled user in the organization.

Organization members

Field Type Description
userId string userId of the user in the organization.
role string The role of the user in the organization. Refer to organization roles.
joinDate date The date that this user was added to the organization.

Get all organizations

curl -X GET "https://favro.com/api/v1/organizations" \
    -u "user@example.com":"password"

The response will be an array of organizations.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "organizationId" : "67973f72db34592d8fc96c48",
        "name" : "My organization",
        "thumbnail": "https://favro.s3.eu-central-1.amazonaws.com/8989898989-698e-4b9f-9c5f-223c0d191ffe.png",
        "sharedToUsers": [{
            "userId" : "fB6bJr5TbaKLiofns",
            "role" : "administrator",
            "joinDate" : "2016-02-10T14:25:58.745Z"
        }]
    }]
}

This endpoint retrieves a paginated list of all organizations shared to the user making the request.

HTTP Request

GET https://favro.com/api/v1/organizations

Get an organization

curl -X GET "https://favro.com/api/v1/organizations/:id" \
    -H "organizationId: 67973f72db34592d8fc96c48" \
    -u "user@example.com":"password"

The response returns an organization object.

    {
        "organizationId" : "67973f72db34592d8fc96c48",
        "name" : "My organization",
        "thumbnail": "https://favro.s3.eu-central-1.amazonaws.com/8989898989-698e-4b9f-9c5f-223c0d191ffe.png",
        "sharedToUsers": [{
            "userId" : "fB6bJr5TbaKLiofns",
            "role" : "administrator",
            "joinDate" : "2016-02-10T14:25:58.745Z"
        }]
    }

This endpoint retrieves a specific organization.

HTTP Request

GET https://favro.com/api/v1/organizations/:organizationId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Query Parameters

Parameter Type Description
organizationId string The id of the organization to be retrieved. Required.

Create an organization

curl -X POST "https://favro.com/api/v1/organizations" \
    -d '{
        "name": "My organization",
        "shareToUsers": [{
            "userId": "fB6bJr5TbaKLiofns",
            "role": "administrator"
        }]
    }' \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created organization.

    {
        "organizationId" : "67973f72db34592d8fc96c48",
        "name" : "My organization",
        "thumbnail": "https://favro.s3.eu-central-1.amazonaws.com/8989898989-698e-4b9f-9c5f-223c0d191ffe.png",
        "sharedToUsers": [{
            "userId" : "fB6bJr5TbaKLiofns",
            "role" : "administrator",
            "joinDate" : "2016-02-10T14:25:58.745Z"
        }]
    }

This endpoint creates a new organization.

HTTP Request

POST https://favro.com/api/v1/organizations

Request Parameters

Parameter Type Description
name string The name of the organization
shareToUsers array The users who will be invited to the organization. See below for a description of a user share object.

Organization user share object parameters

Field Type Description
userId string The userId of the existing user. Required if email is not provided.
email string Email. Required if userId is not provided.
role string The role of the user in the organization. Refer to organization roles. Required.

Update an organization

curl -X PUT "https://favro.com/api/v1/organizations/67973f72db34592d8fc96c48" \
    -d '{
        "name": "My organization",
        "shareToUsers": [{
            "userId": "fB6bJr5TbaKLiofns",
            "role": "administrator"
        }]
    }' \
    -H "organizationId: 67973f72db34592d8fc96c48" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated organization.

    {
        "organizationId" : "67973f72db34592d8fc96c48",
        "name" : "My organization",
        "thumbnail": "https://favro.s3.eu-central-1.amazonaws.com/8989898989-698e-4b9f-9c5f-223c0d191ffe.png",
        "sharedToUsers": [{
            "userId" : "fB6bJr5TbaKLiofns",
            "role" : "administrator",
            "joinDate" : "2016-02-10T14:25:58.745Z"
        }]
    }

This endpoint updates an existing organization.

HTTP Request

PUT https://favro.com/api/v1/organizations/:organizationId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
organizationId string The id of the organization to update.
name string The name of the organization
members array Update user roles in the organization. See below for a description of a user share object.
shareToUsers array The users who will be invited to the organization. See below for a description of a user share object.

Organization user share object parameters

Field Type Description
userId string The userId of the existing user. Required if email is not provided.
email string Email. Required if userId is not provided.
delete boolean Removes user from the organization if value equals to true. Optional.
role string The role of the user in the organization. Refer to organization roles. Required if delete is not provided.

Collections

Collection

Field Type Description
collectionId string The id of the collection.
organizationId string The id of the organization that this collection exists in.
name string The name of the collection.
sharedToUsers array The array of collection members that the collection is shared to.
publicSharing string The collection public sharing level.
background string The collection background.
archived boolean Whether or not the collection is archived.
fullMembersCanAddWidgets boolean Whether or not full members shared this collection can create new widgets.

Collection background

Value
purple
green
grape
red
pink
blue
solidPurple
solidGreen
solidGrape
solidRed
solidPink
solidGray

Collection public sharing

Value Description
users Specific users only.
organization All members of the organization.
public Everyone on the Internet.

Collection roles

Value Description
guest Guest user.
view User with view rights.
edit User with edit rights.
admin User with admin rights.

Collection members

Field Type Description
userId string userId.
role string See collection roles.

Get all collections

curl -X GET "https://favro.com/api/v1/collections" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated list of collections.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "collectionId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "name": "My collection",
        "sharedToUsers": [{
            "userId": "ff440e8f358c08513a86c8d6",
            "role": "admin"
        }],
        "publicSharing": "users",
        "background": "purple",
        "archived": false,
        "widgetCommonId": "cf8212b085aacb60e0df0370"
    }]
}

This endpoint retrieves a paginated list of all collections shared to the user making the request.

HTTP Request

GET https://favro.com/api/v1/collections

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
archived boolean If true, return archived collections. Optional.

Get a collection

curl -X GET "https://favro.com/api/v1/collections/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns a collection object.

    {
        "collectionId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "name": "My collection",
        "sharedToUsers": [{
            "userId": "ff440e8f358c08513a86c8d6",
            "role": "admin"
        }],
        "publicSharing": "users",
        "background": "purple",
        "archived": false,
        "widgetCommonId": "cf8212b085aacb60e0df0370"
    }

This endpoint retrieves a specific collection.

HTTP Request

GET https://favro.com/api/v1/collections/:collectionId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
collectionId string The id of the collection to be retrieved. Required.

Create a collection

curl -X POST "https://favro.com/api/v1/collections" \
    -d '{
        "name": "My collection",
        "starPage": true,
        "publicSharing": "users",
        "type": "backlog",
        "shareToUsers": [{
            "userId": "vMyM9DWeYc2wGx7Wq",
            "role": "admin"
        }]
    }' \
    -H "organizationId: e80e09146bd7cb2cd33bf935" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created collection.

    {
        "collectionId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "name": "My collection",
        "sharedToUsers": [{
            "userId": "ff440e8f358c08513a86c8d6",
            "role": "admin"
        }],
        "publicSharing": "users",
        "background": "purple",
        "archived": false,
        "widgetCommonId": "cf8212b085aacb60e0df0370"
    }

This endpoint creates a new collection.

HTTP Request

POST https://favro.com/api/v1/collections

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
name string The name of the collection. Required.
starPage boolean Star the collection for authorized user. Defaults to false.
publicSharing string Public share role for the collection. Refer to collection public sharing.
shareToUsers array The users who will be invited to the collection. See below for a description of a user share object.
background string The background color of the collection. Refer to collection background.
fullMembersCanAddWidgets boolean Whether or not full members shared this collection can create new widgets. Defaults to true.

Collection user share object parameters

Field Type Description
userId string The userId of the existing user. Required if email is not provided.
email string Email. Required if userId is not provided.
role string The role of the user in the collection. Refer to collection roles. Required.

Update a collection

curl -X PUT "https://favro.com/api/v1/collections/67973f72db34592d8fc96c48" \
    -d '{
        "name": "My collection",
        "starPage": true,
        "publicSharing": "organization",
        "background": "purple",
        "members": [{
            "userId": "ff440e8f358c08513a86c8d6",
            "role": "admin"
        }]
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated collection.

    {
        "collectionId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "name": "My collection",
        "sharedToUsers": [{
            "userId": "ff440e8f358c08513a86c8d6",
            "role": "admin"
        }],
        "publicSharing": "users",
        "background": "purple",
        "archived": false,
        "widgetCommonId": "cf8212b085aacb60e0df0370"
    }

This endpoint updates an existing collection.

HTTP Request

PUT https://favro.com/api/v1/collections/:collectionId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
name string The name of the collection.
starPage boolean Star the collection for authorized user.
publicSharing number Public share role for the collection. See below for a description of an collection public sharing.
background number Collection background. See collection background.
members array Update user roles in the collection. See below for a description of a user share object.
shareToUsers array The users who will be invited to the collection. See below for a description of a user share object.
fullMembersCanAddWidgets boolean Whether or not full members shared this collection can create new widgets. Defaults to true.
archive boolean Archive or unarchive collection.

Collection user share object parameters

Field Type Description
userId string The userId of the existing user. Required if email is not provided.
email string Email. Required if userId is not provided.
delete boolean Removes user from the collection if value equals to true. Optional.
role string The role of the user in the collection. Refer to collection roles. Required if delete is not provided.

Delete a collection

curl -X DELETE "https://favro.com/api/v1/collections/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This endpoint deletes a specific collection.

HTTP Request

DELETE https://favro.com/api/v1/collections/:collectionId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
collectionId string The id of the collection to be deleted. Required.

Widgets

Widget

Field Type Description
widgetCommonId string The shared id of the widget.
organizationId string The id of the organization that this widget exists in.
collectionIds array The ids of the collections that this widget exists in. This array will only contain collections that the user has access to.
name string The name of the widget.
type string The type of the widget. Refer to widget types.
breakdownCardCommonId string If set, this means that this widget is a breakdown of a card.
color string The color of the widget icon. Refer to widget colors.
ownerRole string The users that have ownership of the widget. Refer to widget roles.
editRole string The users that can add, edit and move cards on the widget. Refer to widget roles.

Widget types

Value Description
backlog Left-pane widget is considered a "backlog". Defaults to card list view.
board Right-pane widget is considered a "board". Defaults to Kanban view.

Widget roles

Value Description
owners Only the owners of the collection(s) that the widget is on.
fullMembers All full members in the organization.
guests All full members & guests in the organization. This value is not valid for the ownerRole.

Widget colors

Value
blue
lightgreen
brown
purple
orange
yellow
gray
red
cyan
green

Get all widgets

curl -X GET "https://favro.com/api/v1/widgets" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated array of widgets.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false,
        "lanes": [
            {
                laneId: "1dd704ad8cee4eed2b89f917",
                name: "Not main lane"
            },
            {
                laneId: "4360cdf5be3d42b679e74422",
                name: "Main lane"
            }
        ],
        "columns": [
            {
                "columnId": "1360cdf5be3d42b679e74422",
                "name": "To do",
                "color": "gray"
            },
            {
                "columnId": "2360cdf5be3d42b679e74422",
                "name": "Doing",
                "color": "orange"
            },
            {
                "columnId": "3360cdf5be3d42b679e74422",
                "name": "Done",
                "color": "green"
            }
        ]
    }]
}

This endpoint retrieves a paginated list of all widgets shared to the user making the request.

HTTP Request

GET https://favro.com/api/v1/widgets

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
collectionId string The id of the collection to filter by. Optional.
archived boolean If true, return archived widgets. Optional.

Get a widget

curl -X GET "https://favro.com/api/v1/widgets/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns a widget object.

    {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false,
        "lanes": [
            {
                laneId: "1dd704ad8cee4eed2b89f917",
                name: "Not main lane"
            },
            {
                laneId: "4360cdf5be3d42b679e74422",
                name: "Main lane"
            }
        ],
        "columns": [
            {
                "columnId": "1360cdf5be3d42b679e74422",
                "name": "To do",
                "color": "gray"
            },
            {
                "columnId": "2360cdf5be3d42b679e74422",
                "name": "Doing",
                "color": "orange"
            },
            {
                "columnId": "3360cdf5be3d42b679e74422",
                "name": "Done",
                "color": "green"
            }
        ]
    }

This endpoint retrieves a specific widget.

HTTP Request

GET https://favro.com/api/v1/widgets/:widgetCommonId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
widgetCommonId string The id of the widget to be retrieved.

Create a widget

curl -X POST "https://favro.com/api/v1/widgets" \
    -d '{
        "collectionId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a widget",
        "type": "board",
        "color": "blue",
        "ownerRole": "fullMembers",
        "editRole": "guests"
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created widget.

    {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false,
        "lanes": [
            {
                laneId: "1dd704ad8cee4eed2b89f917",
                name: "Not main lane"
            },
            {
                laneId: "4360cdf5be3d42b679e74422",
                name: "Main lane"
            }
        ],
        "columns": [
            {
                "columnId": "1360cdf5be3d42b679e74422",
                "name": "To do",
                "color": "gray"
            },
            {
                "columnId": "2360cdf5be3d42b679e74422",
                "name": "Doing",
                "color": "orange"
            },
            {
                "columnId": "3360cdf5be3d42b679e74422",
                "name": "Done",
                "color": "green"
            }
        ]
    }

This endpoint creates a new widget.

HTTP Request

POST https://favro.com/api/v1/widgets

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
collectionId string The collectionId of the collection to create the widget in. Required.
name string The name of the widget. Required.
type string The type of widget to create. Refer to widget types. Required.
color string The color of the widget icon. Refer to widget colors.
ownerRole string The users that have ownership of the widget. Defaults to "fullMembers". Refer to widget roles.
editRole string The users that can add, edit and move cards on the widget. Defaults to "guests". Refer to widget roles.

Update a widget

curl -X PUT "https://favro.com/api/v1/widgets/67973f72db34592d8fc96c48" \
    -d '{
        "name": "This is a widget",
        "color": "blue",
        "ownerRole": "fullMember",
        "editRole": "guest"
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated widget.

    {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false,
        "lanes": [
            {
                laneId: "1dd704ad8cee4eed2b89f917",
                name: "Not main lane"
            },
            {
                laneId: "4360cdf5be3d42b679e74422",
                name: "Main lane"
            }
        ],
        "columns": [
            {
                "columnId": "1360cdf5be3d42b679e74422",
                "name": "To do",
                "color": "gray"
            },
            {
                "columnId": "2360cdf5be3d42b679e74422",
                "name": "Doing",
                "color": "orange"
            },
            {
                "columnId": "3360cdf5be3d42b679e74422",
                "name": "Done",
                "color": "green"
            }
        ]
    }

This endpoint updates an existing widget.

HTTP Request

PUT https://favro.com/api/v1/widgets/:widgetCommonId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
widgetCommonId string The common id of the widget to update. Required.
name string The name of the widget.
archive boolean Archive or unarchive widget. Requires collectionId to be specified in the request.
collectionId string The id of the collection where widget will be archived. Required if archive is included in the request.
color string The color of the widget icon. Refer to widget colors.
ownerRole string The users that have ownership of the widget. Defaults to "fullMembers". Refer to widget roles.
editRole string The users that can add, edit and move cards on the widget. Defaults to "guests". Refer to widget roles.

Delete a widget

curl -X DELETE "https://favro.com/api/v1/widgets/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This endpoint deletes a specific widget. Deleting a widget will also delete any columns, card or comments that exist on the widget.

HTTP Request

DELETE https://favro.com/api/v1/widgets/:widgetCommonId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
widgetCommonId string The common id of the widget to be deleted. Required.
collectionId string The id of collection where widget will be deleted. Optional. If ommitted all instances of the widget will be deleted.

Columns

Column object

Field Type Description
columnId string The id of the column.
organizationId string The id of the organization that this column exists in.
widgetCommonId string The common id of the widget that this column exists on.
name string The name of the column.
position number The position of the column on the widget.
cardCount number Total number of cards on the column.
timeSum number Summary time spent of cards on the column in milisecond.
estimationSum number Summary estimation of cards on the column.

Get all columns

curl -X GET "https://favro.com/api/v1/columns?widgetCommonId=ff440e8f358c08513a86c8d6" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated array of columns.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "columnId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "name": "This is a column",
        "position": 0,
        "cardCount": 3,
        "timeSum": 609111150,
        "estimationSum": 22
    }]
}

This endpoint retrieves a paginated list of all columns that exist on the specified widget.

HTTP Request

GET https://favro.com/api/v1/columns

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
widgetCommonId string The common id of the widget to filter by. Required.

Get a column

curl -X GET "https://favro.com/api/v1/columns/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns a column object.

    {
        "columnId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "name": "This is a column",
        "position": 0,
        "cardCount": 3,
        "timeSum": 609111150,
        "estimationSum": 22
    }

This endpoint retrieves a specific column.

HTTP Request

GET https://favro.com/api/v1/columns/:columnId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
columnId string The id of the column to be retrieved.

Create a column

curl -X POST "https://favro.com/api/v1/columns" \
    -d '{
        "name": "This is a column",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "position": 1
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created column.

    {
        "columnId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "name": "This is a column",
        "position": 0,
        "cardCount": 3,
        "timeSum": 609111150,
        "estimationSum": 22
    }

This endpoint creates a new column. Columns can only be created on board widgets.

HTTP Request

POST https://favro.com/api/v1/columns

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
widgetCommonId string The widgetCommonId to create the column on. Required.
name string The name of the column. Required.
position number The position of the column on the widget. By default the column will be placed at the end of the widget. Optional.

Update a column

curl -X PUT "https://favro.com/api/v1/columns/67973f72db34592d8fc96c48" \
    -d '{
        "name": "This is a column",
        "position": 1
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated column.

    {
        "columnId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "name": "This is a column",
        "position": 0,
        "cardCount": 3,
        "timeSum": 609111150,
        "estimationSum": 22
    }

This endpoint updates an existing column.

HTTP Request

PUT https://favro.com/api/v1/columns/:columnId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
columnId string The id of the column to update.
name string The name of the column.
position number The position of the column.

Delete a column

curl -X DELETE "https://favro.com/api/v1/columns/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This endpoint deletes a specific column. Deleting a column will also delete any cards that exist within that column.

HTTP Request

DELETE https://favro.com/api/v1/columns/:columnId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
columnId The id of the column to be deleted. Required.

Cards

In Favro, a card can exist on multiple widgets. As a result of this, a card contains a cardCommonId that is the shared id for all instances of this card. When the API and webhooks return card objects, they will optionally contain the following fields:

Card

Field Type Description
cardId string The id of the card.
organizationId string The id of the organization that this card exists in.
widgetCommonId string The shared id of the widget that this card exists on. Only returned if the card does not exist in a todo list.
todoListUserId string The user id of the user of the todo list that this card exists in. Only returned if the card exists in a todo list. Otherwise widgetCommonId will be returned.
todoListCompleted boolean Returns 'true' if the card exists in a todo list and has been completed by that user.
columnId string The id of the Kanban column that this card exists in. Only returned if the card exists on a widget.
laneId string The id of the lane that this card exists in. Only returned if the card exists on a widget and the widget has lanes enabled.
parentCardId string The id of the parent card in the card hierarchy (sheet or card list). Only returned if the card exists in a widget and is the child of another card.
isLane boolean Returns 'true' if the card is a lane.
archived boolean Returns 'true' if the card is archived.
position number Deprecated. Mapped to listPosition for right-pane widgets, and to sheetPosition for left-pane widgets.
listPosition number Position of the card in a column on a Kanban board, or in a todo list.
sheetPosition number Position of the card in a hierarchical view (sheet or card list).
cardCommonId string A shared id for all instances of this card in the organization.
name string The name of the card.
detailedDescription string The detailed description of the card.
tags array The tags that are set on the card.
sequentialId number The sequentialId of the card. Useful for creating human readable links.
startDate date The start date of the card.
dueDate date The due date of the card.
assignments array The users assigned to the card and whether or not they have completed the card. See below for a description of a card assignment.
numComments number The number of comments posted on the card.
tasksTotal number The number of tasks on the card.
tasksDone number The number of tasks completed on the card.
attachments array The file attachments on the card. See attachments.
dependencies array The list of card dependencies of the card. See Card dependency.
customFields array The custom fields that are set on the card and enabled in the organization. See card custom fields.
timeOnBoard object The amount of time card has been on current board. See Card time on board
timeOnColumns object The detailed summary of time card has been on each column of the current board. The object key represents the columnId of the column, and the value is the amount of time card has been on that column.
favroAttachments array The Favro attachments on the card. See card favro attachment.

Card assignment

Field Type Description
userId string The user assigned to the card.
completed boolean Returns 'true' if the user has completed the card.

Card task

Field Type Description
name string The name of task.
completed boolean The feature makes task completed or uncompleted. False by default.

Card tasklist

Field Type Description
name string The name of tasklist.
tasks array The list of tasks (look at card task) or tasknames.

Card tag

Field Type Description
name string The name of the tag.
color string The color of the tag. Refer to tag colors.

Card custom fields

Field Type Description
customFieldId string The id of the custom field.
value The value of the custom field. The type of this field is dependent on the type of the custom field. Refer to the custom field types.

Card formatting

Syntax Meaning
*italic* italic
**bold** bold
` ` `code block` ` ` code block
[Link](http://localhost) Link

Card time on board

Field Type Description
time number Total time card has been on current board.
isStopped boolean Indicate either card was archived or reached the final column on current board.

Card dependency

Field Type Description
cardId string The cardId of card that is a dependency.
cardCommonId string The cardCommonId of card that is a dependency.
isBefore boolean Indicates if the dependency is before this card.
reverseCardId string The cardId of this instance.

Card dependency options

Field Type Description
cardId string The cardId of the dependency card.
isBefore boolean Indicates if the dependency is before this card.

Card favro attachment

Field Type Description
itemCommonId string The cardCommonId of card or widgetCommonId of widget that is linked to the card.
type string Type of item that is linked to the card. One of [card, backlog, board].

Card custom field parameters

Number custom field parameters

Field Type Description
customFieldId string The id of the custom field.
total number The total value of the field.

Text custom field parameters

Field Type Description
customFieldId string The id of the custom field.
value string The value of the field.

Members custom field parameter

Field Type Description
customFieldId string The id of the custom field.
members object The options that include lists of user ids to set for the custom field. See custom field members.

Tags custom field parameter

Field Type Description
customFieldId string The id of the custom field.
tags object The options that include lists of tag names or ids to set for the custom field. See custom field tags.

Status / Multiple select custom field parameter

Field Type Description
customFieldId string The id of the custom field.
value array The list of selectable item id of this custom field, see custom field item object.

Time custom field parameters

Field Type Description
customFieldId string The id of the custom field. Required.
addUserReports object The user report to be added. See custom field time user reports. Optional.
updateUserReports object The user report to be updated. See custom field time user reports. Optional.
removeUserReports object The user report to be removed. See custom field time user reports. Optional.

Color custom field parameters

Field Type Description
customFieldId string The id of the custom field.
color string The color to set the card to. See custom field card colors. Use an empty string to clear the value.

Rating custom field parameters

Field Type Description
customFieldId string The id of the custom field.
total number The value of the field. Valid value is integer from 0 to 5.

Vote custom field parameters

Field Type Description
customFieldId string The id of the custom field.
value boolean The value to determine the field should be either voted or unvoted.

Checkbox custom field parameters

Field Type Description
customFieldId string The id of the custom field.
value boolean The value of the field.

Date custom field parameters

Field Type Description
customFieldId string The id of the custom field.
value string The date value in string format.

Timeline custom field parameters

Field Type Description
customFieldId string The id of the custom field.
timeline object The value options of the field. See custom field timeline.
Field Type Description
customFieldId string The id of the custom field.
link object The value options of the field. See custom field link.

Get all cards

curl -X GET "https://favro.com/api/v1/cards?widgetCommonId=ff440e8f358c08513a86c8d6" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated array of cards.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    }]
}

This endpoint retrieves a paginated list of all cards shared to the user making the request.

HTTP Request

GET https://favro.com/api/v1/cards

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type In Description
todoList boolean query Return cards from todolist only. Defaults to false.
cardCommonId string query The common id of the card to filter by.
cardSequentialId string query The sequential id of the card to be retrieved.
widgetCommonId string query The common id of the widget to filter by.
columnId string query The id of the column to filter by.
collectionId string query The id of the collection to filter by.
unique boolean query If true, return unique cards only. Defaults to false.
archived boolean query If true, return archived cards.
descriptionFormat string query The format of the card description in response. Supported formats: plaintext, markdown. Default value: plaintext.

In order to use this endpoint you must specify either todoList or one of cardCommonId, cardSequentialId, widgetCommonId or collectionId.

Get a card

curl -X GET "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns a card object.

    {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    }

This endpoint retrieves a specific card.

HTTP Request

GET https://favro.com/api/v1/cards/:cardId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type In Description
cardId string path The id of the card to be retrieved. Required.
descriptionFormat string query The format of the card description in response. Supported formats: markdown, plaintext. Default value: plaintext. Optional.

Create a card

curl -X POST "https://favro.com/api/v1/cards" \
    -d '{
        "name": "This is a card",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "addUserReports": [{
                "value": 50400000
            }]
        }]
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created card.

    {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    }

This endpoint creates a new card.

HTTP Request

POST https://favro.com/api/v1/cards

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type In Description
widgetCommonId string body The widgetCommonId to create the card on. If not set, the card will be created in the user's todo list.
laneId string body The laneId to create the card in. This is only applicable if creating the card on a widget that has lanes enabled. Optional.
columnId string body The columnId to create the card in. It must belong to the widget specified in the widgetCommonId parameter. WidgetCommonId is required if this parameter is set.
parentCardId string body The id of the parent card in the card hierarchy (sheet or card list). It must belong to the widget specified in the widgetCommonId parameter.
name string body The name of the card. Required.
detailedDescription string body The detailed description of the card. Supports formatting.
dependencies array body The list of the card dependency options for a card.
position number body Deprecated. Mapped to listPosition for right-pane widgets, and to sheetPosition for left-pane widgets. Optional.
listPosition number body New position of the card in a column on a Kanban board, or in a todo list. Optional.
sheetPosition number body New position of the card in a hierarchical view (sheet or card list). Optional.
assignmentIds array body The list of assignments (array of userIds). Optional.
tags array body The list of tag names or card tags that will be added to card. If current tag is not exist in the organization, it will be created.
tagIds array body The list of tag IDs, that will be added to card. Optional.
startDate string body The start date of card. Format ISO-8601. Optional.
dueDate string body The due date of card. Format ISO-8601. Optional.
tasklists array body The list of card tasklists. Optional.
customFields array body The list of card custom field parameters. Optional.
descriptionFormat string query The format of the card description in response. Supported formats: plaintext, markdown. Default value: plaintext. Optional.

Update a card

curl -X PUT "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48" \
    -d '{
        "name": "This is a card",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "updateUserReports": [{
                "reportId": "29ed6478b55f90d91c5f4727",
                "value": 50400000
            }],
            "removeUserReports": [{
                "reportId": "29ed6478b55f90d91c5f4728"
            }]
        }]
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated card.

    {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    }

This endpoint updates an existing card. It can also be used to commit a card to another widget by specifying widgetCommonId. See the request parameters for more information.

HTTP Request

PUT https://favro.com/api/v1/cards/:cardId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type In Description
cardId string path The id of the card to update. Required.
name string body The name of the card.
detailedDescription string body The detailed description of the card. Supports formatting.
widgetCommonId string body The widgetCommonId to commit the card in. Optional.
laneId string body The laneId to commit the card in. This is only applicable if creating the card on a widget that has lanes enabled. Optional.
columnId string body The columnId to commit the card in. It must belong to the widget specified in the widgetCommonId parameter. Optional.
parentCardId string body The id of the parent card in the card hierarchy (sheet or card list), where the card will be commited. It must belong to the widget specified in the widgetCommonId parameter. Optional.
dragMode string body 'commit' to commit card, 'move' to move card. 'commit' by default.
position number body Deprecated. Mapped to listPosition for right-pane widgets, and to sheetPosition for left-pane widgets. Optional.
listPosition number body New position of the card in a column on a Kanban board, or in a todo list. Optional.
sheetPosition number body New position of the card in a hierarchical view (sheet or card list). Optional.
addAssignmentIds array body The list of assignments, that will be added to card (array of userIds). Optional.
removeAssignmentIds array body The list of assignments, that will be removed from card (array of userIds). Optional.
completeAssignments array body The list of card assignment, that will update their statuses accordingly. Optional.
addTags array body The list of tag names or card tags that will be added to the card. If the tag does not exist in the organization it will be created. Optional.
addTagIds array body The list of tagIds that will be added to the card. Optional.
addDependencies array body The list of card dependency options that will be added to the card. Optional.
removeDependencies array body The list of dependency card ids that will be removed from the card. Optional.
removeTags array body The list of tag names, that will be removed from card. Optional.
removeTagIds array body The list of tag IDs, that will be removed from card. Optional.
startDate string body The start date of card. Format ISO-8601. If null, start date will be removed. Optional.
dueDate string body The due date of card. Format ISO-8601. If null, due date will be removed. Optional.
addTasklists array body The list of card tasklists, that will be added to card. Optional.
removeAttachments array body The list of attachments URLs, that will be removed from the card. Optional.
customFields array body The list of card custom field parameters, that will be added or modified. Optional.
addFavroAttachments array body The list of card favro attachment that will be added to the card. Optional.
removeFavroAttachmentIds array body The list of cardCommonId and widgetCommonId of card favro attachment, that will be removed from the card. Optional.
archive boolean body Archive or unarchive card. Optional.
descriptionFormat string query The format of the card description in response. Supported formats: plaintext, markdown. Default value: plaintext. Optional.

Delete a card

curl -X DELETE "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns an array of cardIds for the cards that were deleted.

[
    "67973f72db34592d8fc96c48",
    "67973f72db34592d8fc96c49",
    "67973f72db34592d8fc96c50"
]

This endpoint deletes a specific card.

HTTP Request

DELETE https://favro.com/api/v1/cards/:cardId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
cardId string The id of card to be deleted. Required.
everywhere boolean If true, all copies of card will be deleted too. Defaults to false.

Dependencies

Get all dependencies

curl -X GET "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48/dependencies" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be all the dependencies of the card

{
    "cardId": "67973f72db34592d8fc96c48",
    "cardCommonId": "ff440e8f358c08513a86c8d6",
    "organizationId": "zk4CJpg5uozhL4R2W",
    "dependencies": [{
        "cardId": "eRryDkeAwojKHXBML",
        "cardCommonKey": "ff440e8f358c08513a86c8d6,
        "isBefore": true,
        "reverseCardId": "67973f72db34592d8fc96c48"
    }]
}

This endpoint retrieves all the dependencies of a card.

HTTP Request

GET https://favro.com/api/v1/cards/:cardId/dependencies

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Query Parameters

Parameter Type Description
cardId string The id of the card whose dependencies are to be retrieved.

Create dependencies

curl -X POST "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48/dependencies" \
    -d '{
        "dependencies": [{
            "cardId": "eRryDkeAwojKHXBML",
            "isBefore": false
        }]
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated list of dependencies of the card

{
    "cardId": "67973f72db34592d8fc96c48",
    "cardCommonId": "ff440e8f358c08513a86c8d6",
    "organizationId": "zk4CJpg5uozhL4R2W",
    "dependencies": [{
        "cardId": "eRryDkeAwojKHXBML",
        "cardCommonKey": "ff440e8f358c08513a86c8d6,
        "isBefore": true,
        "reverseCardId": "67973f72db34592d8fc96c48"
    }]
}

This endpoint adds new dependencies to a card.

HTTP Request

POST https://favro.com/api/v1/cards/:cardId/dependencies

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Query Parameters

Parameter Type Description
cardId string The id of the card whose dependencies are to be updated.

Request Parameters

Parameter Type Description
dependencies array The list of card dependency options to be added.

Update dependencies

curl -X PUT "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48/dependencies" \
    -d '{
        "dependencies": [{
            "cardId": "eRryDkeAwojKHXBML",
            "isBefore": false
        }]
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated list of dependencies of the card

{
    "cardId": "67973f72db34592d8fc96c48",
    "cardCommonId": "ff440e8f358c08513a86c8d6",
    "organizationId": "zk4CJpg5uozhL4R2W",
    "dependencies": [{
        "cardId": "eRryDkeAwojKHXBML",
        "cardCommonKey": "ff440e8f358c08513a86c8d6,
        "isBefore": true,
        "reverseCardId": "67973f72db34592d8fc96c48"
    }]
}

This endpoint removes all previous dependencies and sets the new dependencies to a card.

HTTP Request

PUT https://favro.com/api/v1/cards/:cardId/dependencies

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Query Parameters

Parameter Type Description
cardId string The id of the card whose dependencies are to be set.

Request Parameters

Parameter Type Description
dependencies array The list of card dependency options to be set.

Update a card dependency

curl -X PATCH "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48/dependencies/eRryDkeAwojKHXBML" \
    -d '{
        "isBefore": true
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated list of dependencies of the card

{
    "cardId": "67973f72db34592d8fc96c48",
    "cardCommonId": "ff440e8f358c08513a86c8d6",
    "organizationId": "zk4CJpg5uozhL4R2W",
    "dependencies": [{
        "cardId": "eRryDkeAwojKHXBML",
        "cardCommonKey": "ff440e8f358c08513a86c8d6,
        "isBefore": true,
        "reverseCardId": "67973f72db34592d8fc96c48"
    }]
}

This endpoint updates a specific dependency of a card

HTTP Request

PATCH https://favro.com/api/v1/cards/:cardId/dependencies/:dependencyCardId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Query Parameters

Parameter Type Description
cardId string The id of the card whose dependency is to be updated.
dependencyCardId string The card id of the dependency to be updated.

Request Parameters

Parameter Type Description
isBefore boolean Indicates if the dependency card has a before dependency to the queried card. Optional.

Delete a card dependency

curl -X DELETE "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48/dependencies/jKHXBMLeRryDkeAwo" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

This endpoint deletes a concrete card dependency.

HTTP Request

DELETE https://favro.com/api/v1/cards/:cardId/dependencies/:dependencyCardId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Query Parameters

Parameter Type Description
cardId string The id of the card whose dependencies are to be deleted.
dependencyCardId string The cardId of the dependency to be deleted.

Delete all dependencies

curl -X DELETE "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48/dependencies" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This endpoint deletes all the dependencies of a card.

HTTP Request

DELETE https://favro.com/api/v1/cards/:cardId/dependencies

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Query Parameters

Parameter Type Description
cardId string The id of the card whose dependencies are to be deleted.

Activities

Activity object

Field Type Description
type string Type of activity.
source string Category of activity. News, follow or news and follow.
cardId string The id of the card.
cardCommonId string The common id of the card.
cardName string The name of the card.
organizationId string The id of the organization that this card exists in.
widgetCommonId string The shared id of the widget that this card exists in. Only returned if the card activity is related to widget.
widgetName string The name of the widget that card that this card exists in. Only returned if the card activity is related to widget.
columnId string The id of the column that this card exists in. Only returned if the card activity is related to column.
columnName string The name of the column that this card exists in. Only returned if the card activity is related to column.
customFieldName string The name of the custom field. Only returned if the card activity is related to custom field.
customFieldValue string The value of the custom field. Only returned if the card activity is related to custom field.
taskName string The name of the task. Only returned if the card activity is related to task.
commentId string The id of the comment. Only returned if the card activity is related to comment.
time date The time activity occur.
byUserId string Id of user who made the action.

Get card activities

curl -X GET "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48/activities" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated array of activities.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "type": "assigned",
        "source": "follow",
        "cardId": "5ecbd2ac95242afcad238f5f",
        "cardCommonKey": "2ff0b9a3600eaf676757853b",
        "cardName": "This is a card",
        "organizationId": "b4534186ffe9dddeb97fdfa4",
        "time": "2018-05-15T06:27:12.466Z",
        "byUserId": "jeb4q8sPf67YwX7po"
    }]
}

This endpoint retrieves a paginated list of all activities of card to the user making the request.

HTTP Request

GET https://favro.com/api/v1/cards/:cardId/activities

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
since date Filter activities occur after since date. Format ISO-8601. Optional.
until date Filter activities occur before until date. Format ISO-8601. Optional.

Tags

Tag

Field Type Description
tagId string The id of the tag.
organizationId string The id of the organization that the tag belongs to.
name string The name of the tag.
color string The color of the tag. Refer to tag colors.

Tag colors

Value
blue
purple
cyan
green
lightgreen
yellow
orange
red
brown
gray
slategray

Get all tags

curl -X GET "https://favro.com/api/v1/tags" \
    -d name="Tag" \
    -d color="red" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated array of tags.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "tagId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "name": "My tag",
        "color": "purple"
    }]
}

This endpoint retrieves a paginated list of all tags that match the specified parameters.

HTTP Request

GET https://favro.com/api/v1/tags

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
name string The name of the tag to filter by. Optional.

Get a tag

curl -X GET "https://favro.com/api/v1/tags/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns a tag object.

    {
        "tagId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "name": "My tag",
        "color": "purple"
    }

This endpoint retrieves a specific tag.

HTTP Request

GET https://favro.com/api/v1/tags/:tagId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
tagId string The id of the tag to be retrieved.

Create a tag

curl -X POST "https://favro.com/api/v1/tags" \
    -d '{
        "name": "This is Tag",
        "color": "blue"
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created tag.

    {
        "tagId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "name": "My tag",
        "color": "purple"
    }

This endpoint creates a new tag on a card.

HTTP Request

POST https://favro.com/api/v1/tags

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
name string The name of the tag. Required.
color string The color of the tag. If not specified, color will be selected randomly. Refer to tag colors.

Update a tag

curl -X PUT "https://favro.com/api/v1/tags/67973f72db34592d8fc96c48" \
    -d '{
        "name": "This is a tag",
        "color": "green"
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated tag.

    {
        "tagId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "name": "My tag",
        "color": "purple"
    }

This endpoint updates an existing tag.

HTTP Request

PUT https://favro.com/api/v1/tags/:tagId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
tagId string The id of the tag to update.
name string The name of the tag to edit. Optional.
color string The color of the tag to edit. Optional. Refer to tag colors.

Delete a tag

curl -X DELETE "https://favro.com/api/v1/tags/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This endpoint deletes a specific tag.

HTTP Request

DELETE https://favro.com/api/v1/tags/:tagId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
tagId The id of the tag to be deleted. Required.

Tasks

Tasks are the API name for checklist items in Favro.

Task

Field Type Description
taskId string The id of the task.
taskListId string The id of the task list that the task belongs to.
cardCommonId string The common id of the card that the task belongs to.
organizationId string The id of the organization that the task belongs to.
name string The name of the task.
completed boolean True if the task has been completed. False if it has not been.
position number The position of the task relative to the other tasks in this tasklist.

Get all tasks

curl -X GET "https://favro.com/api/v1/tasks?cardCommonId=67973f72db34592d8fc96c48&taskListId=67973f72db34592d8fc96c52" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated array of card tasks.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "taskId": "67973f72db34592d8fc96c48",
        "taskListId": "8cc57b1d8a218fa639c8a0fa",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "cardCommonId": "tXfWe3MXQqhnnTRtw",
        "name": "This is a task",
        "completed": false,
        "position": 0
    }]
}

This endpoint retrieves a paginated list of all card tasks that match the specified parameters.

HTTP Request

GET https://favro.com/api/v1/tasks

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
cardCommonId string The card common id to filter by. Required.
taskListId string The task list id to filter by. Optional.

Get a task

curl -X GET "https://favro.com/api/v1/tasks/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns a task object.

    {
        "taskId": "67973f72db34592d8fc96c48",
        "taskListId": "8cc57b1d8a218fa639c8a0fa",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "cardCommonId": "tXfWe3MXQqhnnTRtw",
        "name": "This is a task",
        "completed": false,
        "position": 0
    }

This endpoint retrieves a specific task.

HTTP Request

GET https://favro.com/api/v1/tasks/:taskId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
taskId string The id of the task to be retrieved.

Create a task

curl -X POST "https://favro.com/api/v1/tasks" \
    -d '{
        "taskListId": "67973f72db34592d8fc96c52",
        "name": "This is a task",
        "position": 1,
        "completed": false
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created task.

    {
        "taskId": "67973f72db34592d8fc96c48",
        "taskListId": "8cc57b1d8a218fa639c8a0fa",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "cardCommonId": "tXfWe3MXQqhnnTRtw",
        "name": "This is a task",
        "completed": false,
        "position": 0
    }

This endpoint creates a new task on a card.

HTTP Request

POST https://favro.com/api/v1/tasks

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
taskListId string The task list id to post the task on. Required.
name string The name of the task. Required.
position number Task position in the task list. Optional.
completed boolean Task completion state. Optional.

Update a task

curl -X PUT "https://favro.com/api/v1/tasks/67973f72db34592d8fc96c48" \
    -d '{
        "name": "This is a task",
        "position": 1,
        "completed": true
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated task.

    {
        "taskId": "67973f72db34592d8fc96c48",
        "taskListId": "8cc57b1d8a218fa639c8a0fa",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "cardCommonId": "tXfWe3MXQqhnnTRtw",
        "name": "This is a task",
        "completed": false,
        "position": 0
    }

This endpoint updates an existing task.

HTTP Request

PUT https://favro.com/api/v1/tasks/:taskId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
taskId string The id of the task to update.
name string The name of the task to edit. Optional.
position number Task position in the list. Optional.
completed string Task completion state. Optional.

Delete a task

curl -X DELETE "https://favro.com/api/v1/tasks/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This endpoint deletes a specific task.

HTTP Request

DELETE https://favro.com/api/v1/tasks/:taskId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
taskId The id of the task to be deleted. Required.

Tasklists

Tasklists are the API name for checklists in Favro.

Task List

Field Type Description
taskListId string The id of the task list.
cardCommonId string The common id of the card that the task list belongs to.
organizationId string The id of the organization that the task list belongs to.
name string The name of the task list.
position number The position of the tasklist relative to the other tasklists on the card.

Get all tasklists

curl -X GET "https://favro.com/api/v1/tasklists?cardCommonId=67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated array of card task lists.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "taskListId": "8cc57b1d8a218fa639c8a0fa",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "cardCommonId": "tXfWe3MXQqhnnTRtw",
        "description": "This is a tasklist",
        "position": 0
    }]
}

This endpoint retrieves a paginated list of all card task lists that match the specified parameters.

HTTP Request

GET https://favro.com/api/v1/tasklists

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
cardCommonId string The card common id to filter by. Required.

Get a task list

curl -X GET "https://favro.com/api/v1/tasklists/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns a task list object.

    {
        "taskListId": "8cc57b1d8a218fa639c8a0fa",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "cardCommonId": "tXfWe3MXQqhnnTRtw",
        "description": "This is a tasklist",
        "position": 0
    }

This endpoint retrieves a specific task list.

HTTP Request

GET https://favro.com/api/v1/tasklists/:taskListId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
taskListId string The id of the task list to be retrieved.

Create a task list

curl -X POST "https://favro.com/api/v1/tasklists" \
    -d '{
        "cardCommonId": "67973f72db34592d8fc96c52",
        "name": "This is a task list",
        "position": 1
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created task list.

    {
        "taskListId": "8cc57b1d8a218fa639c8a0fa",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "cardCommonId": "tXfWe3MXQqhnnTRtw",
        "description": "This is a tasklist",
        "position": 0
    }

This endpoint creates a new task list on a card.

HTTP Request

POST https://favro.com/api/v1/tasklists

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
cardCommonId string The card common id to post the task list on. Required.
name string The name of the task list. Required.
position number Task position of the task list. Optional.
tasks array The list of card task. Optional.

Update a task list

curl -X PUT "https://favro.com/api/v1/tasklists/67973f72db34592d8fc96c48" \
    -d '{
        "name": "This is a tasklist",
        "position": 1
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated task list.

    {
        "taskListId": "8cc57b1d8a218fa639c8a0fa",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "cardCommonId": "tXfWe3MXQqhnnTRtw",
        "description": "This is a tasklist",
        "position": 0
    }

This endpoint updates an existing task list.

HTTP Request

PUT https://favro.com/api/v1/tasklists/:taskListId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
taskListId string The id of the task list to update.
name string The name of the task list to edit. Optional.
position number Task position of the task list. Optional.

Delete a task list

curl -X DELETE "https://favro.com/api/v1/tasklists/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This endpoint deletes a specific task list.

HTTP Request

DELETE https://favro.com/api/v1/tasklists/:taskListId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
taskListId The id of the task list to be deleted. Required.

Comments

Comment object

Field Type Description
commentId string The id of the comment.
organizationId string The id of the organization that this comment exists in.
cardCommonId string The common id of the card that this comment exists on.
comment string The text of the comment.
userId string The id of the user that posted the comment.
created Date The date that the comment was posted.
lastUpdated Date The date that the comment was last edited. Only set if the comment has been edited.
attachments array The file attachments on the comment. See attachments.

Get all comments

curl -X GET "https://favro.com/api/v1/comments?cardCommonId=7736421cb6959474bc80cbd0" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated array of comments.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "commentId": "67973f72db34592d8fc96c48",
        "cardCommonId": "ff440e8f358c08513a86c8d6",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "userId": "b4d8c6283d9d58f9a39108e7",
        "comment": "This is a comment",
        "created": "2016-04-18T11:18:42.901Z",
        "lastUpdated": "2016-04-18T11:18:42.901Z"
    }]
}

This endpoint retrieves a paginated list of all comments that match the specified parameters.

HTTP Request

GET https://favro.com/api/v1/comments

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
cardCommonId string The common id of the card to filter by. Required.

Get a comment

curl -X GET "https://favro.com/api/v1/comments/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns a comment object.

    {
        "commentId": "67973f72db34592d8fc96c48",
        "cardCommonId": "ff440e8f358c08513a86c8d6",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "userId": "b4d8c6283d9d58f9a39108e7",
        "comment": "This is a comment",
        "created": "2016-04-18T11:18:42.901Z",
        "lastUpdated": "2016-04-18T11:18:42.901Z"
    }

This endpoint retrieves a specific comment.

HTTP Request

GET https://favro.com/api/v1/comments/:commentId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
commentId string The id of the comment to be retrieved.

Create a comment

curl -X POST "https://favro.com/api/v1/comments" \
    -d '{
        "comment": "This is a comment",
        "cardCommonId": "ff440e8f358c08513a86c8d6"
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created comment.

    {
        "commentId": "67973f72db34592d8fc96c48",
        "cardCommonId": "ff440e8f358c08513a86c8d6",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "userId": "b4d8c6283d9d58f9a39108e7",
        "comment": "This is a comment",
        "created": "2016-04-18T11:18:42.901Z",
        "lastUpdated": "2016-04-18T11:18:42.901Z"
    }

This endpoint creates a new comment on a card.

HTTP Request

POST https://favro.com/api/v1/comments

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
cardCommonId string The common id of the card to post the comment on. Required.
comment string The body of the comment. Required.

Update a comment

curl -X PUT "https://favro.com/api/v1/comments/67973f72db34592d8fc96c48" \
    -d '{
        "comment": "This is a comment"
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated comment.

    {
        "commentId": "67973f72db34592d8fc96c48",
        "cardCommonId": "ff440e8f358c08513a86c8d6",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "userId": "b4d8c6283d9d58f9a39108e7",
        "comment": "This is a comment",
        "created": "2016-04-18T11:18:42.901Z",
        "lastUpdated": "2016-04-18T11:18:42.901Z"
    }

This endpoint updates an existing comment.

HTTP Request

PUT https://favro.com/api/v1/comments/:commentId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
commentId string The id of the comment to update.
comment string The body of the comment to edit. Optional.
removeAttachments array The list of attachments URLs, that will be removed from the comment. Optional.

Delete a comment

curl -X DELETE "https://favro.com/api/v1/comments/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This endpoint deletes a specific comment.

HTTP Request

DELETE https://favro.com/api/v1/comments/:commentId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
commentId string The id of the comment to be deleted. Required.

Attachments

Attachment

Field Type Description
name string The name of the file.
fileURL string The URL of the file.
thumbnailURL string Optional thumbnail URL of the file.

Upload a file to card

Maximum file size via the Rest API is 10mb. PNG and JPG image files larger than 400 pixels in width will have a thumbnail generated.

curl -X POST "https://favro.com/api/v1/cards/67973f72db34592d8fc96c48/attachment" \
    --upload-file myfile.txt \
    -G --data-urlencode "filename=myfile.txt" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This will upload and attach the file myfile.txt, the response will be the new Attachment.

    {
        "name": "myfile.txt",
        "fileURL": "https://s3-eu-west-1.amazonaws.com/organicrelations/2155aa13-cc0b-4385-8be7-369017e91a7e.txt"
    }

HTTP Request

POST https://favro.com/api/v1/cards/:cardId/attachment

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
cardId The id of the card to attach files to. Required.

Query Parameters

Parameter Type Description
filename string The filename of the file to be uploaded. Required.
mimeType string The MIME type of the file. Optional.

Upload a file to comment

Maximum file size via the Rest API is 10mb. PNG and JPG image files larger than 400 pixels in width will have a thumbnail generated.

curl -X POST "https://favro.com/api/v1/comments/67973f72db34592d8fc96c48/attachment" \
    --upload-file myfile.txt \
    -G --data-urlencode "filename=myfile.txt" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This will upload and attach the file myfile.txt, the response will be the new Attachment.

    {
        "name": "myfile.txt",
        "fileURL": "https://s3-eu-west-1.amazonaws.com/organicrelations/2155aa13-cc0b-4385-8be7-369017e91a7e.txt"
    }

HTTP Request

POST https://favro.com/api/v1/comments/:commentId/attachment

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
commentId The id of the comment to attach files to. Required.

Query Parameters

Parameter Type Description
filename string The filename of the file to be uploaded. Required.
mimeType string The MIME type of the file. Optional.

Custom fields

Custom field

Custom field object

Field Type Description
organizationId string The id of the organization that this custom field exists in.
customFieldId string The id of the custom field.
type string Custom field type. Refer to allowed custom field types.
name string The name of the custom field.
enabled boolean True if the custom field is currently enabled for the organization.
customFieldItems array The list of items that this custom field can have in case it is a selectable one.

Custom field item object

Field Type Description
customFieldItemId string The id of the custom field item.
name string The name of the custom field item.

Custom field types

Number

Field Type Description
total number The total value of the field.

Time

Field Type Description
total number The total value of all time reported by all users.
reports object The values reported by each user. The object key represents the userId of the user. The value is an array of user entries. Refer to custom field time user reports.

Text

Field Type Description
value string The value of the field.

Rating

Field Type Description
total number The value of the field. Valid value is integer from 0 to 5.

Vote

Field Type Description
value array The id array of users that vote for the field.

Checkbox

Field Type Description
value boolean The value of the field.

Date

Field Type Description
value string The date value in ISO format.

Timeline

Field Type Description
timeline object The value options of the field. See custom field timeline.
Field Type Description
link object The value options of the field. See custom field link.

Members

Field Type Description
value array The id array of users that are assigned to card.

Tags

Field Type Description
value array The id array of tags that are added to card.

Status

Field Type Description
value array The id array of item that are added to card.

Multiple select

Field Type Description
value array The id array of item that are added to card.

Custom field time user reports

Field Type Description
reportId string The id of the user entry.
value number The user entry value. Passing 0 will remove report entry. For custom fields with type "Time", this value is in milliseconds.
description string The description of the time report entry.
createdAt string The report date in ISO format.

Custom field card colors

Value
purple purple-100 purple-200 purple-300 purple-600 purple-800
blue blue-100 blue-100 blue-200 blue-300 blue-600
cyan cyan-100 cyan-200 cyan-300 cyan-600 cyan-800
green green-100 green-200 green-300 green-600 green-800
lime lime-100 lime-200 lime-300 lime-600 lime-800
yellow yellow-100 yellow-200 yellow-300 yellow-600 yellow-800
orange orange-100 orange-200 orange-300 orange-600 orange-800
red red-100 red-200 red-300 red-600 red-800
brown brown-100 brown-200 brown-300 brown-600 brown-800
gray gray-100 gray-200 gray-300 gray-600 gray-800

Deprecated card colors

Old Value New Value
lightgreen lime

Custom field timeline

Field Type Description
startDate string The value of start date in ISO format. Required.
dueDate string The value of due date in ISO format. Required.
showTime boolean The value to determine display text of field should include time or not.
Field Type Description
url string The url of the field. Required.
text string The display text of the field. Optional.

Custom field members

Field Type Description
addUserIds array The list of members, that will be added to the card custom field (array of userIds). Optional.
removeUserIds array The list of members, that will be removed from card custom field (array of userIds). Optional.
completeUsers array The list of card assignment, that will update their statuses on the custom field accordingly. Optional.

Custom field tags

Field Type Description
addTags array The list of tag names or card tags that will be added to this card custom field. If the tag does not exist in the organization it will be created. Optional.
addTagIds array A list of tagIds that will be added to this card custom field. Optional.
removeTags array The list of tag names, that will be removed from this card custom field. Optional.
removeTagIds array The list of tag IDs, that will be removed from this card custom field. Optional.

Get all custom fields

curl -X GET "https://favro.com/api/v1/customfields" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated array of custom fields.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fb",
    "entities": [{
        "customFieldId": "eRryDkeAwojKHXBML",
        "type": "Number",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "name": "Estimation",
        "enabled": true
    }]
}

This endpoint retrieves a paginated list of all custom fields that match the specified parameters.

HTTP Request

GET https://favro.com/api/v1/customfields

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Get a custom field

curl -X GET "https://favro.com/api/v1/customfields/eRryDkeAwojKHXBML" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns a custom field object.

    {
        "customFieldId": "eRryDkeAwojKHXBML",
        "type": "Number",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "name": "Estimation",
        "enabled": true
    }

This endpoint retrieves a specific custom field.

HTTP Request

GET https://favro.com/api/v1/customfields/:customfieldId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
customfieldId string The id of the custom field to be retrieved.

Groups

Group

Field Type Description
groupId string The id of the group.
organizationId string The id of the organization that this group exists in.
name string The name of the group.
creatorUserId string The id of creator user.
memberCount number Total number of members in group.
members array List of member in group.

Group roles

Value Description
administrator Administrator/Owner of the group. Has full control over the group.
member Member of group.

Group members

Field Type Description
userId string userId of the user.
role string The role of the user in the group. Refer to group roles.

Get all groups

curl -X GET "https://favro.com/api/v1/groups" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be a paginated array of groups.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "groupId": "67973f72db34592d8fc96c48",
        "organizationId": "b4534186ffe9dddeb97fdfa4",
        "name": "This is a group",
        "creatorUserId": "jeb4q8sPf67YwX7po",
        "memberCount": 2,
        "members": [{
            "userId": "iwhqgRY6q7ybyrurg",
            "role": "administrator"
        }, {
            "userId": "jeb4q8sPf67YwX7po",
            "role": "member"
        }]
    }]
}

This endpoint retrieves a paginated list of all groups that exist on organization.

HTTP Request

GET https://favro.com/api/v1/groups

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Get a group

curl -X GET "https://favro.com/api/v1/groups/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response returns a group object.

    {
        "groupId": "67973f72db34592d8fc96c48",
        "organizationId": "b4534186ffe9dddeb97fdfa4",
        "name": "This is a group",
        "creatorUserId": "jeb4q8sPf67YwX7po",
        "memberCount": 2,
        "members": [{
            "userId": "iwhqgRY6q7ybyrurg",
            "role": "administrator"
        }, {
            "userId": "jeb4q8sPf67YwX7po",
            "role": "member"
        }]
    }

This endpoint retrieves a specific group.

HTTP Request

GET https://favro.com/api/v1/groups/:groupId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
groupId string The id of the group to be retrieved.

Create a group

curl -X POST "https://favro.com/api/v1/groups" \
    -d '{
        "name": "This is a group",
        "members": [{
            "userId": "iwhqgRY6q7ybyrurg",
            "role": "administrator"
        }, {
            "userId": "jeb4q8sPf67YwX7po",
            "role": "member"
        }]
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created group.

    {
        "groupId": "67973f72db34592d8fc96c48",
        "organizationId": "b4534186ffe9dddeb97fdfa4",
        "name": "This is a group",
        "creatorUserId": "jeb4q8sPf67YwX7po",
        "memberCount": 2,
        "members": [{
            "userId": "iwhqgRY6q7ybyrurg",
            "role": "administrator"
        }, {
            "userId": "jeb4q8sPf67YwX7po",
            "role": "member"
        }]
    }

This endpoint creates a new group.

HTTP Request

POST https://favro.com/api/v1/groups

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
name string The name of the group. Required.
members array The list of group members.

Update a group

curl -X PUT "https://favro.com/api/v1/groups/67973f72db34592d8fc96c48" \
    -d '{
        "name": "This is a group",
        "members": [{
            "userId": "iwhqgRY6q7ybyrurg",
            "role": "administrator"
        }, {
            "userId": "jeb4q8sPf67YwX7po",
            "role": "member"
        }]
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the updated group.

    {
        "groupId": "67973f72db34592d8fc96c48",
        "organizationId": "b4534186ffe9dddeb97fdfa4",
        "name": "This is a group",
        "creatorUserId": "jeb4q8sPf67YwX7po",
        "memberCount": 2,
        "members": [{
            "userId": "iwhqgRY6q7ybyrurg",
            "role": "administrator"
        }, {
            "userId": "jeb4q8sPf67YwX7po",
            "role": "member"
        }]
    }

This endpoint updates an existing group.

HTTP Request

PUT https://favro.com/api/v1/groups/:groupId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
name string The name of the group.
members array Update user roles in the group. See below for a description of a user share object.

Group user share object parameters

Parameter Type Description
userId string The userId of the existing user. Required if email is not provided.
email string Email. Required if userId is not provided.
delete boolean Removes user from the group if value equals to true. Optional.
role string The role of the user in the group. Refer to group roles. Required if delete is not provided.

Delete a group

curl -X DELETE "https://favro.com/api/v1/groups/67973f72db34592d8fc96c48" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This endpoint deletes a specific group.

HTTP Request

DELETE https://favro.com/api/v1/groups/:groupId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
groupId string The id of the group to be deleted. Required.

Outgoing webhooks

Webhook

Field Type Description
webhookId string The id of the webhook.
widgetCommonId string The common id of the widget that this webhook was created for.
name string The name of the webhook.
postToUrl string The address to post webhook notifications to.
secret string The secret used to sign the HTTP header X-Favro-Webhook. See webhook signatures for more information.
options object The options for this webhook. Refer to webhook options.

Webhook options

Field Type Description
columnIds array The array of columnIds for which webhook notifications will be sent.
notifications array The webhook notifications to include. If empty, all notifications will be sent. Refer to webhook notifications.

Webhook notifications

Value
Card created
Card committed
Card moved
Card updated
Card removed
Comment added
Comment changed
Comment removed

Get all webhooks

curl -X GET "https://favro.com/api/v1/webhooks?widgetCommonId=ff440e8f358c08513a86c8d6" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

The response will be an array of configured webhooks.

    [{
        "webhookId": "LpeXFaAwnPw7ynmdr",
        "widgetCommonId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a webhook",
        "postToUrl": "https://yourserver.com/webhookfromfavro",
        "secret": "secret-key",
        "options": {
            "columnId": "67973f72db34592d8fc96c48",
            "notifications": [
                "Card created",
                "Card moved"
            ]
        }
    }, {
        "webhookId": "k2WsYSJKfRwvHKemw",
        "widgetCommonId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is another webhook",
        "postToUrl": "https://yourserver.com/webhookfromfavro",
        "secret": "secret-key",
        "options": {
            "columnId": "67973f72db34592d8fc96c48",
            "notifications": [
                "Card removed",
                "Card moved"
            ]
        }
    }]

This endpoint retrieves a list of all configured webhooks (of a specific widget if widgetCommonId parameter is provided).

HTTP Request

GET https://favro.com/api/v1/webhooks

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
widgetCommonId string The common id of the widget to filter by. Optional.

Create a webhook

curl -X POST "https://favro.com/api/v1/webhooks" \
    -d '{
        "widgetCommonId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a webhook",
        "postToUrl": "https://yourserver.com/webhookfromfavro",
        "secret": "secret-key",
        "options": {
            "columnIds": ["67973f72db34592d8fc96c48"],
            "notifications": [
                "Card created",
                "Card moved"
            ]
        }
    }' \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -H "Content-Type: application/json" \
    -u "user@example.com":"password"

The response will be the created webhook.

    {
        "webhookId": "LpeXFaAwnPw7ynmdr",
        "widgetCommonId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a webhook",
        "postToUrl": "https://yourserver.com/webhookfromfavro",
        "secret": "secret-key",
        "options": {
            "columnId": "67973f72db34592d8fc96c48",
            "notifications": [
                "Card created",
                "Card moved"
            ]
        }
    }

This endpoint creates a new webhook.

HTTP Request

POST https://favro.com/api/v1/webhooks

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
widgetCommonId string The widgetCommonId of the widget to create the webhook in. Required.
name string The name of the webhook. Required.
postToUrl string The address to post webhook notifications to. Required.
secret string The secret used to sign the HTTP header X-Favro-Webhook. See webhook signatures for more information. Required.
options object The options for this webhook. See below for a description of an options object.

Webhook options object parameters

Field Type Description
columnIds array The array of columnIds for which webhook notifications will be sent.
notifications array The webhook notifications to include. If empty, all notifications will be sent. Refer to webhook notifications.

Delete a webhook

curl -X DELETE "https://favro.com/api/v1/webhooks/LpeXFaAwnPw7ynmdr" \
    -H "organizationId: zk4CJpg5uozhL4R2W" \
    -u "user@example.com":"password"

This endpoint deletes a specific webhook.

HTTP Request

DELETE https://favro.com/api/v1/webhooks/:webhookId

organizationId in header

For this endpoint it is required to send in the organizationId of the organization that this call is being made against. This is both for rate limiting purposes and also to ensure the request is routed to the correct server.

Request Parameters

Parameter Type Description
webhookId string The webhookId of the webhook to be deleted. Required.

Webhook signatures

Favro signs webhook requests so you can optionally verify that they originated from Favro. Each webhook trigger contains the HTTP header X-Favro-Webhook. The header is a base64 digest of an HMAC-SHA1 hash. The hashed content is the concatenation of the payloadId and the URL exactly as it was provided during webhook creation. The key used to sign this text is the secret you entered when setting up the webhook.

Webhook responses

Favro expects to receive a 200 response for each webhook payload event. If multiple payload events do not receive a 200 response, Favro will disable the webhook and stop sending events until the webhook is reconfigured.

Ping event

Example payload:

{
    "payloadId": "ZnvqwjdLh1wmbnEj6vOfHhv8ARY=",
    "action": "ping",
    "hookId": "67973f72db34592d8fc96c48",
    "hook": {
        "url" : "https://yourserver.com/webhookfromfavro"
    }
}

This payload is sent whenever a new webhook is created. It is sent to ensure that the webhook is configured correctly.

Payload fields

Field Type Description
hookId string The id of the created hook.
hook object The outgoing webhook that was configured.

Card created event

Example payload:

{
    "payloadId": "ZnvqwjdLh1wmbnEj6vOfHhv8ARY=",
    "action": "created",
    "card": {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    },
    "column": {
        "columnId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "name": "This is a column",
        "position": 0,
        "cardCount": 3,
        "timeSum": 609111150,
        "estimationSum": 22
    },
    "sender": {
        "userId": "67973f72db34592d8fc96c48",
        "name": "Favro user",
        "email": "user@favro.com",
        "organizationRole": "administrator"
    },
    "widget": {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false,
        "lanes": [
            {
                laneId: "1dd704ad8cee4eed2b89f917",
                name: "Not main lane"
            },
            {
                laneId: "4360cdf5be3d42b679e74422",
                name: "Main lane"
            }
        ],
        "columns": [
            {
                "columnId": "1360cdf5be3d42b679e74422",
                "name": "To do",
                "color": "gray"
            },
            {
                "columnId": "2360cdf5be3d42b679e74422",
                "name": "Doing",
                "color": "orange"
            },
            {
                "columnId": "3360cdf5be3d42b679e74422",
                "name": "Done",
                "color": "green"
            }
        ]
    }
}

This payload is sent whenever a card is created.

Payload fields

Field Type Description
card object The card that was created.
column object The column that the card was created in. Only included if the widget is a board.
sender object The user that performed the action that triggered this webhook event.
widget object The widget that the card was created on.

Card committed event

Example payload:

{
    "payloadId": "ZnvqwjdLh1wmbnEj6vOfHhv8ARY=",
    "action": "committed",
    "card": {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    },
    "column": {
        "columnId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "name": "This is a column",
        "position": 0,
        "cardCount": 3,
        "timeSum": 609111150,
        "estimationSum": 22
    },
    "sender": {
        "userId": "67973f72db34592d8fc96c48",
        "name": "Favro user",
        "email": "user@favro.com",
        "organizationRole": "administrator"
    },
    "widget": {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false,
        "lanes": [
            {
                laneId: "1dd704ad8cee4eed2b89f917",
                name: "Not main lane"
            },
            {
                laneId: "4360cdf5be3d42b679e74422",
                name: "Main lane"
            }
        ],
        "columns": [
            {
                "columnId": "1360cdf5be3d42b679e74422",
                "name": "To do",
                "color": "gray"
            },
            {
                "columnId": "2360cdf5be3d42b679e74422",
                "name": "Doing",
                "color": "orange"
            },
            {
                "columnId": "3360cdf5be3d42b679e74422",
                "name": "Done",
                "color": "green"
            }
        ]
    },
    "sourceWidget": {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false,
        "lanes": [
            {
                laneId: "1dd704ad8cee4eed2b89f917",
                name: "Not main lane"
            },
            {
                laneId: "4360cdf5be3d42b679e74422",
                name: "Main lane"
            }
        ],
        "columns": [
            {
                "columnId": "1360cdf5be3d42b679e74422",
                "name": "To do",
                "color": "gray"
            },
            {
                "columnId": "2360cdf5be3d42b679e74422",
                "name": "Doing",
                "color": "orange"
            },
            {
                "columnId": "3360cdf5be3d42b679e74422",
                "name": "Done",
                "color": "green"
            }
        ]
    }
}

This payload is sent whenever a card is committed to another widget.

Payload fields

Field Type Description
card object The card that was committed.
column object The column that the card was committed to.
sender object The user that performed the action that triggered this webhook event.
widget object The widget that the card was committed to.
sourceWidget object The widget that the card was committed from.

Card moved event

Example payload:

{
    "payloadId": "ZnvqwjdLh1wmbnEj6vOfHhv8ARY=",
    "action": "moved",
    "card": {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    },
    "column": {
        "columnId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "name": "This is a column",
        "position": 0,
        "cardCount": 3,
        "timeSum": 609111150,
        "estimationSum": 22
    },
    "sender": {
        "userId": "67973f72db34592d8fc96c48",
        "name": "Favro user",
        "email": "user@favro.com",
        "organizationRole": "administrator"
    },
    "sourceColumn": {
        "columnId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "name": "This is a column",
        "position": 0,
        "cardCount": 3,
        "timeSum": 609111150,
        "estimationSum": 22
    },
    "widget": {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false,
        "lanes": [
            {
                laneId: "1dd704ad8cee4eed2b89f917",
                name: "Not main lane"
            },
            {
                laneId: "4360cdf5be3d42b679e74422",
                name: "Main lane"
            }
        ],
        "columns": [
            {
                "columnId": "1360cdf5be3d42b679e74422",
                "name": "To do",
                "color": "gray"
            },
            {
                "columnId": "2360cdf5be3d42b679e74422",
                "name": "Doing",
                "color": "orange"
            },
            {
                "columnId": "3360cdf5be3d42b679e74422",
                "name": "Done",
                "color": "green"
            }
        ]
    }
}

This payload is sent whenever a card is moved on a widget.

Payload fields

Field Type Description
card object The card that was moved.
column object The column that the card was moved to.
sender object The user that performed the action that triggered this webhook event.
sourceColumn object The column that the card was moved from.
widget object The widget that the card was moved on.

Card updated event

Example payload:

{
    "payloadId": "ZnvqwjdLh1wmbnEj6vOfHhv8ARY=",
    "action": "updated",
    "card": {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    },
    "sender": {
        "userId": "67973f72db34592d8fc96c48",
        "name": "Favro user",
        "email": "user@favro.com",
        "organizationRole": "administrator"
    }
}

This payload is sent whenever a card is updated. This event is triggered when any field (except comments) is changed. It is also triggered when a card is moved to a different column.

Payload fields

Field Type Description
card object The card that was updated.
sender object The user that performed the action that triggered this webhook event.
widget object The widget that the card exists on.

Card deleted event

Example payload:

{
    "payloadId": "ZnvqwjdLh1wmbnEj6vOfHhv8ARY=",
    "action": "deleted",
    "card": {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    },
    "sender": {
        "userId": "67973f72db34592d8fc96c48",
        "name": "Favro user",
        "email": "user@favro.com",
        "organizationRole": "administrator"
    }
}

This payload is sent whenever a card is deleted.

Payload fields

Field Type Description
card object The card that was deleted.
sender object The user that performed the action that triggered this webhook event.
widget object The widget that the card was deleted from.

Comment created event

Example payload:

{
    "payloadId": "ZnvqwjdLh1wmbnEj6vOfHhv8ARY=",
    "action": "created",
    "card": {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    },
    "comment": {
        "commentId": "67973f72db34592d8fc96c48",
        "cardCommonId": "ff440e8f358c08513a86c8d6",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "userId": "b4d8c6283d9d58f9a39108e7",
        "comment": "This is a comment",
        "created": "2016-04-18T11:18:42.901Z",
        "lastUpdated": "2016-04-18T11:18:42.901Z"
    },
    "sender": {
        "userId": "67973f72db34592d8fc96c48",
        "name": "Favro user",
        "email": "user@favro.com",
        "organizationRole": "administrator"
    }
}

This payload is sent whenever a comment is created.

Payload fields

Field Type Description
card object The card that the comment was created on.
comment object The comment that was created.
sender object The user that performed the action that triggered this webhook event.

Comment updated event

Example payload:

{
    "payloadId": "ZnvqwjdLh1wmbnEj6vOfHhv8ARY=",
    "action": "updated",
    "card": {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    },
    "comment": {
        "commentId": "67973f72db34592d8fc96c48",
        "cardCommonId": "ff440e8f358c08513a86c8d6",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "userId": "b4d8c6283d9d58f9a39108e7",
        "comment": "This is a comment",
        "created": "2016-04-18T11:18:42.901Z",
        "lastUpdated": "2016-04-18T11:18:42.901Z"
    },
    "sender": {
        "userId": "67973f72db34592d8fc96c48",
        "name": "Favro user",
        "email": "user@favro.com",
        "organizationRole": "administrator"
    }
}

This payload is sent whenever a comment is updated.

Payload fields

Field Type Description
card object The card that the comment was updated on.
comment object The comment that was updated.
sender object The user that performed the action that triggered this webhook event.

Comment deleted event

Example payload:

{
    "payloadId": "ZnvqwjdLh1wmbnEj6vOfHhv8ARY=",
    "action": "deleted",
    "card": {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "createdByUserId": "p3tB8yWgtaMnDYdzW",
        "createdAt": "2023-02-06T12:46:45.945+00:00",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    },
    "comment": {
        "commentId": "67973f72db34592d8fc96c48",
        "cardCommonId": "ff440e8f358c08513a86c8d6",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "userId": "b4d8c6283d9d58f9a39108e7",
        "comment": "This is a comment",
        "created": "2016-04-18T11:18:42.901Z",
        "lastUpdated": "2016-04-18T11:18:42.901Z"
    },
    "sender": {
        "userId": "67973f72db34592d8fc96c48",
        "name": "Favro user",
        "email": "user@favro.com",
        "organizationRole": "administrator"
    }
}

This payload is sent whenever a comment is deleted.

Payload fields

Field Type Description
card object The card that the comment was deleted from.
comment object The comment that was deleted.
sender object The user that performed the action that triggered this webhook event.

SAML Single Sign-on

Favro supports user login and provisioning via SAML.

To use these endpoints your organization must be on the Enterprise plan as well as have a verified domain.

The configuration for Favro SAML is:

Field Value
Audience/entity ID https://favro.com/saml/metadata.xml
Consumer URL https://favro.com/saml/assert
Single Logout URL https://favro.com/saml/slo
NameId format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

For just-in-time provisioning we support the following attributes in the SAML assertion:

First Name
given_name
attributes.First Name
attributes.givenName
attributes.http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last Name
surname
attributes.Last Name
attributes.familyName
attributes.http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Favro Role
attributes.favroRole
attributes.FavroRole

Normally users are provisioned as full members in Favro organizations, but if FavroRole or favroRole attribute is specified and set to a provisioning role, then the corresponding role will be used.

Provisioning Roles

Role Comments
Administrator You need to enable this in the domain settings for this role to be allowed.
Full Member
External Member
Guest

SCIM v1.1 Provisioning

User and group provisioning

Favro supports user and group provisioning via SCIM.

To use these endpoints your organization must have SAML-based Single Sign-On configured as a bearer-token is required per domain.

Pagination Query Parameters

Parameter Type Description
count number The number of resources to retrieve.
startIndex number The number of resources to skip initially.

Get all users

curl -X GET "https://favro.com/api/scim/v1/Users" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a list of user resources.

{
    "totalResults": 1,
    "itemsPerPage": 100,
    "startIndex": 1,
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "Resources": [
        {
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "id": "XL7tBffEMcasFPeQy",
            "userName": "user@favro.com",
            "name": {
                "givenName": "Favro",
                "familyName": "User"
            },
            "displayName": "Favro User",
            "active": true,
            "emails": [
                {
                    "value": "user@favro.com",
                    "primary": true
                }
            ],
            "entitlements": [
                { "FavroRole": "Guest" }
            ],
            "favroRole": "Guest"
            "groups": [],
            "meta": {
                "resourceType": "User",
                "created": "2017-03-20T15:28:10.582Z",
                "lastModified": "2017-03-20T15:28:10.582Z",
                "location": "https://favro.com/api/scim/v1/Users/XL7tBffEMcasFPeQy"
            }
        }
    ]
}

Retrieves all user resources. Supports pagination and filtering on email.

GET https://favro.com/api/scim/v1/Users

Query Parameters

Parameter Type Description
filter string The filter to use when retrieving users. userName eq email@domain.com

Get user

curl -X GET "https://favro.com/api/scim/v1/Users/XL7tBffEMcasFPeQy" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a user resource.

        {
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "id": "XL7tBffEMcasFPeQy",
            "userName": "user@favro.com",
            "name": {
                "givenName": "Favro",
                "familyName": "User"
            },
            "displayName": "Favro User",
            "active": true,
            "emails": [
                {
                    "value": "user@favro.com",
                    "primary": true
                }
            ],
            "entitlements": [
                { "FavroRole": "Guest" }
            ],
            "favroRole": "Guest"
            "groups": [],
            "meta": {
                "resourceType": "User",
                "created": "2017-03-20T15:28:10.582Z",
                "lastModified": "2017-03-20T15:28:10.582Z",
                "location": "https://favro.com/api/scim/v1/Users/XL7tBffEMcasFPeQy"
            }
        }

Retrieves a single user resource;

GET https://favro.com/api/scim/v1/Users/:userId

Create user

curl -X POST "https://favro.com/api/scim/v1/Users" \
    -H "Content-Type: application/json" \
    -d '{
            "userName": "user@favro.com",
            "name": {
                "givenName": "Favro",
                "familyName": "User",
                "formatted": "Favro User"
            },
            "entitlements": [
                { "FavroRole": "Guest" }
            ]
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a new user resource.

        {
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "id": "XL7tBffEMcasFPeQy",
            "userName": "user@favro.com",
            "name": {
                "givenName": "Favro",
                "familyName": "User"
            },
            "displayName": "Favro User",
            "active": true,
            "emails": [
                {
                    "value": "user@favro.com",
                    "primary": true
                }
            ],
            "entitlements": [
                { "FavroRole": "Guest" }
            ],
            "favroRole": "Guest"
            "groups": [],
            "meta": {
                "resourceType": "User",
                "created": "2017-03-20T15:28:10.582Z",
                "lastModified": "2017-03-20T15:28:10.582Z",
                "location": "https://favro.com/api/scim/v1/Users/XL7tBffEMcasFPeQy"
            }
        }

Creates a user and adds it to the organization.

POST https://favro.com/api/scim/v1/Users

Request Payload Properties

Parameter Type Description
userName string The email for the new user. Together with emails, the first email matching the bearer token domain will be used to identify the user.
emails array The email for the new user. Together with userName, the first email matching the bearer token domain will be used to identify the user.
name object The name for the new user. Favro uses the formatted parameter only if givenName and familyName is not specified. Required.
favroRole string The workspace role to provision user with. Default is full member. See Provisioning Roles.
entitlements array Array of objects with additional attributes. FavroRole or favroRole attribute to specify the workspace role for a user. Default is full member. See Provisioning Roles.

Update user

curl -X PUT "https://favro.com/api/scim/v1/Users/XL7tBffEMcasFPeQy" \
    -H "Content-Type: application/json" \
    -d '{
            "name": {
                "givenName": "New",
                "familyName": "Name",
                "formatted": "New Name"
            },
            "active": false
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be the updated user resource.

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "id": "XL7tBffEMcasFPeQy",
    "userName": "user@favro.com",
    "name": {
        "givenName": "New",
        "familyName": "name"
    },
    "displayName": "New name",
    "active": false,
    "emails": [
        {
            "value": "user@favro.com",
            "primary": true
        }
    ],
    "groups": [],
    "meta": {
        "resourceType": "User",
        "created": "2017-03-20T15:28:10.582Z",
        "lastModified": "2017-03-20T15:28:10.582Z",
        "location": "http://localhost:3000/api/scim/v1/Users/XL7tBffEMcasFPeQy"
    }
}

Updates a user

PUT https://favro.com/api/scim/v1/Users/:userId

Request Payload Properties

Parameter Type Description
name object The new name for the user. Favro uses the formatted parameter only if givenName and familyName is not specified.
active boolean Activates or disables the user. Defaults to false.
entitlements array Array of objects with additional attributes. FavroRole or favroRole attribute to specify the workspace role for a user. Default is full member. See Provisioning Roles.

Disable user

curl -X DELETE "https://favro.com/api/scim/v1/Users/XL7tBffEMcasFPeQy" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

Disables a user

DELETE https://favro.com/api/scim/v1/Users/:userId

Get all groups

curl -X GET "https://favro.com/api/scim/v1/Groups" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a list of group resources.

{
    "totalResults": 1,
    "itemsPerPage": 100,
    "startIndex": 1,
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "Resources": [
        {
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "id": "6digk8JrQs2m4p4eY",
            "displayName": "Admins",
            "members": [],
            "meta": {
                "resourceType": "Group",
                "created": "2017-05-17T13:50:42.720Z",
                "lastModified": "2017-05-17T13:50:42.720Z",
                "location": "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY"
            }
        }
    ]
}

Retrieves all group resources. Supports pagination.

GET https://favro.com/api/scim/v1/Groups

Get group

curl -X GET "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a group resource.

        {
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "id": "6digk8JrQs2m4p4eY",
            "displayName": "Admins",
            "members": [],
            "meta": {
                "resourceType": "Group",
                "created": "2017-05-17T13:50:42.720Z",
                "lastModified": "2017-05-17T13:50:42.720Z",
                "location": "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY"
            }
        }

Retrieves a single group resource.

GET https://favro.com/api/scim/v1/Groups/:groupId

Create group

curl -X POST "https://favro.com/api/scim/v1/Groups" \
    -H "Content-Type: application/json" \
    -d '{
            "displayName": "Admins"
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a new group resource.

        {
            "schemas": [
                "urn:scim:schemas:core:1.0"
            ],
            "id": "6digk8JrQs2m4p4eY",
            "displayName": "Admins",
            "members": [],
            "meta": {
                "resourceType": "Group",
                "created": "2017-05-17T13:50:42.720Z",
                "lastModified": "2017-05-17T13:50:42.720Z",
                "location": "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY"
            }
        }

Creates a group.

POST https://favro.com/api/scim/v1/Groups

Request Parameters

Parameter Type Description
displayName string The name for the new group. Required.
members array The array of users to add to the group. See below for a description of a member object.

Group member operation parameters

Parameter Type Description
value string The user id of the member. Required.

Update group

curl -X PUT "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY" \
    -H "Content-Type: application/json" \
    -d '{
            "displayName": "New group name",
            "members": [{
                "value": "XL7tBffEMcasFPeQy"
            }]
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be the updated group resource.

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "id": "6digk8JrQs2m4p4eY",
    "displayName": "New group name",
    "members": [
        {
            "value": "XL7tBffEMcasFPeQy",
            "display": "New name"
        }
    ],
    "meta": {
        "resourceType": "Group",
        "created": "2017-05-17T13:50:42.720Z",
        "lastModified": "2017-05-17T13:50:42.720Z",
        "location": "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY"
    }
}

Updates a group

PUT https://favro.com/api/scim/v1/Groups/:groupId

Request Parameters

Parameter Type Description
displayName string The name for the new group. Required.
members array The array of users to add to or remove from the group. See below for a description of a member object.

Group member operation parameters

Parameter Type Description
value string The user id of the member. Required.

Add or remove members

curl -X PATCH "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY" \
    -H "Content-Type: application/json" \
    -d '{
            "members": [{
                "value": "XL7tBffEMcasFPeQy",
                "operation": "add"
            }]
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be the updated group resource if changes has been made.

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "id": "6digk8JrQs2m4p4eY",
    "displayName": "New group name",
    "members": [
        {
            "value": "XL7tBffEMcasFPeQy",
            "display": "New name"
        }
    ],
    "meta": {
        "resourceType": "Group",
        "created": "2017-05-17T13:50:42.720Z",
        "lastModified": "2017-05-17T13:50:42.720Z",
        "location": "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY"
    }
}

Adds and removes users from a group.

PATCH https://favro.com/api/scim/v1/Groups/:groupId

Request Parameters

Parameter Type Description
members array The array of users to add to or remove from the group. See below for a description of a member object.

Group member operation parameters

Parameter Type Description
value string The user id of the member to add or remove. Required.
operation string The operation to perform, "add" or "delete".

Delete group

curl -X DELETE "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

Deletes a group

DELETE https://favro.com/api/scim/v1/Groups/:groupId

SCIM v2.0 Provisioning

User and group provisioning

Favro supports user and group provisioning via SCIM.

To use these endpoints your organization must have SAML-based Single Sign-On configured as a bearer-token is required per domain.

Pagination Query Parameters

Parameter Type Description
count number The number of resources to retrieve.
startIndex number The number of resources to skip initially.

Get all users

curl -X GET "https://favro.com/api/scim/v2/Users" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a list of user resources.

{
    "totalResults": 1,
    "itemsPerPage": 100,
    "startIndex": 1,
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "XL7tBffEMcasFPeQy",
            "userName": "user@favro.com",
            "name": {
                "givenName": "Favro",
                "familyName": "User"
            },
            "displayName": "Favro User",
            "active": true,
            "emails": [
                {
                    "value": "user@favro.com",
                    "primary": true
                }
            ],
            "entitlements": [
                { "FavroRole": "Guest" }
            ],
            "favroRole": "Guest"
            "groups": [],
            "meta": {
                "resourceType": "User",
                "created": "2017-03-20T15:28:10.582Z",
                "lastModified": "2017-03-20T15:28:10.582Z",
                "location": "https://favro.com/api/scim/v1/Users/XL7tBffEMcasFPeQy"
            }
        }
    ]
}

Retrieves all user resources. Supports pagination and filtering on email.

GET https://favro.com/api/scim/v2/Users

Query Parameters

Parameter Type Description
filter string The filter to use when retrieving users. userName eq email@domain.com

Get user

curl -X GET "https://favro.com/api/scim/v2/Users/XL7tBffEMcasFPeQy" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a user resource.

        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "XL7tBffEMcasFPeQy",
            "userName": "user@favro.com",
            "name": {
                "givenName": "Favro",
                "familyName": "User"
            },
            "displayName": "Favro User",
            "active": true,
            "emails": [
                {
                    "value": "user@favro.com",
                    "primary": true
                }
            ],
            "entitlements": [
                { "FavroRole": "Guest" }
            ],
            "favroRole": "Guest"
            "groups": [],
            "meta": {
                "resourceType": "User",
                "created": "2017-03-20T15:28:10.582Z",
                "lastModified": "2017-03-20T15:28:10.582Z",
                "location": "https://favro.com/api/scim/v1/Users/XL7tBffEMcasFPeQy"
            }
        }

Retrieves a single user resource;

GET https://favro.com/api/scim/v2/Users/:userId

Create user

curl -X POST "https://favro.com/api/scim/v2/Users" \
    -H "Content-Type: application/json" \
    -d '{
            "userName": "user@favro.com",
            "name": {
                "givenName": "New",
                "familyName": "Name",
                "formatted": "New Name"
            },
            "favroRole": "Guest"
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a new user resource.

        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "XL7tBffEMcasFPeQy",
            "userName": "user@favro.com",
            "name": {
                "givenName": "Favro",
                "familyName": "User"
            },
            "displayName": "Favro User",
            "active": true,
            "emails": [
                {
                    "value": "user@favro.com",
                    "primary": true
                }
            ],
            "entitlements": [
                { "FavroRole": "Guest" }
            ],
            "favroRole": "Guest"
            "groups": [],
            "meta": {
                "resourceType": "User",
                "created": "2017-03-20T15:28:10.582Z",
                "lastModified": "2017-03-20T15:28:10.582Z",
                "location": "https://favro.com/api/scim/v1/Users/XL7tBffEMcasFPeQy"
            }
        }

Creates a user and adds it to the organization.

POST https://favro.com/api/scim/v2/Users

Request Parameters

Parameter Type Description
userName string The email for the new user. Together with emails, the first email matching the bearer token domain will be used to identify the user.
emails array The email for the new user. Together with userName, the first email matching the bearer token domain will be used to identify the user.
name object The name for the new user. Favro uses the formatted parameter only if givenName and familyName is not specified. Required.
favroRole string The workspace role to provision user with. Default is full member. See Provisioning Roles.
entitlements array Array of objects with additional attributes. FavroRole or favroRole attribute to specify the workspace role for a user. Default is full member. See Provisioning Roles.

Update user

curl -X PUT "https://favro.com/api/scim/v2/Users/XL7tBffEMcasFPeQy" \
    -H "Content-Type: application/json" \
    -d '{
            "name": {
                "givenName": "New",
                "familyName": "Name",
                "formatted": "New Name"
            },
            "active": false
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be the updated user resource.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "XL7tBffEMcasFPeQy",
    "userName": "user@favro.com",
    "name": {
        "givenName": "New",
        "familyName": "name"
    },
    "displayName": "New name",
    "active": false,
    "emails": [
        {
            "value": "user@favro.com",
            "primary": true
        }
    ],
    "groups": [],
    "meta": {
        "resourceType": "User",
        "created": "2017-03-20T15:28:10.582Z",
        "lastModified": "2017-03-20T15:28:10.582Z",
        "location": "http://localhost:3000/api/scim/v2/Users/XL7tBffEMcasFPeQy"
    }
}

Updates a user

PUT https://favro.com/api/scim/v2/Users/:userId

Request Parameters

Parameter Type Description
name object The new name for the user. Favro uses the formatted parameter only if givenName and familyName is not specified.
active boolean Activates or disables the user. Defaults to false.
entitlements array Array of objects with additional attributes. FavroRole or favroRole attribute to specify the workspace role for a user. Default is full member. See Provisioning Roles.

Patch user

curl -X PATCH "https://favro.com/api/scim/v2/Users/XL7tBffEMcasFPeQy" \
    -H "Content-Type: application/json" \
    -d '{
            "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
            "Operations": [
                {"op": "replace", "path": "name.givenName", "value": "New2"}
            ]
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be the updated user resource if changes has been made.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "XL7tBffEMcasFPeQy",
    "userName": "user@favro.com",
    "name": {
        "givenName": "New2",
        "familyName": "name"
    },
    "displayName": "New2 name",
    "active": false,
    "emails": [
        {
            "value": "user@favro.com",
            "primary": true
        }
    ],
    "groups": [],
    "meta": {
        "resourceType": "User",
        "created": "2017-03-20T15:28:10.582Z",
        "lastModified": "2017-03-20T15:28:10.582Z",
        "location": "http://localhost:3000/api/scim/v2/Users/XL7tBffEMcasFPeQy"
    }
}

Change user properties.

PATCH https://favro.com/api/scim/v2/Users/:userId

Request Parameters

Parameter Type Description
Operations array An array of modifications to apply to the user resource. See RFC 7644 Section 3.5.2

Disable user

curl -X DELETE "https://favro.com/api/scim/v2/Users/XL7tBffEMcasFPeQy" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

Disables a user

DELETE https://favro.com/api/scim/v2/Users/:userId

Get all groups

curl -X GET "https://favro.com/api/scim/v2/Groups" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a list of group resources.

{
    "totalResults": 1,
    "itemsPerPage": 100,
    "startIndex": 1,
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "id": "6digk8JrQs2m4p4eY",
            "displayName": "Admins",
            "members": [],
            "meta": {
                "resourceType": "Group",
                "created": "2017-05-17T13:50:42.720Z",
                "lastModified": "2017-05-17T13:50:42.720Z",
                "location": "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY"
            }
        }
    ]
}

Retrieves all group resources. Supports pagination.

GET https://favro.com/api/scim/v2/Groups

Get group

curl -X GET "https://favro.com/api/scim/v2/Groups/6digk8JrQs2m4p4eY" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a group resource.

        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "id": "6digk8JrQs2m4p4eY",
            "displayName": "Admins",
            "members": [],
            "meta": {
                "resourceType": "Group",
                "created": "2017-05-17T13:50:42.720Z",
                "lastModified": "2017-05-17T13:50:42.720Z",
                "location": "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY"
            }
        }

Retrieves a single group resource.

GET https://favro.com/api/scim/v2/Groups/:groupId

Create group

curl -X POST "https://favro.com/api/scim/v2/Groups" \
    -H "Content-Type: application/json" \
    -d '{
            "displayName": "Admins"
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be a new group resource.

        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "id": "6digk8JrQs2m4p4eY",
            "displayName": "Admins",
            "members": [],
            "meta": {
                "resourceType": "Group",
                "created": "2017-05-17T13:50:42.720Z",
                "lastModified": "2017-05-17T13:50:42.720Z",
                "location": "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY"
            }
        }

Creates a group.

POST https://favro.com/api/scim/v2/Groups

Request Parameters

Parameter Type Description
displayName string The name for the new group. Required.
members array The array of users to add to the group. See below for a description of a member object.

Group member operation parameters

Parameter Type Description
value string The user id of the member. Required.

Update group

curl -X PUT "https://favro.com/api/scim/v2/Groups/6digk8JrQs2m4p4eY" \
    -H "Content-Type: application/json" \
    -d '{
            "displayName": "New group name",
            "members": [{
                "value": "XL7tBffEMcasFPeQy"
            }]
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be the updated group resource.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "6digk8JrQs2m4p4eY",
    "displayName": "New group name",
    "members": [
        {
            "value": "XL7tBffEMcasFPeQy",
            "display": "New name"
        }
    ],
    "meta": {
        "resourceType": "Group",
        "created": "2017-05-17T13:50:42.720Z",
        "lastModified": "2017-05-17T13:50:42.720Z",
        "location": "https://favro.com/api/scim/v2/Groups/6digk8JrQs2m4p4eY"
    }
}

Updates a group

PUT https://favro.com/api/scim/v2/Groups/:groupId

Request Parameters

Parameter Type Description
displayName string The name for the new group. Required.
members array The array of users to add to or remove from the group. See below for a description of a member object.

Group member operation parameters

Parameter Type Description
value string The user id of the member. Required.

Patch group

curl -X PATCH "https://favro.com/api/scim/v2/Groups/6digk8JrQs2m4p4eY" \
    -H "Content-Type: application/json" \
    -d '{
            "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
            "Operations": [
                {"op": "add", "path": "members", "value": [{"value": "XL7tBffEMcasFPeQy", "display": "New name"}]}
            ]
        }' \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

The response will be the updated group resource if changes has been made.

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "id": "6digk8JrQs2m4p4eY",
    "displayName": "New group name",
    "members": [
        {
            "value": "XL7tBffEMcasFPeQy",
            "display": "New name"
        }
    ],
    "meta": {
        "resourceType": "Group",
        "created": "2017-05-17T13:50:42.720Z",
        "lastModified": "2017-05-17T13:50:42.720Z",
        "location": "https://favro.com/api/scim/v2/Groups/6digk8JrQs2m4p4eY"
    }
}

Adds and removes users from a group or changes display name.

PATCH https://favro.com/api/scim/v2/Groups/:groupId

Request Parameters

Parameter Type Description
Operations array An array of modifications to apply to the group resource. See RFC 7644 Section 3.5.2

Delete group

curl -X DELETE "https://favro.com/api/scim/v2/Groups/6digk8JrQs2m4p4eY" \
    -H "Authorization: Bearer Vi_wcfhsdpJg2knGnHmCoXiolxxxxxxxxx" \
    -H 'Accept: application/json'

Deletes a group

DELETE https://favro.com/api/scim/v2/Groups/:groupId