Teamwork Desk is the help desk of Teamwork.com: emails and other channels arrive in inboxes and become tickets, handled by agents, classified by status, priority, type and tags, and measured against SLAs and satisfaction ratings. This connector reads your site’s data through the official Teamwork Desk API (v2) and brings your tickets with their whole conversation (messages), your customers and companies, satisfaction ratings, time logs, users and inboxes, plus the help desk settings: tags, statuses, priorities, sources, types, SLAs, business hours, custom fields and canned responses.

The connector only reads data. It never creates, changes or deletes anything in Teamwork Desk.

Configuring Teamwork Desk as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Teamwork Desk option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

The Teamwork Desk API uses an API key created by a user of your site. To create one, open Teamwork Desk, click your avatar in the bottom left, click View Profile, go to API Keys and click Create an API key. Copy the key.

Teamwork Site Address: the address of your Teamwork site, as shown in your browser when Teamwork Desk is open, without the /desk part. For example https://acme.teamwork.com, https://acme.eu.teamwork.com if your site is hosted in the EU, or your custom domain such as https://support.example.com. Only https addresses are accepted.
API Key: the key copied from Teamwork Desk.
Start Date: the earliest date synced on the first sync and on full syncs. Tickets (with their messages), customers, companies, satisfaction ratings and time logs last updated since this date are loaded. Users, inboxes and the help desk settings are always loaded whole.

The connector sees exactly what the user who created the API key sees. Create the key with a user that has access to every inbox you want to sync; tickets of inboxes that user cannot open are not loaded. If the key is deleted, or the user loses access, update the API Key of this source.

Teamwork Desk allows 120 requests per minute per site, shared by every integration of your site. The connector stays at 100 per minute and waits when Teamwork Desk asks it to, so a long history takes a while on the first sync.

Once you’re done, click Next.

2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

Tip: The stream can be found more easily by typing its name.

Select the streams and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
Sync Type: keep the suggested type. Tickets, Ticket Messages, Customers, Companies, Happiness Ratings and Time Logs are Incremental: each sync reads only what changed since the previous one and merges it into the table. The other tables are Full table: each sync reads them whole and replaces the table.

Avoid setting Ticket Messages to Full table. Teamwork Desk lists messages one ticket at a time, so every sync would read again the messages of every ticket updated since the Start Date, which takes hours on a large help desk.

Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Tickets are read incrementally, so an hourly or daily sync works well. Optionally, you can configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here. Once you are ready, click Next to finalize the setup.

5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

For you to be able to see it on your Catalog, you need at least one successful source run.

Streams and Fields

Available streams

The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description.

Stream	Slug	Sync	Description
Tickets	`tickets`	Incremental	Tickets of every state with inbox, status, priority, type, agent, customer, SLA and response times.
Ticket Messages	`ticket_messages`	Incremental	Replies, notes, forwards and events of each ticket, with text and HTML body.
Customers	`customers`	Incremental	People who contact your help desk, with contact details and company.
Companies	`companies`	Incremental	Companies and groups of customers.
Happiness Ratings	`happiness_ratings`	Incremental	Satisfaction ratings given to tickets, with the comment.
Time Logs	`timelogs`	Incremental	Time logged by agents on tickets.
Users	`users`	Full table	Agents and admins, archived ones included.
Inboxes	`inboxes`	Full table	Inboxes and their settings.
Tags	`tags`	Full table	Ticket tags.
Ticket Priorities	`ticket_priorities`	Full table	Ticket priorities.
Ticket Statuses	`ticket_statuses`	Full table	Ticket statuses.
Ticket Sources	`ticket_sources`	Full table	Ticket channels.
Ticket Types	`ticket_types`	Full table	Ticket types.
SLAs	`slas`	Full table	Service level agreements.
Business Hours	`business_hours`	Full table	Business hours used by SLAs.
Custom Fields	`custom_fields`	Full table	Custom field definitions.
Custom Field Options	`custom_field_options`	Full table	Options of dropdown and checkboxes custom fields.
Happiness Rating Options	`happiness_rating_options`	Full table	Answers of the satisfaction rating.
Canned Responses	`canned_responses`	Full table	Saved replies.

Tables join on their ids: ticket_messages.ticket_id, happiness_ratings.ticket_id and timelogs.ticket_id = tickets.id; tickets.customer_id = customers.id; customers.company_id and tickets.company_id = companies.id; tickets.inbox_id = inboxes.id; tickets.status_id, priority_id, type_id and source_id = the id of Ticket Statuses, Ticket Priorities, Ticket Types and Ticket Sources; tickets.agent_id and timelogs.user_id = users.id; custom_field_options.custom_field_id = custom_fields.id; happiness_ratings.happiness_rating_option_id = happiness_rating_options.id.

Fields by stream

