> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Movidesk as a data source

> Bring your Movidesk tickets, conversations, time appointments, people, services and satisfaction surveys to Nekt.

Movidesk, by Zenvia, is a help desk and customer service platform: requests arrive by email, chat, WhatsApp, phone or the client portal and become tickets, handled by agents and teams, classified by service, category and urgency, and measured against SLA agreements. This connector reads your account's data through the official Movidesk API and brings your tickets with their whole conversation (actions), the hours logged on them, their clients, status and owner histories and additional fields, plus your people (clients and agents), service catalog, hour contracts, activities and satisfaction survey answers.

> [!NOTE]
>
> The connector only reads data. It never creates, changes or deletes anything in Movidesk.

## Configuring Movidesk as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Movidesk option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

The Movidesk API uses an **API token**, one per account. An administrator finds it in Movidesk under **Configurações > Conta > Parâmetros**, on the **Ambiente** tab, at the bottom of the page. If there is no token yet, click **Gerar nova chave**.

* **API Token**: the token copied from Movidesk.
* **Start Date**: the earliest date synced on the first sync and on full syncs. Tickets last updated since this date are loaded (with all their actions, time appointments, clients, histories and additional fields), and so are the survey answers given since it. People, services, hour contracts, activities and survey questions are always loaded whole.
* **Requests per Minute** (advanced, default 10): how many requests per minute this source may send to Movidesk. Keep 10 unless Movidesk support raised your account's limit.

> [!WARNING]
>
> Generating a new key in Movidesk stops the previous one. If you or another integration generate a new key, update the API Token of this source, or its syncs will fail.

> [!TIP]
>
> Movidesk allows 10 requests per minute per account from 07:00 to 19:00 (Brasília time), shared by every integration that uses the token. Other integrations running at the same time make the syncs slower, 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. The ticket tables and Survey Responses 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.

