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

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

Get a user
Get all organizations
Create an organization

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

Throttling

To ensure fair usage and optimal performance, a token bucket algorithm is applied for throttling API requests. Each request consumes a token, and tokens replenish at a rate aligned with the hourly limit. Essentially, the hourly rate is divided into per-second allowances. To further optimize the experience, responses are automatically delayed to allow token replenishment when necessary, thereby reducing the number of failed API requests. If the delay exceeds 10 seconds, the call will fail with the 429 status code.

Response headers

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.
X-RateLimit-Delay	The duration, in seconds, by which the request was delayed.

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

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.

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

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.

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

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

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

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

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.

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

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.

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

Request Parameters

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

Widgets

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.

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.

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.

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

Request Parameters

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

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

Request Parameters

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

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

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.

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

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.

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

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

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

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

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

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

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.

Link custom field parameters

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 fields can be:

Board - usable only within a single widget.
Shared - usable across the entire organization.

Board fields will have widgetCommonId field set, shared fields will not.

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.
widgetCommonId	string	The shared id of the widget if the custom field is local to that widget.
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.

Link

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.

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.

Custom field link

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

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

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

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

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

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

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.

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

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

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

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

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

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.

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.

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.

Introduction

Authentication

Tokens

Routing

Pagination

Rate limiting and throttling

Throttling

Response headers

Errors

HTTP status code summary

Users

User

Get all users

HTTP Request

organizationId in header

Get a user

HTTP Request

Query Parameters

Organizations

Organization

Organization roles

Organization members

Get all organizations

HTTP Request

Get an organization

HTTP Request

organizationId in header

Query Parameters

Create an organization

HTTP Request

Request Parameters

Organization user share object parameters

Update an organization

HTTP Request

organizationId in header

Request Parameters

Organization user share object parameters

Collections

Collection

Collection background

Collection public sharing

Collection roles

Collection members

Get all collections

HTTP Request

organizationId in header

Request Parameters

Get a collection

HTTP Request

organizationId in header

Request Parameters

Create a collection

HTTP Request

organizationId in header

Request Parameters

Collection user share object parameters

Update a collection

HTTP Request

organizationId in header

Request Parameters

Collection user share object parameters

Delete a collection

HTTP Request

organizationId in header

Request Parameters

Widgets

Widget

Widget types

Widget roles

Widget colors

Get all widgets

HTTP Request

organizationId in header

Request Parameters

Get a widget

HTTP Request

organizationId in header

Request Parameters

Create a widget

HTTP Request