Fields marked String (JSON) hold a nested object or list as JSON text; use your warehouse’s JSON functions to read them. Lists of related records (for example tickets.tags) come as JSON arrays of {"id": ..., "type": ...} objects; join the ids with the matching table. Dates and times are in UTC.

Tickets

Help desk tickets of every state (active, scheduled, merged and deleted) updated since the Start Date, with their inbox, status, priority, type, source, agent, customer, SLA and counters. Each sync reads the tickets changed (or deleted) since the previous one.Table: tickets · Primary key: id · Sync: Incremental (updated_at)

Field	Type	Description
`id`	Integer	Unique identifier of the ticket (the ticket number shown in Teamwork Desk).
`subject`	String	Subject of the ticket.
`preview_text`	String	Up to 255 characters of the most recent message of the ticket.
`summary`	String	Short description of the ticket generated by Teamwork Desk, used for search and similarity.
`inbox_id`	Integer	Id of the inbox the ticket belongs to (inboxes table).
`status_id`	Integer	Id of the ticket status (ticket_statuses table).
`priority_id`	Integer	Id of the ticket priority (ticket_priorities table).
`type_id`	Integer	Id of the ticket type (ticket_types table).
`source_id`	Integer	Id of the channel the ticket came from (ticket_sources table).
`agent_id`	Integer	Id of the agent the ticket is assigned to (users table).
`customer_id`	Integer	Id of the customer who opened the ticket (customers table).
`contact_id`	Integer	Id of the customer contact (email address or phone) the ticket came from.
`company_id`	Integer	Id of the company of the customer (companies table).
`sla_id`	Integer	Id of the SLA applied to the ticket (slas table).
`sla_breached_at`	Datetime	When the ticket is next expected to breach its SLA (UTC).
`business_hours_id`	Integer	Id of the business hours used for the ticket’s SLA (business_hours table).
`happiness_rating_id`	Integer	Id of the satisfaction rating given to the ticket (happiness_ratings table).
`happiness_survey_sent_at`	Datetime	When the satisfaction survey was sent to the customer (UTC).
`solved_by_id`	Integer	Id of the agent who solved the ticket.
`parent_ticket_id`	Integer	Id of the parent ticket, when this ticket is a child ticket.
`project_id`	Integer	Id of the Teamwork Projects project linked to the ticket.
`review_id`	Integer	Id of the review of the ticket.
`trend_id`	Integer	Id of the trend the ticket was grouped into.
`trend_rationale`	String	Why the ticket was grouped into its trend.
`trigger_id`	Integer	Id of the trigger that acted on the ticket.
`scheduled_email_id`	Integer	Id of the scheduled reply of the ticket.
`installation_id`	Integer	Id of the Teamwork Desk installation (site) of the ticket.
`original_recipient`	String	Email address the ticket was originally sent to.
`message_count`	Integer	Number of customer and agent replies in the ticket, including notes and forwards.
`response_time_mins`	Integer	Time to the first agent response, in minutes.
`resolution_time_mins`	Integer	Time to resolution, in minutes.
`is_read`	Boolean	Whether the ticket was read (by the user of the API key).
`readonly`	Boolean	Whether the ticket is closed and can no longer be replied to (inbox setting).
`images_hidden`	Boolean	Whether images of the ticket are hidden.
`inaccessible_child_tickets`	Boolean	Whether the ticket has child tickets in inboxes the API key’s user cannot see.
`archived_at`	Datetime	When the ticket was archived (UTC).
`spam_score`	Number	Spam score of the ticket.
`spam_rules`	String	Spam rules matched by the ticket.
`similarity_score`	Number	Vector similarity score of the ticket (search).
`suggestions`	String (JSON)	Reply suggestions for the ticket (JSON object).
`tags`	String (JSON)	Tags of the ticket: relationships with the tag id (JSON array; names in the tags table).
`custom_fields`	String (JSON)	Custom fields of the ticket: relationships with the custom field id and, in meta, the value when Teamwork Desk sends it (JSON array).
`files`	String (JSON)	Attachments on the messages of the ticket (JSON array of relationships).
`followers`	String (JSON)	Agents following the ticket (JSON array of relationships).
`messages`	String (JSON)	Replies of the ticket (JSON array of relationships; the messages themselves are in the ticket_messages table).
`activities`	String (JSON)	Activities of the ticket (JSON array of relationships).
`timelogs`	String (JSON)	Time logged on the ticket (JSON array of relationships; details in the timelogs table).
`tasks`	String (JSON)	Teamwork Projects tasks linked to the ticket (JSON array of relationships).
`child_tickets`	String (JSON)	Child tickets of the ticket (JSON array of relationships).
`merged_tickets`	String (JSON)	Tickets merged into this ticket (JSON array of relationships).
`pinned_notes`	String (JSON)	Pinned notes of the ticket (JSON array of relationships).
`shared_with`	String (JSON)	Users the ticket was shared with (JSON array of relationships).
`sla_tickets`	String (JSON)	SLA events of the ticket (JSON array of relationships).
`thread_email_refs`	String (JSON)	CC/BCC addresses of the ticket (JSON array of relationships).
`company_customers`	String (JSON)	Customers of the ticket’s company involved in the ticket (JSON array of relationships).
`review_comments`	String (JSON)	Review comments of the ticket (JSON array of relationships).
`created_by_type`	String	Kind of who created the ticket: users (an agent) or customers.
`state`	String	State of the ticket: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the ticket was created (UTC).
`created_by_id`	Integer	Id of the user who created the ticket.
`updated_at`	Datetime	When the ticket was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the ticket.
`deleted_at`	Datetime	When the ticket was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the ticket.

