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

General

General methods

Return organization information

Returns the name of your organization as a string.

Authorizations:

Responses

200

Successful operation

401

Invalid authorization response

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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Example organization"
}

Projects

Access and update projects in your organization.

Return projects in organization

Returns a list of projects in your organization. You can sort them by any fields, or return only selected projects.

Authorizations:
query Parameters
sort
any

Pick the order in which the projects will be returned. You can sort by any field: ?sort=name will return a list of projects 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 projects you want to be returned. By default, all of the projects are returned.

archived
integer

Filter the archived projects. By default, all of the projects are returned.

Responses

200

Successful operation

401

Invalid authorization response

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

Response samples

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

Add a new project

Authorizations:
Request Body schema: application/json
name
required
string (Project name) <= 100 characters

Project name.

color
string

Color in hex format.

archived
any <boolean>

Project archived flag.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

422

Invalid input

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Example project",
  • "color": "string",
  • "archived": false
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "name": "Example project",
  • "color": "string",
  • "archived": false
}

Return a single project from your organization

Return any single project from your organization using its ID.

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

ID of a project you want to get.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "name": "Example project",
  • "color": "string",
  • "archived": false
}

Update a project

Change information about any of the projects in your organization.

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

ID of a project you want to update.

Request Body schema: application/json
name
required
string (Project name) <= 100 characters

Project name.

color
string

Color in hex format.

archived
any <boolean>

Project archived flag.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

422

Invalid input

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Example project",
  • "color": "string",
  • "archived": false
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "name": "Example project",
  • "color": "string",
  • "archived": false
}

Resources

Access and update data concerning resources: team members and basic resources added to your organization.

Return resources in organization

Returns a list of team members and basic resources from your organization. You can sort them by any fields, or return only selected resources.

Authorizations:
query Parameters
sort
any

Pick the order in which the resources will be returned. You can sort by any field: ?sort=name will return a list of resources 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 resources you want to be returned. By default, all of the resources are returned.

active
integer
Default: 1

Filter the active resources. By default is 1

email
string

Filter the emails of the resources you want to be returned.

Responses

200

Successful operation

400

Invalid request response

401

Invalid authorization response

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

Response samples

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

Add a new basic resource

Add a new basic resource, a resource with no email access to the app but listed in the Calendar.

Authorizations:
Request Body schema: application/json
name
string (Resource name) <= 255 characters

Resource name

active
any <boolean>

Resource active flag

is_part_time
boolean

Flag set to true if it is a part-time resource.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

422

Invalid input

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Example resource",
  • "active": false,
  • "is_part_time": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "name": "Example resource",
  • "active": false,
  • "avatar": "string",
  • "is_part_time": true,
  • "is_visible": true,
  • "email": null
}

Return single resource from organization

Return data of a single resource of your choosing.

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

ID of a resource you want to get.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "name": "Example resource",
  • "active": false,
  • "avatar": "string",
  • "is_part_time": true,
  • "is_visible": true,
  • "email": null
}

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}

Time Entries

All of the entries in Teamdeck’s timesheets are called Time Entries. They represent tracked time (using Teamdeck’s time tracker or added manually). This API allows you to access and update information about your team’s time entries.

Return time entries in organization

Returns a list of time entries in your organization.

Authorizations:
query Parameters
sort
any

Pick the order in which the time entries should be returned. You can sort by any field: ?sort=start_date will return a list of time entries 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

All entries have resources assigned to them. Filter entries by entering resource_id values of your choosing. Multiple IDs can be passed as comma-separated values. By default, all of the entries are returned.

project_id
integer

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

start_date_from
date

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

start_date_to
date

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

end_date_from
date

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

end_date_to
date

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

Responses

200

Successful operation

401

Invalid authorization response

422

Invalid input

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

Response samples

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

Add a new time entry assigned to any resource within your organization.

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.

minutes
required
int64

The length of a time entry in minutes.

weekend_booking
boolean
Default: false

This is set to false by default, meaning that this time entry is set not to be added to a weekend day. true signifies time entries that don’t take weekends into account.

holidays_booking
boolean
Default: false

This is set to false by default, meaning that this time entry is set not to be added to a holiday. true signifies time entries that don’t take holidays into account.

vacations_booking
boolean
Default: false

This is set to false by default, meaning that this time entry is set not to be added to a vacation (personal time off of a given resource). true signifies time entries that don’t take vacations into account.

description
string

Description of a time entry.

start_date
required
date <YYYY-MM-DD>

Starting date of a time entry.

end_date
required
date <YYYY-MM-DD>

End date of a time entry.

creator_resource_id
integer (Resource identifier)

ID of the resource who has created this time entry.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

422

Invalid input

post /time-entries
This is Teamdecks Public API documentation
https://api.teamdeck.io/v1/time-entries

Request samples

application/json
Copy
Expand all Collapse all
{
  • "resource_id": 1,
  • "project_id": 1,
  • "minutes": 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,
  • "minutes": 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 time entry from organization

Return a single time entry from your organization based on its ID.

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

ID of the time entry you want to get.

Responses

200

Successful operation

401

Invalid authorization response

403

Invalid token rights response

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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "resource_id": 1,
  • "project_id": 1,
  • "minutes": 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
}