Octadesk is a Brazilian customer service platform. The connector extracts your help desk tickets and every interaction on them (comments, replies, status changes, and automations), along with the people and structure around them: requesters (customers), agents, organizations, groups and their members, products, subjects, tags, custom fields, and forms. With it you can analyze your support volume, response and resolution times, and your team’s workload in your Lakehouse.

The connector reads the Octadesk API documented at api-docs.octadesk.services, which covers the ticket help desk. WhatsApp and chat conversations are not included.

Configuring Octadesk as a Source

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

1. Add account access

Octadesk authenticates with an API token, the e-mail of the user who uses it, and your account’s subdomain. To create the token, in Octadesk go to Tickets > Geral > Código de integração, create a token, and copy it (it starts with octa.).

Use the e-mail and token of an administrator. Agents, groups, custom fields, and other settings are only visible to users whose profile can see them; streams the user cannot see are skipped with a warning.

The following configurations are available:

Subdomain: the first part of your Octadesk address. For https://mycompany.octadesk.com, enter mycompany. Required.
User E-mail: the e-mail of an active Octadesk user. Required.
API Token: the token created in Código de integração. Required.
Start Date: on the first sync, tickets last updated from this date on are extracted, with their interactions. Later syncs only read tickets updated since the previous one. Required.
Requests Per Minute: how fast the connector may call Octadesk. The default is 120.

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: Tickets and Ticket Interactions support INCREMENTAL. The other streams are FULL_TABLE. Read more about Sync Types here.

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). Optionally, you can define some additional settings:

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.
Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.

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

Below you’ll find all available data streams from Octadesk and their corresponding fields. API reference: Octadesk API.

Timestamps are stored in UTC. Objects and lists (custom fields, interactions, comments, attachments, phone numbers) are stored as JSON text, and the most used values inside them also get their own columns (for example product_id, organization_name, person_email). Every table also has a raw_payload column with the whole record as Octadesk returned it.

Ticket Interactions are read one ticket at a time, for the tickets updated since the previous sync. The first sync of an account with many tickets can take a while; the following ones only read what changed.

Tickets

Tickets of the account (GET /tickets/search), with requester, assignee, group, status, subject, product, and the first, last, and last human interaction. Read incrementally by the day of the last update: each sync reads the tickets updated since the previous one (the day before the last sync point is re-read).Primary key: id · Incremental key: last_date_update