Ticket Messages

The conversation of each ticket: customer and agent replies, notes, forwards and events, with their text and HTML body. Each sync reads all the messages of the tickets changed since the previous one.Table: ticket_messages · Primary key: id · Sync: Incremental (ticket_updated_at)

Field	Type	Description
`id`	Integer	Unique identifier of the message.
`ticket_id`	Integer	Id of the ticket the message belongs to (tickets table).
`ticket_updated_at`	Datetime	Last update of the ticket when the message was read (UTC); used as the incremental replication key.
`thread_type`	Integer	Kind of message as a number (for example 1 is a message; notes, forwards and events have their own numbers).
`text_body`	String	Plain text body of the message.
`html_body`	String	HTML body of the message.
`edit_method`	String	Format the message was written in: html or markdown.
`email_message_id`	String	Message-ID of the email (RFC 2822).
`status_id`	Integer	Id of the ticket status set with this message.
`contact_id`	Integer	Id of the customer contact (email address or phone) the message came from.
`assigning_user_id`	Integer	Id of the user who assigned the ticket with this message.
`happiness_rating_id`	Integer	Id of the satisfaction rating attached to the message.
`helpdoc_id`	Integer	Id of the help doc article linked to the message.
`metadata_id`	Integer	Id of the metadata of the message.
`sentiment_id`	Integer	Id of the sentiment analysis of the message.
`sla_thread_id`	Integer	Id of the SLA event of the message.
`suggested_response_id`	Integer	Id of the AI suggested response used for the message.
`task_id`	Integer	Id of the Teamwork Projects task linked to the message.
`is_pinned`	Boolean	Whether the message is pinned.
`delayed`	Boolean	Whether the message is delayed (scheduled to be sent later).
`delivery_method`	String	How the message was delivered.
`delivery_reason`	String	Reason given for the delivery status.
`delivery_status`	String	Delivery status of the message.
`review_status`	String	Review status of the message.
`s3link`	String	Storage link of the original message.
`exclude_history`	Boolean	Whether the ticket history was left out of the message.
`merged_at`	Datetime	When the message was merged into another ticket (UTC).
`viewed_by_customer_at`	Datetime	Most recent time the customer viewed the message (UTC).
`agents_notified`	String (JSON)	Agents notified about the message (JSON array of relationships).
`files`	String (JSON)	Attachments of the message (JSON array of relationships).
`forwarded_messages`	String (JSON)	Messages forwarded with this one (JSON array of relationships).
`likes`	String (JSON)	Likes of the message (JSON array of relationships).
`reactions`	String (JSON)	Reactions to the message (JSON array of relationships).
`thread_email_refs`	String (JSON)	CC/BCC addresses of the message (JSON array of relationships).
`thread_reactions`	String (JSON)	Reactions to the message thread (JSON array of relationships).
`created_by_type`	String	Kind of who wrote the message: users (an agent) or customers.
`state`	String	State of the message: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the message was created (UTC).
`created_by_id`	Integer	Id of the user who created the message.
`updated_at`	Datetime	When the message was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the message.
`deleted_at`	Datetime	When the message was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the message.

Customers

Customers (the people who contact your help desk) updated since the Start Date, with their contact details and company.Table: customers · Primary key: id · Sync: Incremental (updated_at)

