Teamdeck API (0.0.1)

Download OpenAPI specification:Download

Introduction

Teamdeck API is a RESTful interface, which allows you to access and update much of your data in the app.

Responses (including errors) are returned in JSON format. We use built-in HTTP features, like HTTP verbs, to receive commands and return responses. The API is designed to have predictable, resource-oriented URLs.

Authentication

In order to authorize your account, you need to generate a token.

Log in to your Teamdeck account and go to Settings > Integrations > API keys.

Note: You have to be an owner of your Teamdeck organization to access this tab.

Type in the name of your token, select the permission you want to receive and click the plus icon.

There are two permission types in Teamdeck:

  • read - allows you to read the data using the GET method
  • read + write - allows you to read & modify the data using the GET, PUT, POST & DELETE methods

api_key

In order to authenticate Teamdeck API, send a request with the following HTTP header:

Security scheme type: API Key
header parameter name: X-Api-Key

Errors

Teamdeck uses standard HTTP response codes to indicate API errors or successful requests:

  • 2xx - the request was fulfilled successfully,
  • 4xx - there was an issue with the request that was sent,
  • 5xx - there is a server-side problem - something went wrong on Teamdeck’s end.

Rate limiting

Teamdeck accounts are subject to rate limiting: 5000 requests per hour per key.

Webhooks

Important changes happening in your Teamdeck account are recorded as events. For example, each time a new project is added, an event is created.

You can listen to these events and be notified about changes in your organization by configuring Webhook URL.

Log in to your Teamdeck account and go to Settings > Integrations > Webhooks.

Note: You have to be an owner of your Teamdeck organization to access this tab.

Here you can paste a payload URL and name it. You can create multiple webhooks, but all of the events (listed below) will be sent to any webhook you set up.

Note: You have to use HTTPS in your webhook URL.

Retry policy: In an event your request fails (the response status > 300), we will try sending a request after 30 seconds, and then the last one 60 seconds later.

The events are returned in JSON format, following this basic structure:

  {
    "id": 1,
    "type": "booking_created",
    "date": "2018-01-01 15:00:00",
    "creator_resource_id": 1,
    "data": {
      "id": 1,
      ...
    }
  }

The following events are available:

Event type Description
booking_created New booking created
booking_updated Booking updated
booking_deleted Booking deleted
time_entry_created New time entry created
time_entry_updated Time entry updated
time_entry_deleted Time entry deleted
vacation_created New vacation created
vacation_updated Vacation updated
vacation_deleted Vacation deleted
project_created New project created
project_updated Project updated

Bookings

When you plan your team’s work in Teamdeck, every assignment is called a booking. Bookings are always assigned to resources and projects, have a start and end data, as well as a specified daily duration.

Return bookings in organization

Returns a list of bookings in your organization.

Authorizations:
query Parameters
sort
any

Pick the order in which the bookings will be returned. You can sort by any field: ?sort=start_date will return a list of bookings sorted by their starting dates in ascending order, whereas ?sort=-start_date will return a list in descending order.

fields
any

Select the fields you want to be returned. By default, all of the fields are returned.

page
integer
Default: 0

Select the page you want to display. By default, this is set to 0.

resource_id
integer

Filter the resource_id values of the bookings you want to be returned. Multiple IDs can be passed as comma-separated values. By default, all of the bookings are returned.

project_id
integer

Filter the project_id values of the bookings you want to be returned. Multiple IDs can be passed as comma-separated values. By default, all of the bookings are returned.

start_date_from
date

Filter bookings by their start_date field. Use the YYYY-MM-DD format.

start_date_to
date

Filter bookings by their start_date field. Use the YYYY-MM-DD format.

end_date_from
date

Filter bookings by their end_date field. Use the YYYY-MM-DD format.

end_date_to
date

Filter bookings by their end_date field. Use the YYYY-MM-DD format.

Responses

200

Successful operation

401

Invalid authorization response

422

Invalid input

get /bookings
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/bookings

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Add a new booking

Authorizations:
Request Body schema: application/json
resource_id
required
integer (Resource identifier)

ID of the resource assigned to this entry.

project_id
required
integer (Project identifier)

ID of the project assigned to this entry.

hours
required
int64

The length of a booking in hours.

weekend_booking
boolean
Default: false