Field	Type	Description
`id`	String	Unique identifier (UUID) of the ticket.
`number`	Integer	Ticket number shown in Octadesk (sequential within the account).
`summary`	String	Subject line of the ticket.
`description`	String	Description of the ticket (HTML).
`description_as_text`	String	Description of the ticket as plain text.
`id_type`	String	Identifier of the ticket type.
`type_name`	String	Ticket type (problema, tarefa, dúvida, incidente, não especificado).
`id_priority`	String	Identifier of the priority.
`priority_name`	String	Priority of the ticket (alta, média, baixa).
`id_channel`	String	Identifier of the channel the ticket came in.
`number_channel`	Integer	Code of the channel the ticket came in (Octadesk NumberChannel enum).
`channel_name`	String	Name of the ticket’s channel.
`inbox_mail`	String	E-mail inbox that received the ticket.
`inbox_domain`	String	Domain of the inbox that received it.
`id_requester`	String	Identifier of the requester (customer).
`requester_name`	String	Name of the requester.
`requester_mail`	String	E-mail of the requester.
`requester_customer_code`	String	Customer code of the requester, when registered.
`requester_multi_channel_id`	String	Identifier of the requester on the multichannel integration.
`id_organization`	String	Identifier of the requester’s organization.
`organization_name`	String	Name of the requester’s organization.
`id_assigned`	String	Identifier of the agent assigned to it.
`assigned_name`	String	Name of the assigned agent.
`assigned_mail`	String	E-mail of the assigned agent.
`id_group_assigned`	String	Identifier of the group the ticket is assigned to.
`group_assigned_name`	String	Name of the assigned group.
`id_subject`	String	Identifier of the subject (assunto).
`topic_group_name`	String	Name of the subject’s topic group.
`topic_name`	String	Name of the ticket’s subject topic.
`id_current_status`	String	Identifier of the current status.
`current_status_name`	String	Current status (novo, pendente, em andamento, resolvido, rejeitado…).
`state_progress`	Integer	Code of the ticket’s progress state (Octadesk StateProgress enum).
`state_progress_name`	String	Name of the progress state.
`number_ticket_created_from`	Integer	Number of the ticket this one was created from, if any.
`tags`	Array	Tags of the ticket.
`tags_join`	String	Tags of the ticket, comma-joined.
`product_members_join`	String	Values of the related product’s fields, joined.
`product_id`	String	Identifier of the related product.
`product_sku`	String	SKU of the related product.
`product`	String	Related product (JSON object: id, sku, fields).
`open_date`	Datetime	When the ticket was opened (UTC).
`due_date`	Datetime	SLA due date of the ticket (UTC).
`done_date`	Datetime	When the ticket was solved (UTC).
`last_date_update`	Datetime	When the ticket was last updated (UTC); incremental replication key.
`last_person_update_id`	String	Identifier of the person who last updated the ticket.
`last_person_update_name`	String	Name of the person who last updated the ticket.
`last_person_update_email`	String	E-mail of the person who last updated the ticket.
`last_person_update`	String	Person who last updated the ticket (JSON object).
`attachments`	String	Files attached to the ticket (JSON array).
`first_interaction`	String	First interaction of the ticket (JSON object).
`last_interaction`	String	Latest interaction of the ticket (JSON object).
`last_human_interaction`	String	Latest interaction made by a person, not an automation (JSON object).
`cc`	Array	E-mails copied on the ticket.
`cco`	Array	E-mails blind-copied on the ticket.
`merge`	String	Merge information: parent and child ticket numbers (JSON object).
`custom_field`	String	Custom fields of the ticket, keyed by field code (JSON object).
`requester_custom_field`	String	Custom fields of the requester (JSON object).
`organization_custom_field`	String	Custom fields of the requester’s organization (JSON object).
`has_custom_work_flow`	Boolean	Whether the ticket follows a custom workflow.
`current_step_flow_type`	Integer	Code of the current workflow step type (Octadesk TypeStepFlow enum).
`current_step_flow_name`	String	Name of the current workflow step.
`survey`	String	Satisfaction survey of the ticket (JSON object).
`is_survey_applied`	Boolean	Whether a satisfaction survey was sent for the ticket.
`multi_channel_field`	String	Multichannel integration data of the ticket (JSON object).
`id_company_ticket_share`	String	Identifier of the company the ticket is shared with.
`company_ticket_share`	String	Company the ticket is shared with (JSON object).
`company_ticket_share_active`	Boolean	Whether the ticket sharing is active.
`company_ticket_share_number`	Integer	Number of the ticket on the company it is shared with.
`reported_as_spam`	Boolean	Whether the ticket is marked as spam.
`total_human_interactions`	Integer	Number of interactions made by people.
`total_interactions`	Integer	Number of interactions, automations included.
`total_employee_interactions`	Integer	Number of interactions made by agents.
`id_form`	String	Identifier of the form the ticket was opened with.
`octadesk_number_url`	String	Link to the ticket in Octadesk.
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Ticket Interactions

Every interaction of the tickets read in the sync (GET /tickets/{number}/interactions, one call per ticket): public and internal comments, e-mail replies, status and property changes, and automation actions.Primary key: id · Incremental key: date_creation

Field	Type	Description
`id`	String	Unique identifier of the interaction.
`ticket_number`	Integer	Number of the ticket it belongs to.
`ticket_id`	String	Identifier (UUID) of the ticket it belongs to.
`date_creation`	Datetime	When the interaction happened (UTC); incremental replication key.
`person_id`	String	Identifier of the person who interacted.
`person_name`	String	Name of the person who interacted.
`person_email`	String	E-mail of the person who interacted.
`person_type`	Integer	Kind of person who interacted: 1 agent, 2 customer, 3 trigger, 4 system, 5 sharing agent.
`person`	String	Person who interacted (JSON object).
`is_human_interaction`	Boolean	Whether a person (not an automation) made the interaction.
`comments`	String	Comments of the interaction: public, internal, e-mail (JSON array).
`attachments`	String	Files attached to the interaction (JSON array).
`properties_changes`	String	Ticket properties changed by the interaction (JSON object).
`multi_channel_field`	String	Multichannel integration data of the interaction (JSON object).
`has_multi_channel_comment`	Boolean	Whether the interaction carries a multichannel comment.
`forward_reply_comment`	String	Forwarded reply of the interaction (JSON object).
`forward_comment`	String	Forwarded comment of the interaction (JSON object).
`multi_channel_comment`	String	Multichannel comment of the interaction (JSON object).
`internal_comment`	String	Internal comment of the interaction (JSON object).
`spam_status`	String	Whether this interaction marked or unmarked the ticket as spam.
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Requesters