Field	Type	Description
`id`	Integer	Unique identifier of the customer.
`first_name`	String	First name of the customer.
`last_name`	String	Last name of the customer.
`email`	String	Main email address of the customer; ticket replies are sent to it.
`organization`	String	Name of the organization the customer belongs to.
`company_id`	Integer	Id of the company of the customer (companies table).
`job_title`	String	Job title of the customer.
`phone`	String	Phone number of the customer.
`mobile`	String	Mobile number of the customer.
`address`	String	Address of the customer.
`avatar_url`	String	URL of the customer’s avatar.
`linkedin_url`	String	LinkedIn URL of the customer.
`facebook_url`	String	Facebook URL of the customer.
`twitter_handle`	String	Twitter handle of the customer.
`external_id`	String	External id of the customer (a reference from another system).
`extra_data`	String	Free-form reference field for additional customer data.
`notes`	String	Free-form notes about the customer.
`num_tickets`	Integer	Number of tickets of the customer.
`num_visible_tickets`	Integer	Number of tickets of the customer visible to the API key’s user.
`standing`	String	Standing of the customer: Bad, New or Good (customers that only sent spam are Bad).
`trusted`	Boolean	Whether the customer is trusted (their images are shown automatically).
`verified_email`	Boolean	Whether the customer verified their email address.
`welcome_email_sent`	Boolean	Whether the customer portal welcome email was sent to the customer.
`send_welcome_email`	Boolean	Whether a welcome email is to be sent to the customer.
`permission`	String	Ticket permission of the customer in the customer portal (own or all), overriding the company setting.
`add_method`	String	How the customer was added to their company (for example by domain or manually).
`pm_person_id`	Integer	Id of the matching person in Teamwork Projects.
`contacts`	String (JSON)	Contacts of the customer (email addresses and phones) as relationships (JSON array).
`customer_welcome_emails`	String (JSON)	Welcome emails sent to the customer (JSON array of relationships).
`state`	String	State of the customer: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the customer was created (UTC).
`created_by_id`	Integer	Id of the user who created the customer.
`updated_at`	Datetime	When the customer was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the customer.
`deleted_at`	Datetime	When the customer was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the customer.

Companies

Companies (and custom groups) your customers belong to, updated since the Start Date.Table: companies · Primary key: id · Sync: Incremental (updated_at)

Field	Type	Description
`id`	Integer	Unique identifier of the company.
`name`	String	Unique name of the company.
`email`	String	Email address used to contact the company.
`website`	String	Website of the company.
`industry`	String	Industry of the company.
`details`	String	Reference notes about the company.
`kind`	String	Whether the company is a company or a group (a custom group of customers).
`permission`	String	Access customers of this company have in the customer portal (own or all tickets).
`avatar_path`	String	Domain and path of the company avatar.
`customers_count`	Integer	Number of customers in the company.
`tickets_count`	Integer	Number of tickets of the company.
`unread_tickets_count`	Integer	Number of unread tickets of the company.
`address_id`	Integer	Id of the address of the company.
`pm_company_id`	Integer	Id of the matching company in Teamwork Projects.
`domains`	String (JSON)	Email domains of the company (JSON array of relationships).
`phones`	String (JSON)	Phone numbers of the company (JSON array of relationships).
`social_links`	String (JSON)	Social links of the company (JSON array of relationships).
`state`	String	State of the company: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the company was created (UTC).
`created_by_id`	Integer	Id of the user who created the company.
`updated_at`	Datetime	When the company was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the company.
`deleted_at`	Datetime	When the company was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the company.

Happiness Ratings

Satisfaction (happiness) ratings customers gave to tickets, updated since the Start Date. Ratings deleted in Teamwork Desk are kept with state = deleted.Table: happiness_ratings · Primary key: id · Sync: Incremental (updated_at)

Field	Type	Description
`id`	Integer	Unique identifier of the satisfaction (happiness) rating.
`ticket_id`	Integer	Id of the rated ticket (tickets table).
`happiness_rating_option_id`	Integer	Id of the answer the customer chose (happiness_rating_options table).
`comment`	String	Comment the customer left with the rating.
`deleted_reason`	String	Why the rating was deleted.
`state`	String	State of the rating: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the rating was created (UTC).
`created_by_id`	Integer	Id of the user who created the rating.
`updated_at`	Datetime	When the rating was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the rating.
`deleted_at`	Datetime	When the rating was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the rating.

Time Logs

Time logged by agents on tickets, updated since the Start Date. Time logs deleted in Teamwork Desk are kept with state = deleted, so add WHERE state <> 'deleted' when summing hours.Table: timelogs · Primary key: id · Sync: Incremental (updated_at)

Field	Type	Description
`id`	Integer	Unique identifier of the time log.
`ticket_id`	Integer	Id of the ticket the time was logged on (tickets table).
`user_id`	Integer	Id of the user who logged the time (users table).
`date`	Datetime	Date (and start time, when chosen) the time was logged for (UTC).
`has_start_time`	Boolean	Whether date carries a start time chosen by the user.
`seconds`	Integer	Time logged, in seconds.
`billable`	Boolean	Whether the time is billable.
`description`	String	Description of the work.
`timezone_offset`	Integer	UTC offset of the user when the time was logged, in minutes.
`project_id`	Integer	Id of the Teamwork Projects project the time was sent to.
`task_id`	Integer	Id of the Teamwork Projects task the time was sent to.
`projects_timelog_id`	Integer	Id of the matching time entry in Teamwork Projects (relationship).
`timelogs_id`	Integer	Id of the matching time entry in Teamwork Projects.
`state`	String	State of the time log: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the time log was created (UTC).
`created_by_id`	Integer	Id of the user who created the time log.
`updated_at`	Datetime	When the time log was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the time log.
`deleted_at`	Datetime	When the time log was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the time log.