> [!WARNING]
>
> Avoid setting the ticket tables to Full table. Every sync would then read again every ticket updated since the Start Date, which takes long under Movidesk's limit of 10 requests per minute.

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](https://docs.nekt.com/runs/scheduling-and-triggers.md), 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](https://docs.nekt.com/get-started/core-concepts/resource-control).

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/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 with status, service, SLA, owner, clients, histories and additional fields. |
| Ticket Actions | `ticket_actions` | Incremental | The conversation of each ticket: messages, internal notes and emails, with author and expenses. |
| Ticket Time Appointments | `ticket_time_appointments` | Incremental | Hours logged by agents on each ticket. |
| Ticket Clients | `ticket_clients` | Incremental | Clients of each ticket, with their organization. |
| Ticket Status Histories | `ticket_status_histories` | Incremental | Every status each ticket went through and for how long. |
| Ticket Owner Histories | `ticket_owner_histories` | Incremental | Every agent responsible for each ticket and for how long. |
| Ticket Custom Field Values | `ticket_custom_field_values` | Incremental | Values of the additional fields of each ticket. |
| Persons | `persons` | Full table | People, companies and departments (clients and agents). |
| Services | `services` | Full table | The service catalog. |
| Time Agreements | `time_agreements` | Full table | Hour contracts. |
| Activities | `activities` | Full table | Activities agents log time against. |
| Survey Questions | `survey_questions` | Full table | Questions of the satisfaction surveys. |
| Survey Responses | `survey_responses` | Incremental | Answers to the satisfaction surveys. |

The ticket tables join on `ticket_id` = `tickets.id`. People join on `persons.id` with the `*_id` reference codes (`owner_id`, `created_by_id`, `ticket_clients.id`...), and services on `services.id` = `tickets.service_first_level_id`. Survey answers join on `survey_responses.ticket_id` and `survey_responses.question_id` = `survey_questions.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. Dates and times are in UTC.

> [accordion] Tickets
>
> Tickets last updated since the Start Date (first sync and full syncs), with their status, service, SLA dates and counters, owner, clients, histories and additional fields. Each sync reads the tickets changed since the previous one.
>
> Table: `tickets` · Primary key: `id` · Sync: Incremental (`last_update`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Ticket number. |
> | `protocol` | String | Ticket protocol (null when the account does not use protocols). |
> | `type` | Integer | Ticket type: 1 internal, 2 public. |
> | `subject` | String | Ticket subject. |
> | `category` | String | Name of the ticket category. |
> | `urgency` | String | Name of the ticket urgency. |
> | `status` | String | Name of the ticket status. |
> | `base_status` | String | Base status of the ticket: New, InAttendance, Stopped, Canceled, Resolved or Closed. |
> | `justification` | String | Name of the justification of the current status. |
> | `origin` | Integer | Channel the ticket was opened through (1 web by client, 2 web by agent, 3 email, 5 chat, 9 API, 18 WhatsApp... see the Movidesk API docs). |
> | `created_date` | Datetime | When the ticket was opened (UTC). |
> | `origin_email_account` | String | Email account the ticket was received on. |
> | `owner_team` | String | Team of the agent responsible for the ticket. |
> | `owner_id` | String | Reference code (Cód. Ref.) of the agent responsible for the ticket. |
> | `owner_name` | String | Name of the agent responsible for the ticket. |
> | `owner` | String (JSON) | The agent responsible for the ticket: id, businessName, email, phone, personType (1 person, 2 company, 4 department) and profileType (1 agent, 2 client, 3 both) (JSON object). |
> | `created_by_id` | String | Reference code (Cód. Ref.) of the person who opened the ticket. |
> | `created_by_name` | String | Name of the person who opened the ticket. |
> | `created_by` | String (JSON) | The person who opened the ticket: id, businessName, email, phone, personType (1 person, 2 company, 4 department) and profileType (1 agent, 2 client, 3 both) (JSON object). |
> | `service_full` | String (JSON) | Names of every level of the service selected in the ticket (JSON array). |
> | `service_first_level_id` | Integer | Id of the service selected in the ticket. |
> | `service_first_level` | String | Name of the first level of the selected service. |
> | `service_second_level` | String | Name of the second level of the selected service. |
> | `service_third_level` | String | Name of the third level of the selected service. |
> | `contact_form` | String | Name of the contact form the ticket was opened through. |
> | `tags` | String (JSON) | Tags of the ticket (JSON array of strings). |
> | `cc` | String | Emails in the Cc field, comma separated. |
> | `resolved_in` | Datetime | When an agent marked the ticket as resolved (UTC). |
> | `reopened_in` | Datetime | When the ticket was last reopened (UTC). |
> | `closed_in` | Datetime | When the ticket was closed (UTC). |
> | `last_action_date` | Datetime | When the last action of the ticket happened (UTC). |
> | `action_count` | Integer | Number of actions in the ticket. |
> | `last_update` | Datetime | When the ticket was last changed (UTC); used as the incremental replication key. |
> | `lifetime_working_time` | Number | Lifetime of the ticket since it was opened, in working-hours minutes. |
> | `stopped_time` | Number | Time the ticket spent in a stopped status, in calendar minutes. |
> | `stopped_time_working_time` | Number | Time the ticket spent in a stopped status, in working-hours minutes. |
> | `resolved_in_first_call` | Boolean | Whether the ticket was resolved on first contact (only filled for chat and phone tickets created as resolved or closed). |
> | `chat_widget` | String | Chat app the ticket was opened through. |
> | `chat_group` | String | Chat group the ticket was opened through. |
> | `chat_talk_time` | Number | Duration of the chat, in seconds. |
> | `chat_waiting_time` | Number | Time the client waited to be answered in the chat, in seconds. |
> | `sequence` | Integer | Number stored in the Sequence field. |
> | `sla_agreement` | String | SLA agreement used in the ticket. |
> | `sla_agreement_rule` | String | Rule of the SLA agreement. |
> | `sla_solution_time` | Number | Solution time of the SLA agreement. |
> | `sla_response_time` | Number | Response time of the SLA agreement. |
> | `sla_solution_changed_by_user` | Boolean | Whether a user changed the SLA solution date by hand. |
> | `sla_solution_changed_by` | String (JSON) | Person who changed the SLA solution date (JSON object). |
> | `sla_solution_date` | Datetime | SLA solution due date (UTC). |
> | `sla_solution_date_is_paused` | Boolean | Whether the SLA solution date is paused. |
> | `sla_response_date` | Datetime | SLA response due date (UTC). |
> | `sla_real_response_date` | Datetime | When the ticket was actually first answered (UTC). |
> | `jira_issue_key` | String | Key of the Jira issue linked to the ticket by integration. |
> | `redmine_issue_id` | Integer | Id of the Redmine issue linked to the ticket by integration. |
> | `clients` | String (JSON) | Clients of the ticket, with their organization and isDeleted flag (JSON array); also in the ticket\_clients table. |
> | `parent_tickets` | String (JSON) | Parent tickets: id, subject, isDeleted (JSON array). |
> | `children_tickets` | String (JSON) | Child tickets: id, subject, isDeleted (JSON array). |
> | `owner_histories` | String (JSON) | History of the agents responsible for the ticket (JSON array); also in the ticket\_owner\_histories table. |
> | `status_histories` | String (JSON) | History of the ticket statuses (JSON array); also in the ticket\_status\_histories table. |
> | `custom_field_values` | String (JSON) | Values of the additional fields shown in the ticket (JSON array); also in the ticket\_custom\_field\_values table. |
> | `assets` | String (JSON) | Assets linked to the ticket (JSON array). |

> [accordion] Ticket Actions
>
> The conversation of each ticket: every action (message, internal note, email) with its author and expenses. Deleted actions are kept and marked with `is_deleted`.
>
> Table: `ticket_actions` · Primary key: `ticket_id`, `id` · Sync: Incremental (`ticket_last_update`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `ticket_id` | Integer | Number of the ticket this row belongs to. |
> | `id` | Integer | Number of the action within the ticket. |
> | `ticket_last_update` | Datetime | Last update of the ticket this row belongs to (UTC); used as the incremental replication key. |
> | `type` | Integer | Action type: 1 internal, 2 public. |
> | `origin` | Integer | Where the action came from (1 web by client, 2 web by agent, 3 email, 5 chat, 9 API, 18 WhatsApp... see the Movidesk API docs). |
> | `description` | String | Text of the action (plain text; the HTML version is not available in ticket lists). |
> | `status` | String | Ticket status set by the action. |
> | `justification` | String | Justification of the status set by the action. |
> | `created_date` | Datetime | When the action was created (UTC). |
> | `created_by_id` | String | Reference code (Cód. Ref.) of the person who created the action. |
> | `created_by_name` | String | Name of the person who created the action. |
> | `created_by` | String (JSON) | The person who created the action: id, businessName, email, phone, personType (1 person, 2 company, 4 department) and profileType (1 agent, 2 client, 3 both) (JSON object). |
> | `is_deleted` | Boolean | Whether the action was deleted from the ticket. |
> | `tags` | String (JSON) | Tags of the action (JSON array of strings). |
> | `expenses` | String (JSON) | Expenses recorded on the action: type, date, quantity, value, createdBy (JSON array). |
> | `attachments` | String (JSON) | Files attached to the action: fileName, path (file hash), createdBy, createdDate (JSON array). |

> [accordion] Ticket Time Appointments
>
> Hours logged by agents on the actions of each ticket.
>
> Table: `ticket_time_appointments` · Primary key: `ticket_id`, `action_id`, `id` · Sync: Incremental (`ticket_last_update`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `ticket_id` | Integer | Number of the ticket this row belongs to. |
> | `action_id` | Integer | Number of the action the time was logged on. |
> | `id` | Integer | Id of the time appointment. |
> | `ticket_last_update` | Datetime | Last update of the ticket this row belongs to (UTC); used as the incremental replication key. |
> | `action_is_deleted` | Boolean | Whether the action holding this appointment was deleted from the ticket. |
> | `activity` | String | Activity the time was logged for. |
> | `date` | Date | Day the work was done. |
> | `period_start` | String | Start of the logged period (time of day, e.g. 08:00:00). |
> | `period_end` | String | End of the logged period (time of day, e.g. 12:00:00). |
> | `work_time` | String | Total time logged (e.g. 04:00:00). |
> | `accounted_time` | Number | Time accounted for the appointment, in decimal hours. |
> | `work_type_name` | String | Type of hours logged (e.g. overtime). |
> | `created_by_id` | String | Reference code (Cód. Ref.) of the person who logged the time. |
> | `created_by_name` | String | Name of the person who logged the time. |
> | `created_by` | String (JSON) | The person who logged the time: id, businessName, email, phone, personType (1 person, 2 company, 4 department) and profileType (1 agent, 2 client, 3 both) (JSON object). |
> | `created_by_team_id` | Integer | Id of the team of the person who logged the time. |
> | `created_by_team_name` | String | Name of the team of the person who logged the time. |

> [accordion] Ticket Clients
>
> The clients (people, companies or departments) of each ticket, with their organization. Clients removed from a ticket are kept and marked with `is_deleted`.
>
> Table: `ticket_clients` · Primary key: `ticket_id`, `id` · Sync: Incremental (`ticket_last_update`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `ticket_id` | Integer | Number of the ticket this row belongs to. |
> | `id` | String | Reference code (Cód. Ref.) of the client (person, company or department). |
> | `ticket_last_update` | Datetime | Last update of the ticket this row belongs to (UTC); used as the incremental replication key. |
> | `business_name` | String | Name of the client. |
> | `email` | String | Main email of the client. |
> | `phone` | String | Main phone of the client. |
> | `person_type` | Integer | Client type: 1 person, 2 company, 4 department. |
> | `profile_type` | Integer | Client profile: 1 agent, 2 client, 3 both. |
> | `is_deleted` | Boolean | Whether the client was removed from the ticket. |
> | `organization_id` | String | Reference code of the client's organization. |
> | `organization_name` | String | Name of the client's organization. |
> | `organization` | String (JSON) | Organization of the client (JSON object). |

> [accordion] Ticket Status Histories
>
> Every status a ticket went through, numbered from the oldest, with how long it stayed in each one.
>
> Table: `ticket_status_histories` · Primary key: `ticket_id`, `position` · Sync: Incremental (`ticket_last_update`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `ticket_id` | Integer | Number of the ticket this row belongs to. |
> | `position` | Integer | Order of the entry in the ticket's history (1 = oldest), by change date. |
> | `ticket_last_update` | Datetime | Last update of the ticket this row belongs to (UTC); used as the incremental replication key. |
> | `status` | String | Status the ticket was in. |
> | `justification` | String | Justification of the status. |
> | `permanency_time_full_time` | Number | Time the ticket stayed in this status, in calendar seconds. |
> | `permanency_time_working_time` | Number | Time the ticket stayed in this status, in working-hours seconds. |
> | `changed_by_id` | String | Reference code (Cód. Ref.) of the person who changed the status. |
> | `changed_by_name` | String | Name of the person who changed the status. |
> | `changed_by` | String (JSON) | The person who changed the status: id, businessName, email, phone, personType (1 person, 2 company, 4 department) and profileType (1 agent, 2 client, 3 both) (JSON object). |
> | `changed_date` | Datetime | When the status was set (UTC). |

> [accordion] Ticket Owner Histories
>
> Every agent responsible for a ticket, numbered from the oldest, with how long each one held it.
>
> Table: `ticket_owner_histories` · Primary key: `ticket_id`, `position` · Sync: Incremental (`ticket_last_update`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `ticket_id` | Integer | Number of the ticket this row belongs to. |
> | `position` | Integer | Order of the entry in the ticket's history (1 = oldest), by change date. |
> | `ticket_last_update` | Datetime | Last update of the ticket this row belongs to (UTC); used as the incremental replication key. |
> | `owner_team` | String | Team of the agent responsible for the ticket. |
> | `owner_id` | String | Reference code (Cód. Ref.) of the agent responsible for the ticket. |
> | `owner_name` | String | Name of the agent responsible for the ticket. |
> | `owner` | String (JSON) | The agent responsible for the ticket: id, businessName, email, phone, personType (1 person, 2 company, 4 department) and profileType (1 agent, 2 client, 3 both) (JSON object). |
> | `permanency_time_full_time` | Number | Time this agent stayed responsible, in calendar seconds. |
> | `permanency_time_working_time` | Number | Time this agent stayed responsible, in working-hours seconds. |
> | `changed_by_id` | String | Reference code (Cód. Ref.) of the person who changed the responsible agent. |
> | `changed_by_name` | String | Name of the person who changed the responsible agent. |
> | `changed_by` | String (JSON) | The person who changed the responsible agent: id, businessName, email, phone, personType (1 person, 2 company, 4 department) and profileType (1 agent, 2 client, 3 both) (JSON object). |
> | `changed_date` | Datetime | When the responsible agent was set (UTC). |

> [accordion] Ticket Custom Field Values
>
> Values of the additional fields (campos adicionais) of each ticket, one row per field and line.
>
> Table: `ticket_custom_field_values` · Primary key: `ticket_id`, `custom_field_id`, `custom_field_rule_id`, `line` · Sync: Incremental (`ticket_last_update`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `ticket_id` | Integer | Number of the ticket this row belongs to. |
> | `custom_field_id` | Integer | Id of the additional field (see the list of additional fields in Movidesk). |
> | `custom_field_rule_id` | Integer | Id of the display rule the field belongs to. |
> | `line` | Integer | Line of the display rule the value is on (1 when the rule has a single line). |
> | `ticket_last_update` | Datetime | Last update of the ticket this row belongs to (UTC); used as the incremental replication key. |
> | `value` | String | Text value of the field (text, number, date, email, phone, URL fields); dates in UTC. |
> | `items` | String (JSON) | Selected items of list fields: customFieldItem, personId, clientId, team (JSON array). |

> [accordion] Persons
>
> People, companies and departments registered in Movidesk, clients and agents alike.
>
> Table: `persons` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Reference code (Cód. Ref.) of the person, company or department. |
> | `code_reference_additional` | String | Additional reference code (Cód. Ref. Adicional). |
> | `is_active` | Boolean | Whether the person is enabled. |
> | `person_type` | Integer | Type: 1 person, 2 company, 4 department. |
> | `profile_type` | Integer | Profile: 1 agent, 2 client, 3 agent and client. |
> | `access_profile` | String | Access profile of the person. |
> | `corporate_name` | String | Corporate name (companies). |
> | `business_name` | String | Trade name for companies, or name for people and departments. |
> | `business_branch` | String | Line of business (companies). |
> | `cpf_cnpj` | String | CPF (people) or CNPJ (companies). |
> | `user_name` | String | User name. |
> | `role` | String | Job title. |
> | `boss_id` | String | Reference code of the person's manager. |
> | `boss_name` | String | Name of the person's manager. |
> | `classification` | String | Classification of the person. |
> | `culture_id` | String | Language of the person (e.g. pt-BR). |
> | `time_zone_id` | String | Time zone of the person (IANA, e.g. America/Sao\_Paulo). |
> | `authenticate_on` | String | Directory server and domain the person authenticates on, when not Movidesk. |
> | `created_date` | Datetime | When the person was created (UTC). |
> | `created_by` | String | Reference code of who created the person. |
> | `changed_date` | Datetime | When the person was last changed (UTC). |
> | `changed_by` | String | Reference code of who last changed the person. |
> | `observations` | String | Notes about the person. |
> | `default_email` | String | Main email of the person (the one marked as default). |
> | `default_contact` | String | Main contact of the person, e.g. a phone number (the one marked as default). |
> | `addresses` | String (JSON) | Addresses: addressType, country, postalCode, state, city, district, street, number, complement, reference, isDefault (JSON array). |
> | `contacts` | String (JSON) | Contacts: contactType, contact, isDefault (JSON array). |
> | `emails` | String (JSON) | Emails: emailType, email, isDefault (JSON array). |
> | `teams` | String (JSON) | Names of the teams of the person (JSON array of strings). |
> | `relationships` | String (JSON) | Organizations the person belongs to, with SLA agreement and allowed services (JSON array). |
> | `custom_field_values` | String (JSON) | Values of the additional fields of the person (JSON array). |
> | `at_assets` | String (JSON) | Assets of the person (JSON array). |

> [accordion] Services
>
> The service catalog: the services (and sub-services) a ticket can be classified under.
>
> Table: `services` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Id of the service. |
> | `name` | String | Name of the service. |
> | `description` | String | Description of the service. |
> | `parent_service_id` | Integer | Id of the parent service (null for a first-level service). |
> | `service_for_ticket_type` | Integer | Ticket types the service is available for: 0 public, 1 internal, 2 both. |
> | `is_visible` | Integer | Visible to: 1 agent, 2 client, 3 both. |
> | `allow_selection` | Integer | Selectable by: 1 agent, 2 client, 3 both. |
> | `allow_finish_ticket` | Boolean | Whether a ticket can be finished with this service selected. |
> | `is_active` | Boolean | Whether the service is enabled (a service under a disabled one is returned as disabled). |
> | `automation_macro` | String | Macro run automatically when the service is selected. |
> | `default_category` | String | Category selected by default with the service. |
> | `default_urgency` | String | Urgency selected by default with the service. |
> | `allow_all_categories` | Boolean | Whether every category can be selected with the service. |
> | `categories` | String (JSON) | Names of the categories allowed with the service (JSON array). |

> [accordion] Time Agreements
>
> Hour contracts (contratos de horas) registered in Movidesk.
>
> Table: `time_agreements` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Id of the hour contract. |
> | `name` | String | Name of the hour contract. |
> | `email_subject` | String | Subject of the contract's email. |
> | `email_description` | String | Body of the contract's email. |
> | `email_account` | String | Sender of the contract's email. |
> | `is_active` | Boolean | Whether the contract is active. |
> | `differentiate_hours_franchise` | Boolean | Whether the hour allowance differs by activity. |
> | `differentiate_hours_consumption` | Boolean | Whether hours and values differ by activity and hour type. |
> | `accumulate_unused_hours` | Boolean | Whether unused hours accumulate. |
> | `renewal_day` | Integer | Day of the month the contract renews. |
> | `contracted_hours` | Number | Hours contracted. |
> | `consumption_deadline` | Integer | Months accumulated hours can still be used. |
> | `email_send_day` | Integer | Day of the month the email is sent. |
> | `base_amount` | Number | Base amount of the contract. |
> | `created_on` | Datetime | When the contract was created. |
> | `disabled_date` | Datetime | When the contract was disabled. |

> [accordion] Activities
>
> Activities agents can log time against.
>
> Table: `activities` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Id of the activity. |
> | `name` | String | Name of the activity. |
> | `is_active` | Boolean | Whether the activity is active. |
> | `is_allows_all_teams` | Boolean | Whether the activity is available to every team. |
> | `teams` | String (JSON) | Teams the activity is available to (JSON array). |

> [accordion] Survey Questions
>
> Questions of the satisfaction surveys.
>
> Table: `survey_questions` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Id of the question. |
> | `type` | Integer | Question type: 1 satisfied/unsatisfied, 2 smiley faces, 3 NPS, 4 yes/no. |
> | `is_active` | Boolean | Whether the question is active. |
> | `description` | String | Text of the question in Portuguese (pt-BR), or in its only language. |
> | `languages` | String (JSON) | Text of the question in each language: cultureId, description (JSON array). |

> [accordion] Survey Responses
>
> Answers to the satisfaction surveys given since the Start Date (first sync and full syncs). Each sync reads the answers given since the previous one.
>
> Table: `survey_responses` · Primary key: `id` · Sync: Incremental (`response_date`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Id of the answer. |
> | `question_id` | String | Id of the question answered (see survey\_questions). |
> | `client_id` | String | Reference code of the client (person, company or department) who answered. |
> | `type` | Integer | Question type: 1 satisfied/unsatisfied, 2 smiley faces, 3 NPS, 4 yes/no. |
> | `ticket_id` | Integer | Number of the ticket the answer is about. |
> | `response_date` | Datetime | When the answer was given (UTC); used as the incremental replication key. |
> | `commentary` | String | Comment left with the answer. |
> | `value` | Integer | Score by type: 1 satisfied / 2 unsatisfied; smiley faces 1 (very unsatisfied) to 5 (very satisfied); NPS 0 to 10; 1 yes / 2 no. |

## Implementation Notes

### Data Quality Considerations

* **How tickets stay up to date.** Movidesk moves a ticket's last update date whenever anything changes in it (a new action, a status or owner change, an edited field). Each sync reads the tickets updated since the previous one, minus 2 hours to cover Movidesk's own replication delay, and loads each one whole: the ticket and all its rows in the other ticket tables. A ticket updated while a sync runs is read by the next sync.
* **One read for all ticket tables.** The ticket tables are read together in a single pass. When you add a ticket table to an existing source, the next sync reads every ticket since the Start Date again, so the new table gets the full history.
* **Older history.** Movidesk serves tickets updated in the last 90 days from one place and older tickets from an archive refreshed once a day. A first sync or a full sync with an older Start Date reads both; incremental syncs only read the recent tickets. The archive can still hold an older version of a ticket updated since; both versions are read and the tables keep the most recent one. Rows that only exist in the older version (for example, an additional field that no longer applies) stay in the child tables.
* **Long histories are read in steps.** Tickets are read 30 days at a time, oldest first. On the first sync and on a full sync, the sync 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 long pause, each period is saved as it goes, and a sync that stops halfway continues from the last period saved. On a table set to Full table, everything is read before anything is saved, so the table is never replaced by part of the data.
* **One ticket table failing does not stop the others.** If one ticket table cannot be prepared, it is shown as failed and the other ticket tables are still updated. Rows that Movidesk sends without their identifier are left out, and the sync log says so.
* **Deleted data.** Actions and clients removed from a ticket stay in the tables with `is_deleted` set to true. Time appointments, expenses and attachments removed from an action, and tickets deleted in Movidesk, are not reported by the API and stay in the tables as they were last loaded. People deleted in Movidesk disappear from Persons on the next sync.
* **Additional fields.** Movidesk only sends the additional fields whose display rule currently applies to a ticket. A value whose rule stops applying stays in Ticket Custom Field Values as last loaded.
* **Action text.** `ticket_actions.description` is the plain text of each action; Movidesk does not send the HTML version in ticket lists.
* **Full table tables are never half updated.** The connector reads all the data of a table before writing any of it. If Movidesk 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 Movidesk, run a full sync of the source to accept it.
* **Features not available to the token.** If Movidesk refuses the token access to an area (for example, satisfaction surveys or hour contracts not enabled for your account), 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.
* **Survey answers.** Each sync reads the answers again from one day before the previous sync, so answers that show up late in Movidesk are not missed.

### API Limits & Performance

* Movidesk allows 10 requests per minute per account from 07:00 to 19:00 (Brasília time), shared by every integration using the token. The connector sends at most the configured Requests per Minute (10 by default) and, when Movidesk asks it to wait, waits and tells you in the sync log.
* Tickets are read up to 100 per request. At 10 requests per minute, a first sync of 10,000 tickets takes about 11 minutes of requests and 100,000 tickets about 2 hours. If the first sync fails, the next one starts it again.
* Persons, services, hour contracts, activities and survey questions are read whole on every sync: about one request per 500 people, so 20,000 people add about 4 minutes to each sync.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.