Customers (requesters) registered in the account (GET /persons/requesters), with their organization, phone numbers, custom fields, and responsible agent.Primary key: id

Field	Type	Description
`id`	String	Unique identifier (UUID) of the person.
`name`	String	Name of the person.
`email`	String	Main e-mail of the person.
`date_creation`	Datetime	When the person was registered (UTC).
`is_enabled`	Boolean	Whether the person is active in Octadesk.
`type`	Integer	Kind of person: 0 none, 1 agent, 2 customer, 3 trigger, 4 system, 5 sharing agent, 6 sharing customer.
`role_type`	Integer	Role of the person: 0 none, 1 account owner, 2 admin, 3 master agent, 4 agent, 5 client, 6 corporate.
`permission_type`	Integer	Permission level of the person (Octadesk PermissionType enum).
`permission_view`	Integer	Which tickets the person can see (Octadesk PermissionViewType enum).
`participant_permission`	Integer	Permission on tickets the person took part in (Octadesk enum).
`is_locked`	Boolean	Whether the person’s access is locked.
`customer_code`	String	Customer code registered for the person.
`others_email`	Array	Other e-mails of the person.
`others_customer_code`	String	Other customer codes of the person (JSON array of key/value pairs).
`id_contact_status`	String	Identifier of the contact status.
`contact_status`	String	Name of the contact status.
`phone_contacts`	String	Phone numbers of the person: number, country code, type (JSON array).
`custom_field`	String	Custom fields of the person, keyed by field code (JSON object).
`organization_id`	String	Identifier of the person’s main organization.
`organization_name`	String	Name of the person’s main organization.
`organization`	String	Main organization of the person (JSON object).
`organizations`	String	Every organization the person belongs to (JSON array).
`groups`	String	Groups the person belongs to (JSON array).
`responsible_id`	String	Identifier of the agent responsible for this customer.
`responsible_name`	String	Name of the agent responsible for this customer.
`responsible_email`	String	E-mail of the agent responsible for this customer.
`products`	String	Products linked to the person (JSON array).
`apps`	String	Octadesk apps linked to the person and their fields (JSON array).
`my_apps`	Array	Identifiers of the apps the person uses.
`my_ticket_views`	Array	Identifiers of the ticket views the person uses.
`thumb_url`	String	Link to the person’s picture.
`facebook_id`	String	Facebook identifier of the person.
`facebook_user_name`	String	Facebook user name of the person.
`home_page`	String	Home page settings of the person (JSON object).
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Agents

Agents (employees) of the account (GET /persons/agents), with their role, permissions, and groups.Primary key: id

Field	Type	Description
`id`	String	Unique identifier (UUID) of the person.
`name`	String	Name of the person.
`email`	String	Main e-mail of the person.
`date_creation`	Datetime	When the person was registered (UTC).
`is_enabled`	Boolean	Whether the person is active in Octadesk.
`type`	Integer	Kind of person: 0 none, 1 agent, 2 customer, 3 trigger, 4 system, 5 sharing agent, 6 sharing customer.
`role_type`	Integer	Role of the person: 0 none, 1 account owner, 2 admin, 3 master agent, 4 agent, 5 client, 6 corporate.
`permission_type`	Integer	Permission level of the person (Octadesk PermissionType enum).
`permission_view`	Integer	Which tickets the person can see (Octadesk PermissionViewType enum).
`participant_permission`	Integer	Permission on tickets the person took part in (Octadesk enum).
`is_locked`	Boolean	Whether the person’s access is locked.
`customer_code`	String	Customer code registered for the person.
`others_email`	Array	Other e-mails of the person.
`others_customer_code`	String	Other customer codes of the person (JSON array of key/value pairs).
`id_contact_status`	String	Identifier of the contact status.
`contact_status`	String	Name of the contact status.
`phone_contacts`	String	Phone numbers of the person: number, country code, type (JSON array).
`custom_field`	String	Custom fields of the person, keyed by field code (JSON object).
`organization_id`	String	Identifier of the person’s main organization.
`organization_name`	String	Name of the person’s main organization.
`organization`	String	Main organization of the person (JSON object).
`organizations`	String	Every organization the person belongs to (JSON array).
`groups`	String	Groups the person belongs to (JSON array).
`responsible_id`	String	Identifier of the agent responsible for this customer.
`responsible_name`	String	Name of the agent responsible for this customer.
`responsible_email`	String	E-mail of the agent responsible for this customer.
`products`	String	Products linked to the person (JSON array).
`apps`	String	Octadesk apps linked to the person and their fields (JSON array).
`my_apps`	Array	Identifiers of the apps the person uses.
`my_ticket_views`	Array	Identifiers of the ticket views the person uses.
`thumb_url`	String	Link to the person’s picture.
`facebook_id`	String	Facebook identifier of the person.
`facebook_user_name`	String	Facebook user name of the person.
`home_page`	String	Home page settings of the person (JSON object).
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Organizations