Users

Agents and admins of your Teamwork Desk, archived ones included.Table: users · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the user (agent or admin).
`first_name`	String	First name of the user.
`last_name`	String	Last name of the user.
`email`	String	Email address of the user.
`role`	String	Role of the user: admin or agent.
`is_app_owner`	Boolean	Whether the user owns the Teamwork Desk installation.
`is_part_time`	Boolean	Whether the user is a part-time agent (limited number of ticket replies per month).
`reviewer`	Boolean	Whether the user reviews pending replies of other agents.
`edit_method`	String	Default editor of the user: html or markdown.
`avatar_url`	String	URL of the user’s avatar.
`auto_follow_on_cc`	Boolean	Whether the user follows tickets they are copied on.
`send_push_notifications`	Boolean	Whether push notifications are sent to the user’s mobile app.
`send_web_notifications`	Boolean	Whether browser notifications are sent to the user.
`ticket_reply_redirect`	String	Where the user is taken after replying to a ticket.
`time_format_id`	Integer	Time format of the user (from Teamwork).
`timezone_id`	Integer	Time zone of the user (from Teamwork).
`projects_company_id`	Integer	Id of the user’s company in Teamwork Projects.
`onboarding`	String (JSON)	Onboarding progress of the user (JSON object).
`training_wheels_enrollment_id`	Integer	Id of the user’s in-app guide enrollment.
`state`	String	State of the user: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the user was created (UTC).
`created_by_id`	Integer	Id of the user who created the user.
`updated_at`	Datetime	When the user was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the user.
`deleted_at`	Datetime	When the user was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the user.

Inboxes

Inboxes (shared and personal) and their settings. The SMTP password is never loaded.Table: inboxes · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the inbox.
`name`	String	Name of the inbox.
`email`	String	Email address of the inbox.
`type`	String	Kind of inbox: shared (by the team) or personal.
`user_id`	Integer	Id of the owner of a personal inbox (users table).
`display_order`	Integer	Position of the inbox in the inbox list.
`starred`	Boolean	Whether the inbox is starred.
`client_only`	Boolean	Whether the inbox is a client-only inbox.
`notifications_only`	Boolean	Whether the inbox only sends notifications.
`is_admin`	Boolean	Whether the user of the API key administers the inbox.
`verified`	Boolean	Whether the inbox email address is verified.
`is_free_domain`	Boolean	Whether the inbox address is on a free email domain.
`local_part`	String	Local part (before the @) of the inbox address.
`forwarding_address`	String	Address emails are forwarded to for this inbox.
`email_forwarding_state`	String	State of the email forwarding of the inbox.
`send_emails_from`	String	Address emails of the inbox are sent from.
`use_teamwork_mail_server`	Boolean	Whether emails are sent through Teamwork’s mail server.
`smtp_provider`	String	SMTP provider used to send emails (when not Teamwork’s).
`smtp_server`	String	SMTP server used to send emails.
`smtp_port`	Integer	SMTP port used to send emails.
`smtp_security`	String	SMTP security setting.
`smtp_username`	String	SMTP user name (the password is never loaded).
`synced`	Boolean	Whether the inbox is synced with a mailbox.
`sync_account_id`	Integer	Id of the synced mailbox account.
`sync_subscription_id`	Integer	Id of the mailbox sync subscription.
`sync_days`	Integer	Number of days of email imported by the mailbox sync.
`sync_force_import`	Boolean	Whether the mailbox sync forces the import of emails.
`auto_reply_enabled`	Boolean	Whether the automatic reply is on.
`auto_reply_from_user_id`	Integer	Id of the user the automatic reply is sent as.
`auto_reply_subject`	String	Subject of the automatic reply.
`auto_reply_message`	String	Body of the automatic reply.
`happiness_rating_enabled`	Boolean	Whether satisfaction ratings are asked for tickets of the inbox.
`happiness_rating_message`	String	Message of the satisfaction rating request.
`timelogging_enabled`	Boolean	Whether time logging is on for the inbox.
`timelogging_project_id`	Integer	Id of the Teamwork Projects project time is logged to.
`on_closed_lock`	String	What happens to replies on closed tickets of the inbox.
`on_closed_wait`	Integer	How long a closed ticket accepts replies before the lock applies.
`using_office_hours`	Boolean	Whether the inbox uses office hours.
`include_ticket_history_on_forward`	Boolean	Whether forwarded tickets carry their history.
`show_trends`	Boolean	Whether trends are shown for the inbox.
`spam_threshold`	Integer	Spam score above which tickets are marked as spam.
`language_code`	String	Language of the inbox.
`signature`	String	Email signature of the inbox.
`icon_image`	String	Icon of the inbox.
`public_icon_image`	String	Public icon of the inbox.
`default_team_agent_id`	Integer	Id of the default agent of the inbox.
`ticket_status_id`	Integer	Id of the default status of new tickets of the inbox.
`ticket_types`	String (JSON)	Ticket types available in the inbox (JSON array of relationships).
`users`	String (JSON)	Users with access to the inbox (JSON array of relationships).
`projects`	String (JSON)	Teamwork Projects projects linked to the inbox (JSON array of relationships).
`triggers`	String (JSON)	Triggers of the inbox (JSON array of relationships).
`inbox_aliases`	String (JSON)	Alias addresses of the inbox (JSON array of relationships).
`inbox_cnames`	String (JSON)	Custom domains (CNAME) of the inbox (JSON array of relationships).
`inbox_email_refs`	String (JSON)	Email references of the inbox (JSON array of relationships).
`restricted_domains`	String (JSON)	Email domains restricted for the inbox (JSON array of relationships).
`state`	String	State of the inbox: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the inbox was created (UTC).
`created_by_id`	Integer	Id of the user who created the inbox.
`updated_at`	Datetime	When the inbox was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the inbox.
`deleted_at`	Datetime	When the inbox was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the inbox.

