NAV Navbar
Logo
shell

Introduction

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

If you have any problems or requests please contact support.

Authentication

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

Tokens

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

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

Routing

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

Pagination

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

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

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

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

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

Rate limiting

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

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

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

Payment plan Number of calls per hour per user
Free 100
Standard 1000
Enterprise 10000

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

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

Errors

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

HTTP status code summary

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

Users

User

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

Get all users

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

The response will be an array of users.

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

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

HTTP Request

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

organizationId in header

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

Get a user

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

The response returns a user object.

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

This endpoint retrieves a specific user.

HTTP Request

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

Query Parameters

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

Organizations

Organization

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

Organization roles

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

Organization members

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

Get all organizations

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

The response will be an array of organizations.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "organizationId" : "67973f72db34592d8fc96c48",
        "name" : "My organization",
        "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",
        "sharedToUsers": [{
            "userId" : "fB6bJr5TbaKLiofns",
            "role" : "administrator",
            "joinDate" : "2016-02-10T14:25:58.745Z"
        }]
    }

This endpoint retrieves a specific organization.

HTTP Request

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

organizationId in header

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

Query Parameters

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

Create an organization

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

The response will be the created organization.

    {
        "organizationId" : "67973f72db34592d8fc96c48",
        "name" : "My organization",
        "sharedToUsers": [{
            "userId" : "fB6bJr5TbaKLiofns",
            "role" : "administrator",
            "joinDate" : "2016-02-10T14:25:58.745Z"
        }]
    }

This endpoint creates a new organization.

HTTP Request

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

Request Parameters

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

Organization user share object parameters

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

Update an organization

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

The response will be the updated organization.

    {
        "organizationId" : "67973f72db34592d8fc96c48",
        "name" : "My organization",
        "sharedToUsers": [{
            "userId" : "fB6bJr5TbaKLiofns",
            "role" : "administrator",
            "joinDate" : "2016-02-10T14:25:58.745Z"
        }]
    }

This endpoint updates an existing organization.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Organization user share object parameters

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

Collections

Collection

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

Collection background

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

Collection public sharing

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

Collection roles

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

Collection members

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

Get all collections

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

The response will be a paginated list of collections.

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Get a collection

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

The response returns a collection object.

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

This endpoint retrieves a specific collection.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Create a collection

curl -X POST "https://favro.com/api/v1/collections" \
    -d '{
        "name": "My collection",
        "starPage": true,
        "publicSharing": "users",
        "background": "purple",
        "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,
        "fullMembersCanAddWidgets": true
    }

This endpoint creates a new collection.

HTTP Request

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

organizationId in header

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

Request Parameters

Parameter Type Description
name string The name of the collection. Required.
starPage boolean Star the collection for authorized user. Defaults to false.
publicSharing string Public share role for the collection. Refer to collection public sharing.
background string The background color of the collection. Refer to collection background.
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.

Collection user share object parameters

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

Update a collection

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

The response will be the updated collection.

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

This endpoint updates an existing collection.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Collection user share object parameters

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

Delete a collection

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

This endpoint deletes a specific collection.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Widgets

Widget

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

Widget types

Value Description
backlog A backlog consists of only one list of cards.
board A board consists of one or more lists of cards organised into columns.

Widget roles

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

Widget colors

Value
blue
lightgreen
brown
purple
orange
yellow
gray
red
cyan
green

Get all widgets

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

The response will be a paginated array of widgets.

{
    "limit": 100,
    "page": 0,
    "pages": 1,
    "requestId": "8cc57b1d8a218fa639c8a0fa",
    "entities": [{
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false
    }]
}

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Get a widget

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

The response returns a widget object.

    {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false
    }

This endpoint retrieves a specific widget.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Create a widget

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

The response will be the created widget.

    {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false
    }

This endpoint creates a new widget.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Update a widget

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

The response will be the updated widget.

    {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false
    }

This endpoint updates an existing widget.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Delete a widget

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Columns

Column object

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

Get all columns

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

The response will be a paginated array of columns.

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Get a column

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

The response returns a column object.

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

This endpoint retrieves a specific column.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Create a column

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

The response will be the created column.

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Update a column

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

The response will be the updated column.

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

This endpoint updates an existing column.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Delete a column

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Cards

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

Card

Field Type Description
cardId string The id of the card.
organizationId string The id of the organization that this card exists in.
widgetCommonId string The shared id of the widget that this card exists on. Only returned if the card does not exist in a todo list.
todoListUserId string The user id of the user of the todo list that this card exists in. Only returned if the card exists in a todo list. Otherwise widgetCommonId will be returned.
todoListCompleted boolean Returns ‘true’ if the card exists in a todo list and has been completed by that user.
columnId string The id of the column that this card exists in. Only returned if the card exists on a board.
laneId string The id of the lane that this card exists in. Only returned if the card exists on a board and the board has the Lanes app enabled.
parentCardId string The id of the parent card. Only returned if the card exists in a backlog 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 The position of the card in the column or backlog in relation to other cards.
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.
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 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.

Card custom fields

Field Type Description
customFieldId string The id of the custom field.
customValue 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 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.

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.

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",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    }]
}

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