Organizations (companies) your customers belong to, disabled ones included (GET /organizations).Primary key: id

Field	Type	Description
`id`	String	Unique identifier (UUID) of the organization.
`name`	String	Name of the organization.
`description`	String	Description of the organization.
`date_creation`	Datetime	When the organization was registered (UTC).
`is_enabled`	Boolean	Whether the organization is active.
`domains`	Array	E-mail domains that identify the organization’s people.
`group_id`	String	Identifier of the group that serves the organization.
`group_name`	String	Name of the group that serves it.
`group`	String	Group that serves the organization (JSON object).
`products`	String	Products linked to the organization (JSON array).
`custom_field`	String	Custom fields of the organization, keyed by field code (JSON object).
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Groups

Agent groups (teams) of the account (GET /groups).Primary key: id

Field	Type	Description
`id`	String	Unique identifier (UUID) of the group.
`name`	String	Name of the group.
`description`	String	Description of the group.
`date_creation`	Datetime	When the group was created (UTC).
`is_enabled`	Boolean	Whether the group is active.
`standard`	Boolean	Whether this is the account’s default group.
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Group Members

Agents that belong to each group, one row per group and agent (GET /groups/{id}/persons).Primary key: group_id, id

Field	Type	Description
`group_id`	String	Identifier of the group.
`id`	String	Unique identifier (UUID) of the person.
`name`	String	Name of the person.
`email`	String	Main e-mail of the person.
`date_creation`	Datetime	When the person was registered (UTC).
`is_enabled`	Boolean	Whether the person is active in Octadesk.
`type`	Integer	Kind of person: 0 none, 1 agent, 2 customer, 3 trigger, 4 system, 5 sharing agent, 6 sharing customer.
`role_type`	Integer	Role of the person: 0 none, 1 account owner, 2 admin, 3 master agent, 4 agent, 5 client, 6 corporate.
`permission_type`	Integer	Permission level of the person (Octadesk PermissionType enum).
`permission_view`	Integer	Which tickets the person can see (Octadesk PermissionViewType enum).
`participant_permission`	Integer	Permission on tickets the person took part in (Octadesk enum).
`is_locked`	Boolean	Whether the person’s access is locked.
`customer_code`	String	Customer code registered for the person.
`others_email`	Array	Other e-mails of the person.
`others_customer_code`	String	Other customer codes of the person (JSON array of key/value pairs).
`id_contact_status`	String	Identifier of the contact status.
`contact_status`	String	Name of the contact status.
`phone_contacts`	String	Phone numbers of the person: number, country code, type (JSON array).
`custom_field`	String	Custom fields of the person, keyed by field code (JSON object).
`organization_id`	String	Identifier of the person’s main organization.
`organization_name`	String	Name of the person’s main organization.
`organization`	String	Main organization of the person (JSON object).
`organizations`	String	Every organization the person belongs to (JSON array).
`groups`	String	Groups the person belongs to (JSON array).
`responsible_id`	String	Identifier of the agent responsible for this customer.
`responsible_name`	String	Name of the agent responsible for this customer.
`responsible_email`	String	E-mail of the agent responsible for this customer.
`products`	String	Products linked to the person (JSON array).
`apps`	String	Octadesk apps linked to the person and their fields (JSON array).
`my_apps`	Array	Identifiers of the apps the person uses.
`my_ticket_views`	Array	Identifiers of the ticket views the person uses.
`thumb_url`	String	Link to the person’s picture.
`facebook_id`	String	Facebook identifier of the person.
`facebook_user_name`	String	Facebook user name of the person.
`home_page`	String	Home page settings of the person (JSON object).
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Contact Statuses