Tags

Tags that can be applied to tickets.Table: tags · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the tag.
`name`	String	Name of the tag.
`color`	String	Color of the tag.
`allow_auto_tagging`	Boolean	Whether the tag can be applied automatically.
`ticket_count`	Integer	Number of active tickets with the tag.
`state`	String	State of the tag: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the tag was created (UTC).
`created_by_id`	Integer	Id of the user who created the tag.
`updated_at`	Datetime	When the tag was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the tag.
`deleted_at`	Datetime	When the tag was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the tag.

Ticket Priorities

Priorities a ticket can have.Table: ticket_priorities · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the ticket priority.
`name`	String	Name of the priority.
`color`	String	Color of the priority.
`display_order`	Integer	Position of the priority in lists.
`ticket_count`	Integer	Number of tickets with the priority (when Teamwork Desk sends it).
`state`	String	State of the priority: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the priority was created (UTC).
`created_by_id`	Integer	Id of the user who created the priority.
`updated_at`	Datetime	When the priority was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the priority.
`deleted_at`	Datetime	When the priority was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the priority.

Ticket Statuses

Statuses a ticket can have, built-in and custom.Table: ticket_statuses · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the ticket status.
`name`	String	Name of the status (for example Active, Waiting on customer, Solved, Closed).
`code`	String	Code of the status (for example active, waiting, solved, closed).
`color`	String	Color of the status.
`icon`	String	Icon of the status.
`is_custom`	Boolean	Whether the status was created by the site (not a built-in one).
`display_order`	Integer	Position of the status in lists.
`ticket_count`	Integer	Number of tickets with the status (when Teamwork Desk sends it).
`state`	String	State of the status: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the status was created (UTC).
`created_by_id`	Integer	Id of the user who created the status.
`updated_at`	Datetime	When the status was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the status.
`deleted_at`	Datetime	When the status was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the status.

Ticket Sources

Channels a ticket can come from (email, phone, chat, API…).Table: ticket_sources · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the ticket source (the channel a ticket came from).
`name`	String	Name of the source (for example Email, Phone, Chat, API).
`icon`	String	Icon of the source.
`is_custom`	Boolean	Whether the source was created by the site (not a built-in one).
`display_order`	Integer	Position of the source in lists.
`ticket_count`	Integer	Number of tickets from the source (when Teamwork Desk sends it).
`state`	String	State of the source: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the source was created (UTC).
`created_by_id`	Integer	Id of the user who created the source.
`updated_at`	Datetime	When the source was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the source.
`deleted_at`	Datetime	When the source was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the source.

Ticket Types

Types a ticket can have.Table: ticket_types · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the ticket type.
`name`	String	Name of the type (for example Question, Problem, Feature request).
`is_default`	Boolean	Whether the type is the default for new tickets.
`display_order`	Integer	Position of the type in lists.
`enabled_for_future_inboxes`	Boolean	Whether the type is added to inboxes created later.
`inboxes`	String (JSON)	Inboxes the type is available in (JSON array of relationships).
`state`	String	State of the type: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the type was created (UTC).
`created_by_id`	Integer	Id of the user who created the type.
`updated_at`	Datetime	When the type was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the type.
`deleted_at`	Datetime	When the type was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the type.

SLAs