This is set to false by default, meaning that the booking is set not to happen during a weekend day. true signifies bookings that don’t take weekends into account.

holidays_booking
boolean
Default: false

This is set to false by default, meaning that the booking is is set not to happen during a holiday. true signifies bookings that don’t take holidays into account.

vacations_booking
boolean
Default: false

This is set to false by default, meaning that the booking is is set not to happen during a vacation (personal time off of a given resource). true signifies bookings that don’t take vacations into account.

description
string

Description of a booking.

start_date
required
date <YYYY-MM-DD>

Starting date of a booking.

end_date
required
date <YYYY-MM-DD>

End date of a booking.

creator_resource_id
integer (Resource identifier)

ID of the resource who has created this booking.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

422

Invalid input

post /bookings
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/bookings

Request samples

application/json
Copy
Expand all Collapse all
{
  • "resource_id": 1,
  • "project_id": 1,
  • "hours": 8,
  • "weekend_booking": true,
  • "holidays_booking": true,
  • "vacations_booking": true,
  • "description": "string",
  • "start_date": "2018-07-01",
  • "end_date": "2018-07-01",
  • "creator_resource_id": 1
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "resource_id": 1,
  • "project_id": 1,
  • "hours": 8,
  • "weekend_booking": true,
  • "holidays_booking": true,
  • "vacations_booking": true,
  • "description": "string",
  • "start_date": "2018-07-01",
  • "end_date": "2018-07-01",
  • "creator_resource_id": 1
}

Return single booking from organization

Return a single booking from your organization based on its ID.

Authorizations:
path Parameters
id
required
integer (Booking identifier)
Example: 1

ID of a booking you want to get.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

get /bookings/{id}
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/bookings/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "resource_id": 1,
  • "project_id": 1,
  • "hours": 8,
  • "weekend_booking": true,
  • "holidays_booking": true,
  • "vacations_booking": true,
  • "description": "string",
  • "start_date": "2018-07-01",
  • "end_date": "2018-07-01",
  • "creator_resource_id": 1
}

Update booking

Update information about any booking within your organization.

Authorizations:
path Parameters
id
required
integer (Booking identifier)
Example: 1

ID of a booking you want to update.

Request Body schema: application/json
resource_id
required
integer (Resource identifier)

ID of the resource assigned to this entry.

project_id
required
integer (Project identifier)

ID of the project assigned to this entry.

hours
required
int64

The length of a booking in hours.

weekend_booking
boolean
Default: false

This is set to false by default, meaning that the booking is set not to happen during a weekend day. true signifies bookings that don’t take weekends into account.

holidays_booking
boolean
Default: false

This is set to false by default, meaning that the booking is is set not to happen during a holiday. true signifies bookings that don’t take holidays into account.

vacations_booking
boolean
Default: false

This is set to false by default, meaning that the booking is is set not to happen during a vacation (personal time off of a given resource). true signifies bookings that don’t take vacations into account.

description
string

Description of a booking.

start_date
required
date <YYYY-MM-DD>

Starting date of a booking.

end_date
required
date <YYYY-MM-DD>

End date of a booking.

creator_resource_id
integer (Resource identifier)

ID of the resource who has created this booking.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

422

Invalid input

put /bookings/{id}
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/bookings/{id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "resource_id": 1,
  • "project_id": 1,
  • "hours": 8,
  • "weekend_booking": true,
  • "holidays_booking": true,
  • "vacations_booking": true,
  • "description": "string",
  • "start_date": "2018-07-01",
  • "end_date": "2018-07-01",
  • "creator_resource_id": 1
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "resource_id": 1,
  • "project_id": 1,
  • "hours": 8,
  • "weekend_booking": true,
  • "holidays_booking": true,
  • "vacations_booking": true,
  • "description": "string",
  • "start_date": "2018-07-01",
  • "end_date": "2018-07-01",
  • "creator_resource_id": 1
}

Delete single booking from organization

Delete a booking using its ID.

Authorizations:
path Parameters
id
required
integer (Booking identifier)
Example: 1

ID of a booking you want to delete.

Responses

204

Successful operation

401

Invalid authorization response

403

Invalid token rights response

delete /bookings/{id}
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/bookings/{id}

Custom fields

Teamdeck’s API allows you to access custom fields defined in your organization. In order to access their values check Custom field values section.

Example flow:

Imagine you have a custom field called Job Title and you want to retrieve the job title of one of your resources. First, you should get the list of your custom fields, find the “job title” custom field and after that send request to:

custom-field-values/custom-field/{ID of found custom field}/resource/{ID of resource whose job title you want to check}

Return custom fields in organization

Returns a list of custom fields from your organization. You can sort this list by any field, or return only selected custom fields.

Authorizations:
query Parameters
sort
any

Pick the order in which the custom fields will be returned. You can sort by any field: ?sort=name will return a list of custom fields sorted by their names in ascending order, whereas ?sort=-name will return a list in descending order.

fields
any

Select the fields you want to be returned. By default, all of the fields are returned.

page
integer
Default: 0

Select the page you want to display. By default, this is set to 0

name
string

Filter the names of the custom fields you want to be returned. By default, all of the custom fields are returned.

related_table
string

Filter custom fields by the table they’re related to (either projects or resources). By default, all of the custom fields are returned.

Responses

200

Successful operation

400

Invalid request response

401

Invalid authorization response

get /custom-fields
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/custom-fields

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Return single custom field from organization

Return a single custom field of your choosing.

Authorizations:
path Parameters
id
required
integer (Custom field identifier)
Example: 1

ID of a custom field you want to get.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

get /custom-fields/{id}
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/custom-fields/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "type": 0,
  • "name": "string",
  • "required": true,
  • "related_table": "string"
}

Custom field values

Teamdeck’s API allows you to access the values of custom fields defined in your organization. The custom fields themselves can also be returned - check Custom fields to learn more.

Example flow:

Imagine you have a custom field called Job Title and you want to retrieve the job title of one of your resources. First, you should get the list of your custom fields, find the “job title” custom field and after that send request to:

custom-field-values/custom-field/{ID of found custom field}/resource/{ID of resource whose job title you want to check}

Return custom field values in organization

Returns a list of custom field values from your organization. You can sort them by any fields, or return only selected custom field values.

Authorizations:
query Parameters
sort
any

Pick the order in which the custom field values will be returned. You can sort by any field: ?sort=value will return a list of custom field values sorted by their values in ascending order, whereas ?sort=-value will return a list in descending order.

fields
any

Select the fields you want to be returned. By default, all of the fields are returned.

page
integer
Default: 0

Select the page you want to display. By default, this is set to 0

custom_field_id
string

Filter the list by the custom field these custom field values belong to. By default, all of the custom field values are returned.

Responses

200

Successful operation

400

Invalid request response

401

Invalid authorization response

get /custom-field-values
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/custom-field-values

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Return custom field values from a chosen custom field & resource

Returns custom field values from a chosen custom field assigned to a chosen resource. You can sort them by any fields, or return only selected custom field values.

Authorizations:
query Parameters
sort
any

Pick the order in which the custom field values will be returned. You can sort by any field: ?sort=value will return a list of custom field values sorted by their values in ascending order, whereas ?sort=-value will return a list in descending order.

fields
any

Select the fields you want to be returned. By default, all of the fields are returned.

page
integer
Default: 0

Select the page you want to display. By default, this is set to 0

custom_field_id
required
string

Select the custom field of the values you want to return.

resource_id
required
string

Select the resource whose custom field values you want to return.

Responses

200

Successful operation

400

Invalid request response

401

Invalid authorization response

get /custom-field-values/custom-field/{custom_field_id}/resource/{resource_id}
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/custom-field-values/custom-field/{custom_field_id}/resource/{resource_id}

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Return custom field values from a chosen custom field & project

Returns custom field values from a chosen custom field assigned to a chosen project. You can sort them by any fields, or return only selected custom field values.

Authorizations:
query Parameters
sort
any

Pick the order in which the custom field values will be returned. You can sort by any field: ?sort=value will return a list of custom field values sorted by their values in ascending order, whereas ?sort=-value will return a list in descending order.

fields
any

Select the fields you want to be returned. By default, all of the fields are returned.

page
integer
Default: 0

Select the page you want to display. By default, this is set to 0

custom_field_id
required
string

Select the custom field of the values you want to return.

project_id
required
string

Select the project which custom field values you want to return.

Responses

200

Successful operation

400

Invalid request response

401

Invalid authorization response

get /custom-field-values/custom-field/{custom_field_id}/project/{project_id}
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/custo