HTTP Request

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

organizationId in header

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

Request Parameters

Parameter Type Description
todoList boolean Return cards from todolist only. Defaults to false.
cardCommonId string The common id of the card to filter by.
cardSequentialId string The sequential id of the card to be retrieved.
widgetCommonId string The common id of the widget to filter by.
columnId string The id of the column to filter by.
collectionId string The id of the collection to filter by.
unique boolean If true, return unique cards only. Defaults to false.
archived boolean If true, return archived cards.

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",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    }

This endpoint retrieves a specific card.

HTTP Request

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

organizationId in header

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

Request Parameters

Parameter Type Description
cardId string The id of the card to be retrieved. Required.

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",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    }

This endpoint creates a new card.

HTTP Request

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

organizationId in header

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

Request Parameters

Parameter Type Description
widgetCommonId string The widgetCommonId to create the card on. If not set, the card will be created in the user’s todo list.
laneId string 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 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 If creating a card on a backlog widget, it is possible to create this card as a child of the card specified by this parameter. Optional.
name string The name of the card. Required.
detailedDescription string The detailed description of the card. Supports formatting.
position decimal Position of the card in the list.
assignmentIds array The list of assignments (array of userIds). Optional.
tags array 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 The list of tag IDs, that will be added to card.
startDate string The start date of card. Format ISO-8601.
dueDate string The due date of card. Format ISO-8601.
tasklists array The list of card tasklists.
customFields array The list of card custom field parameters.

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",
        "customFields": [{
            "customFieldId": "kj4qQzhLMJ73dybBR",
            "total": 50400000,
            "reports": {
                "XTdS5bP6qX9Ta3rwt": {
                    "reportId": "29ed6478b55f90d91c5f4727",
                    "createdAt": "2016-01-13T00:00:00.000Z",
                    "value": 50400000,
                    "description": "Timesheet report description"
                }
            }
        }],
        "archived": false,
        "timeOnBoard": {
            "time": 72000000,
            "isStopped": true
        },
        "timeOnColumns": {
            "b4d8c6283d9d58f9a39108e7": 54000000,
            "as4d566783d9d58onuf8538f": 18000000
        }
    }

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

HTTP Request

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

organizationId in header

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

Request Parameters

Parameter Type Description
cardId string The id of the card to update. Required.
name string The name of the card.
detailedDescription string The detailed description of the card. Supports formatting.
widgetCommonId string The widgetCommonId to commit the card in. Optional.
laneId string 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 The columnId to commit the card in. It must belong to the widget specified in the widgetCommonId parameter. Optional.
parentCardId string If commiting a card on a backlog widget, it is possible to create this card as a child of the card specified by this parameter. Optional.
dragMode string ‘commit’ to commit card, ‘move’ to move card. ‘commit’ by default.
position decimal Position of the card in the list. If moving or committing it specifies on which position card will be moved to.
addAssignmentIds array The list of assignments, that will be added to card (array of userIds). Optional.
removeAssignmentIds array The list of assignments, that will be removed from card (array of userIds). Optional.
completeAssignments array The list of card assignment, that will update their statuses accordingly. Optional.
addTags array 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.
addTagIds array A list of tagIds that will be added to card.
removeTags array The list of tag names, that will be removed from card.
removeTagIds array The list of tag IDs, that will be removed from card.
startDate string The start date of card. Format ISO-8601. If null, start date will be removed.
dueDate string The due date of card. Format ISO-8601. If null, due date will be removed.
addTasklists array The list of card tasklists, that will be added to card.
removeAttachments array The list of card attachments URLs, that will be removed from the card.
customFields array The list of card custom field parameters, that will be added or modified.
addFavroAttachments array The list of card favro attachment that will be added to the card.
removeFavroAttachmentIds array The list of cardCommonId and widgetCommonId of card favro attachment, that will be removed from the card.
archive boolean Archive or unarchive card.

Delete a card

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

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

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

This endpoint deletes a specific card.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Activities

Activity object

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

Get card activities

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

The response will be a paginated array of activities.

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Tags

Tag

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

Tag colors

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

Get all tags

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

The response will be a paginated array of tags.

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Get a tag

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

The response returns a tag object.

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

This endpoint retrieves a specific tag.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Create a tag

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

The response will be the created tag.

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

This endpoint creates a new tag on a card.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Update a tag

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

The response will be the updated tag.

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

This endpoint updates an existing tag.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Delete a tag

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

This endpoint deletes a specific tag.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Tasks

Tasks are the API name for checklist items in Favro.

Task

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

Get all tasks

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

The response will be a paginated array of card tasks.

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Get a task

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

The response returns a task object.

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

This endpoint retrieves a specific task.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Create a task

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

The response will be the created task.

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

This endpoint creates a new task on a card.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Update a task

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

The response will be the updated task.

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

This endpoint updates an existing task.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Delete a task

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

This endpoint deletes a specific task.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Tasklists

Tasklists are the API name for checklists in Favro.

Task List

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

Get all tasklists

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

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

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Get a task list

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

The response returns a task list object.

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

This endpoint retrieves a specific task list.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Create a task list

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

The response will be the created task list.

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