Service level agreements and what they apply to.Table: slas · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the SLA (service level agreement).
`name`	String	Name of the SLA.
`description`	String	Description of the SLA.
`enabled`	Boolean	Whether the SLA is on.
`display_order`	Integer	Position of the SLA in lists (the order in which SLAs are matched).
`on_close_without_reply`	String	What the SLA does when a ticket is closed without a reply.
`business_hours_id`	Integer	Id of the business hours the SLA counts time in (business_hours table).
`inboxes`	String (JSON)	Inboxes the SLA applies to (JSON array of relationships).
`companies`	String (JSON)	Companies the SLA applies to (JSON array of relationships).
`customers`	String (JSON)	Customers the SLA applies to (JSON array of relationships).
`tags`	String (JSON)	Tags the SLA applies to (JSON array of relationships).
`ticket_priorities`	String (JSON)	Ticket priorities the SLA applies to (JSON array of relationships).
`ticket_types`	String (JSON)	Ticket types the SLA applies to (JSON array of relationships).
`notifications`	String (JSON)	Notifications of the SLA, with their targets (JSON array of relationships).
`sla_companies`	String (JSON)	Company links of the SLA (JSON array of relationships).
`sla_customers`	String (JSON)	Customer links of the SLA (JSON array of relationships).
`sla_inboxes`	String (JSON)	Inbox links of the SLA (JSON array of relationships).
`sla_tags`	String (JSON)	Tag links of the SLA (JSON array of relationships).
`sla_ticket_priorities`	String (JSON)	Ticket priority links of the SLA, with response and resolution targets when sent (JSON array of relationships).
`sla_ticket_types`	String (JSON)	Ticket type links of the SLA (JSON array of relationships).
`state`	String	State of the SLA: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the SLA was created (UTC).
`created_by_id`	Integer	Id of the user who created the SLA.
`updated_at`	Datetime	When the SLA was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the SLA.
`deleted_at`	Datetime	When the SLA was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the SLA.

Business Hours

Business hours used by SLAs, with their schedules and holidays.Table: business_hours · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the business hours.
`name`	String	Name of the business hours.
`description`	String	Description of the business hours.
`is_default`	Boolean	Whether these are the default business hours.
`timezone_id`	Integer	Time zone of the business hours (Teamwork id).
`timezone_name`	String	Time zone of the business hours.
`business_hour_schedules`	String (JSON)	Weekly schedule of the business hours (JSON array of relationships).
`business_hour_holidays`	String (JSON)	Holidays of the business hours (JSON array of relationships).
`triggers`	String (JSON)	Triggers using the business hours (JSON array of relationships).
`state`	String	State of the business hours: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the business hours was created (UTC).
`created_by_id`	Integer	Id of the user who created the business hours.
`updated_at`	Datetime	When the business hours was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the business hours.
`deleted_at`	Datetime	When the business hours was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the business hours.

Custom Fields

Custom fields defined for tickets.Table: custom_fields · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the custom field.
`agent_label`	String	Name of the field shown to agents.
`customer_label`	String	Name of the field shown to customers.
`description`	String	Description of the field.
`kind`	String	Input kind of the field: dropdown, checkboxes, text, textarea, number, date…
`enabled`	Boolean	Whether the field is shown and validated.
`agent_required`	Boolean	Whether agents must fill the field.
`customer_required`	Boolean	Whether customers must fill the field.
`add_to_new_inboxes`	Boolean	Whether the field is added to inboxes created later.
`display_order`	Integer	Position of the field.
`apps`	String (JSON)	Where the field is used (help docs, customer portal, contact form…) and its options there (JSON array of relationships).
`options`	String (JSON)	Options of a dropdown or checkboxes field (JSON array of relationships; names in custom_field_options).
`state`	String	State of the custom field: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the custom field was created (UTC).
`created_by_id`	Integer	Id of the user who created the custom field.
`updated_at`	Datetime	When the custom field was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the custom field.
`deleted_at`	Datetime	When the custom field was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the custom field.

Custom Field Options

Options of the dropdown and checkboxes custom fields.Table: custom_field_options · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the custom field option.
`custom_field_id`	Integer	Id of the custom field the option belongs to (custom_fields table).
`name`	String	Name of the option, also its value.
`display_order`	Integer	Position of the option.
`state`	String	State of the option: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the option was created (UTC).
`created_by_id`	Integer	Id of the user who created the option.
`updated_at`	Datetime	When the option was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the option.
`deleted_at`	Datetime	When the option was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the option.

Happiness Rating Options

Answers a customer can choose when rating a ticket.Table: happiness_rating_options · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the satisfaction rating answer.
`name`	String	Name of the answer (for example Great, Okay, Not good).
`annotation`	String	Text shown with the answer.
`color`	String	Color of the answer.
`score`	Integer	Score of the answer.
`state`	String	State of the rating answer: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the rating answer was created (UTC).
`created_by_id`	Integer	Id of the user who created the rating answer.
`updated_at`	Datetime	When the rating answer was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the rating answer.
`deleted_at`	Datetime	When the rating answer was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the rating answer.

Canned Responses

Saved replies agents can insert in tickets.Table: canned_responses · Primary key: id · Sync: Full table