Statuses customers can be tagged with (GET /persons/contact-status).Primary key: id

Field	Type	Description
`id`	String	Unique identifier of the contact status.
`name`	String	Name of the contact status.
`default`	Boolean	Whether this is the default contact status.
`created_by_id`	String	Identifier of the person who created the status.
`created_by_name`	String	Name of the person who created it.
`created_by`	String	Person who created the status (JSON object).
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Products

Products registered in the account, disabled ones included (GET /products/search).Primary key: id

Field	Type	Description
`id`	String	Unique identifier (UUID) of the product.
`members_join`	String	Values of the product’s fields, joined (how Octadesk names the product).
`product_group_id`	String	Identifier of the product group the product belongs to.
`product_group_name`	String	Name of the product group.
`product_group`	String	Product group of the product (JSON object).
`thumb_url`	String	Link to the product’s picture.
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Product Groups

Product groups (catalogs) and the fields their products are described with (GET /products/groups).Primary key: id

Field	Type	Description
`id`	String	Unique identifier (UUID) of the product group.
`name`	String	Name of the product group.
`description`	String	Description of the product group.
`date_creation`	Datetime	When the product group was created (UTC).
`is_enabled`	Boolean	Whether the product group is active.
`fields`	Array	Fields the group’s products are described with.
`products`	String	Products of the group, when the listing includes them (JSON array).
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Subjects

Ticket subjects (assuntos), with their topic and topic group (GET /subjects).Primary key: id

Field	Type	Description
`id`	String	Unique identifier (UUID) of the subject.
`name`	String	Name of the subject.
`is_enabled`	Boolean	Whether the subject is active.
`invisible_to_client`	Boolean	Whether customers cannot pick this subject.
`id_topic`	String	Identifier of the subject’s topic.
`topic_name`	String	Name of the subject’s topic.
`topic`	String	Topic of the subject (JSON object).
`id_topic_group`	String	Identifier of the topic group.
`topic_group_name`	String	Name of the topic group.
`topic_group`	String	Topic group of the subject (JSON object).
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Field	Type	Description
`id`	String	Unique identifier (UUID) of the custom field.
`field_id`	String	Code of the field, the key it appears under in records’ custom_field.
`title`	String	Label of the field.
`description`	String	Description of the field.
`type`	Integer	Kind of field: text, list, date, number… (Octadesk FieldType enum).
`domain_type`	Integer	Octadesk domain the field applies to (DomainType enum: tickets, people…).
`required`	Boolean	Whether the field is mandatory.
`is_enabled`	Boolean	Whether the field is active.
`is_customer_visible`	Boolean	Whether customers can see the field.
`is_customer_editable`	Boolean	Whether customers can fill the field.
`is_searchable`	Boolean	Whether the field can be searched.
`is_show_at_close`	Boolean	Whether the field is asked when a conversation is closed.
`is_show_in_conversation_details`	Boolean	Whether the field shows in the conversation details.
`order`	Integer	Display position of the field.
`alphabetically_ordered`	Boolean	Whether the field’s options are sorted alphabetically.
`hint`	String	Hint shown next to the field.
`place_holder`	String	Placeholder of the field.
`list_item`	String	Options of a list field: order and text (JSON array).
`levels`	String	Options of a multi-level field (JSON array).
`reflected_fields`	String	Fields this one is mirrored to (JSON array).
`new_reflection_fields`	String	New mirrored fields of this one (JSON array).
`date_creation`	Datetime	When the field was created (UTC).
`raw_payload`	String	The whole record exactly as Octadesk returned it (JSON object), including fields that have no column of their own.

Documentation

Get started

Context

Activate

Workspace

Resources

Octadesk as a data source

Configuring Octadesk 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

​Configuring Octadesk 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

Configuring Octadesk 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