This endpoint creates a new task list on a card.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Update a task list

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

The response will be the updated task list.

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

This endpoint updates an existing task list.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Delete a task list

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

This endpoint deletes a specific task list.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Comments

Comment object

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

Get all comments

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

The response will be a paginated array of comments.

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Get a comment

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

The response returns a comment object.

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

This endpoint retrieves a specific comment.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Create a comment

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

The response will be the created comment.

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

This endpoint creates a new comment on a card.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Update a comment

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

The response will be the updated comment.

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

This endpoint updates an existing comment.

HTTP Request

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

organizationId in header

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

Request Parameters

Parameter Type Description
commentId string The id of the comment to update.
comment string The body of the comment to edit.

Delete a comment

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

This endpoint deletes a specific comment.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Attachments

Upload a file

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 Card attachment.

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Query Parameters

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

Custom fields

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.

Custom field object

Field Type Description
organizationId string The id of the organization that this custom field exists in.
customFieldId string The id of the custom field.
type string Custom field type. Refer to allowed custom field types.
name string The name of the custom field.
enabled boolean True if the custom field is currently enabled for the organization.

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
blue
purple
cyan
green
lightgreen
yellow
orange
red
brown
gray

Get all custom fields

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

The response will be a paginated array of custom fields.

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

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

HTTP Request

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

organizationId in header

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

Get a custom field

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

The response returns a custom field object.

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

This endpoint retrieves a specific custom field.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Groups

Group

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

Group roles

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

Group members

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

Get all groups

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

The response will be a paginated array of groups.

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

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

HTTP Request

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

organizationId in header

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

Get a group

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

The response returns a group object.

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

This endpoint retrieves a specific group.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Create a group

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

The response will be the created group.

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

This endpoint creates a new group.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Update a group

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

The response will be the updated group.

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

This endpoint updates an existing group.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Group user share object parameters

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

Delete a group

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

This endpoint deletes a specific group.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Outgoing webhooks

Webhook

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

Webhook options

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

Webhook notifications

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

Get all webhooks

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

The response will be an array of configured webhooks.

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

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

HTTP Request

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

organizationId in header

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

Request Parameters

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

Create a webhook

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

The response will be the created webhook.

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

This endpoint creates a new webhook.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Webhook options object parameters

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

Delete a webhook

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

This endpoint deletes a specific webhook.

HTTP Request

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

organizationId in header

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

Request Parameters

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

Webhook signatures

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

Webhook responses

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

Ping event

Example payload:

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

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

Payload fields

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

Card created event

Example payload:

{
    "payloadId": "ZnvqwjdLh1wmbnEj6vOfHhv8ARY=",
    "action": "created",
    "card": {
        "cardId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "widgetCommonId": "ff440e8f358c08513a86c8d6",
        "columnId": "b4d8c6283d9d58f9a39108e7",
        "name": "This is a card",
        "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
    }
}

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",
        "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
    },
    "sourceWidget": {
        "widgetCommonId": "67973f72db34592d8fc96c48",
        "organizationId": "zk4CJpg5uozhL4R2W",
        "collectionIds": [
            "8cc57b1d8a218fa639c8a0fa"
        ],
        "name": "This is a widget",
        "type": "board",
        "color": "purple",
        "ownerRole": "fullMembers",
        "editRole": "guests",
        "archived": false
    }
}

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",
        "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
    }
}

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",
        "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",
        "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",
        "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",
        "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",
        "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 First Name and Last Name attributes in the SAML assertion.

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

SCIM 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" }
        ],
        "groups": [],
        "meta": {
            "resourceType": "User",
            "created": "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" }
        ],
        "groups": [],
        "meta": {
            "resourceType": "User",
            "created": "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": {
                "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" }
        ],
        "groups": [],
        "meta": {
            "resourceType": "User",
            "created": "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 Parameters

Parameter Type Description
userName string The email for the new user. The domain must match the bearer token. Required.
name object The name for the new user. Favro uses the “formatted” parameter. Required.
entitlements array Array of objects with additional attributes. FavroRole attribute with value Guest can be used to provision user as a guest.

Update user

curl -X PUT "https://favro.com/api/scim/v1/Users/XL7tBffEMcasFPeQy" \
    -H "Content-Type: application/json" \
    -d '{
        "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",
        "location": "http://localhost:3000/api/scim/v1/Users/XL7tBffEMcasFPeQy"
    }
}

Updates a user

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

Request Parameters

Parameter Type Description
name object The new name for the user. Favro uses the “formatted” parameter.
active boolean Activates or disables the user. Defaults to false.
entitlements array Array of objects with additional attributes. FavroRole attribute with value Guest can be used to provision user as a guest.

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",
        "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",
        "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",
        "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 to add or remove. 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",
    "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 to add or remove. Required.
operation string The operation to perform, “add” or “delete”.

Add or remove members

curl -X PATCH "https://favro.com/api/scim/v1/Groups/6digk8JrQs2m4p4eY" \
    -H "Content-Type: application/json" \
  -d '{
    "members": [{
      "value": "XL7tBffEMcasFPeQy"
    }]
  }' \
    -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",
    "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