Field	Type	Description
`id`	Integer	Unique identifier of the canned response.
`name`	String	Name of the canned response, shown when searching for it.
`reply`	String	Body of the canned response (HTML).
`reply_plain`	String	Body of the canned response in plain text.
`shared`	Boolean	Whether any agent can use the canned response.
`inbox_id`	Integer	Id of the inbox the canned response belongs to (inboxes table).
`files`	String (JSON)	Attachments of the canned response (JSON array of relationships).
`state`	String	State of the canned response: usually active or deleted (deleted only when the API returns deleted records).
`created_at`	Datetime	When the canned response was created (UTC).
`created_by_id`	Integer	Id of the user who created the canned response.
`updated_at`	Datetime	When the canned response was last updated (UTC); not changed when it is deleted.
`updated_by_id`	Integer	Id of the user who last updated the canned response.
`deleted_at`	Datetime	When the canned response was deleted (UTC); only set for deleted records.
`deleted_by_id`	Integer	Id of the user who deleted the canned response.

Implementation Notes

Data Quality Considerations

How tickets stay up to date. Each sync reads the tickets updated since the previous one (minus 10 minutes, to cover changes still being saved in Teamwork Desk) up to the moment the sync started; a ticket updated while a sync runs is read by the next sync. Tickets of every state are read: active, scheduled, merged and deleted. Deleting a ticket does not change its last update date, so the connector also reads the tickets deleted since the previous sync, and they appear with state = deleted.
Ticket messages. Teamwork Desk lists messages ticket by ticket. When a ticket changes (for example, a new reply), the next sync reads all its messages again and merges them by message id. The sync also reads the messages of every ticket that had any activity since the previous sync, even if its last update date did not change, and warns in the sync log if Teamwork Desk added new messages without updating their ticket. Tickets with activity that the API key’s user cannot see are skipped. The messages of deleted tickets are not read again and stay as last loaded. If Teamwork Desk says a ticket’s messages are not found, the sync checks the ticket: when it was deleted, merged into another ticket or no longer exists, it is skipped; otherwise the table fails.
Delivery and view details of messages. Fields such as delivery_status, viewed_by_customer_at, reactions and likes can change without any activity on the ticket; they are refreshed the next time the ticket changes, so they may lag behind Teamwork Desk.
Long histories are read in steps. Tickets are read 30 days at a time (messages 7 days at a time; customers, companies, ratings and time logs 90 days at a time), oldest first. On the first sync and on a full sync, a table only counts as done when every period was read: if it stops halfway, the next sync starts it again. When a source catches up after a pause, each period is saved as it goes, and a sync that stops halfway continues from the last period saved.
Full table tables are never half updated. The connector reads all the data of a full table table before writing any of it. If Teamwork Desk fails while it is read, nothing of that table is sent and the sync shows it as failed. A full table table that suddenly comes back empty is not emptied either: the sync fails for that table. If the data really was removed in Teamwork Desk, run a full sync of the source to accept it.
Complete reads. Lists are read page by page and checked against the number of records Teamwork Desk reports. If records disappear while a list is read (for example, a customer deleted during the sync), the list is read again; if it still does not add up, the table fails instead of loading incomplete data.
Deleted records. Tickets, time logs and satisfaction ratings deleted in Teamwork Desk are loaded with state = deleted and their deleted_at date. Filter them out in your analyses (for example WHERE state <> 'deleted' when summing timelogs.seconds). Deleted customers and companies are not reported, so they stay in the table as last loaded.
Features not available to the key. If Teamwork Desk refuses the API key access to an area (for example, SLAs, time logs or satisfaction ratings not included in your plan, or not allowed for the key’s user), or answers with an error when the sync checks it, the tables of that area are shown as failed with a message saying so, and the other tables keep syncing. An invalid key, or a site address that is not your Teamwork site, fails the sync with a message saying what to check.
Custom field values. Custom fields of a ticket come in tickets.custom_fields as a JSON list with the custom field id and, when Teamwork Desk sends it, the value.
Secrets. Passwords stored in Teamwork Desk (such as an inbox SMTP password) are never loaded.

API Limits & Performance

Teamwork Desk allows 120 requests per minute per site, shared by every integration of your site. The connector sends at most 100 per minute and, when Teamwork Desk asks it to wait, waits and tells you in the sync log.
Lists are read up to 100 records per request: 10,000 tickets take about 100 requests (one minute).
Ticket Messages needs one request per changed ticket (and one more per extra 100 messages). A first sync of 10,000 tickets takes about 2 hours; later syncs only read the tickets that changed, so they are quick. On a large help desk, choose a recent Start Date (for example, the last few months) for the first sync, or deselect Ticket Messages if you do not need the conversations.
Users, inboxes and the settings tables are read whole on every sync; they are small and take a few requests each.

Get started

Context

Activate

Organizations

Workspaces

Resources

Teamwork Desk as a data source

Configuring Teamwork Desk as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Available streams

Fields by stream

Implementation Notes

Data Quality Considerations

API Limits & Performance