> ## 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.

# CustomerX as a data source

> Bring clients, contacts, contracts, NPS and CSAT answers, tasks, tickets and health scores from CustomerX to Nekt.

CustomerX is a Brazilian customer success platform: it keeps your clients and their contacts, contracts and additives, journeys and tasks, support tickets, NPS and CSAT surveys, and computes indicators such as the health score and the churn risk of each client. This connector brings all of that to your Catalog, so you can analyze retention, revenue, satisfaction and the work of your CS team next to your other data.

<Note>
  The connector only reads data. It never creates, changes or deletes anything in CustomerX.
</Note>

## Configuring CustomerX 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 CustomerX option from the list of connectors.

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

### 1. Add account access

The connector uses the **API token** of a CustomerX user. To copy it:

1. Log in to CustomerX with an **administrator** user. The API returns only what the token's user can see, so a CSM's token may leave out clients of other portfolios and other users' task boards.
2. Open the menu at the top right, click **Ver Perfil** (View profile) and copy the **Api Token** field.

The following configurations are available:

* **API Token**: the token copied above. It stops working when its user is deactivated or the token is regenerated.

* **Start Date** (advanced): only records changed on or after this date are extracted by the incremental streams (clients, contacts, contract additives, tasks, journey tasks, tickets, ticket activities and timeline events), and client health scores start at this date's month. Leave it empty to extract the whole history.

* **Lookback Days** (advanced): (Default: 1) how many days before the last extracted point each run reads again.

* **Full Refresh Days** (advanced): (Default: 7) every this many days, the incremental streams of clients, contacts, contract additives, tasks, journey tasks and tickets read every record again. CustomerX may change tags, custom field values, labels, checklists or a client's contract status without changing the record's last update date; this refresh keeps those columns at most this many days behind. Set 0 to turn it off.

* **Max Requests per Minute** (advanced): (Default: 40) how many requests per minute each run may make.

<Warning>
  CustomerX limits each API token to **60 requests per minute** on the Startup plan (120 on Growth, 240 on Scale and Enterprise), shared with every other integration that uses the same token. The default of 40 leaves room for them on any plan. If your plan allows more and the token is used only by Nekt, raise **Max Requests per Minute** to sync faster. When CustomerX signals the limit, the run waits and continues.
</Warning>

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.

<Warning>
  **Client Health Scores** costs one request per client on **every run**: CustomerX answers the health score of one client at a time and has no way to ask for all clients at once. With 2,000 clients and the default pace of 40 requests per minute, that stream alone takes about 50 minutes per run. Leave it unselected if you do not use it. After the first run, each run asks every client only for the current and the previous month, so the requests stay one per client but are small.
</Warning>

<Info>
  The other streams cost about one request per 100 records the first time and much less afterwards.
</Info>

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**: Clients, Contacts, Contract Additives, Tasks, Journey Tasks, Tickets, Ticket Activities, Timeline Events and Client Health Scores support INCREMENTAL, which is the recommended type for them. Contracts, NPS and CSAT answers, the churn risk and the registers (users, segments, tags and others) are FULL\_TABLE: they are read in full on every run, so their tables always show the current state. Read more about Sync Types [here](https://docs.nekt.com/get-started/core-concepts/types-of-sync).

<Note>
  CustomerX has no way to list deleted records. An incremental table keeps a record deleted in CustomerX until the next full sync; a FULL\_TABLE table drops it on the next run. Ticket Activities and Timeline Events are not part of the periodic re-read (**Full Refresh Days**): a full sync refreshes them.
</Note>

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), consider how often you want data to be extracted from this source. Once a day is usually enough for customer success analysis; if you select **Client Health Scores**, make sure a run fits between two triggers.

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](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an [Additional Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync). It reads every record again (removing records deleted in CustomerX from the incremental tables); a monthly one is enough.

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.</Warning>

<Info>
  Before writing anything, each run checks that the token can read every selected stream: one request per stream, plus every active user's task board for Board Steps and the client list and one client's scores for Client Health Scores. If a full-table stream is not readable (for example, other users' boards with a token that is not an administrator's), the run stops before writing and the log lists the streams to deselect or the access to grant; an incremental stream that is not readable is skipped with a warning and its table is kept as it is.
</Info>

# 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 | Description |
| - | - | - |
| Clients | `clients` | Every client (customer account) managed in CustomerX, with address, status derived from its contracts, segment, group, line of business, portfolio, tags, phones and custom field values. |
| Contacts | `contacts` | People at each client, with role, phones and custom field values. |
| Contracts | `contracts` | Contracts of each client: values, periods, plan, seller, renewal and cancellation. |
| Contract Additives | `contract_additives` | Amendments to contracts (upsells and downsells) with the value before and after each one. |
| Contract Plans | `contract_plans` | Plans that contracts can be linked to. |
| NPS Responses | `nps_responses` | Answers to NPS surveys: score, comment, send and answer dates, client and contact. |
| CSAT Responses | `csat_responses` | Answers to CSAT surveys: score, comment, dates, client and the question answered. |
| CSAT Questions | `csat_questions` | Questions of the CSAT surveys. |
| Tasks | `tasks` | Tasks of the CSM task board, with client, responsible user, schedule, completion and labels. |
| Journey Tasks | `journey_tasks` | Tasks of the clients' journeys, with the journey step they belong to, responsible user, schedule, completion and checklists. |
| Tickets | `tickets` | Support tickets with type, priority, status, agent, deadlines, client and contact. |
| Ticket Activities | `ticket_activities` | Activities logged on tickets. |
| Timeline Events | `timeline_events` | Events of the clients' timelines (new contracts, changes, notes). |
| Client Health Scores | `client_health_scores` | Monthly health score history of every client, one row per client and month. The current month is dated the day it was read and changes until the month closes. Costs one request per client on every run. |
| Clients Churn Risk | `clients_churn_risk` | Churn risk CustomerX currently assigns to each client. |
| Users | `users` | Users of your CustomerX account (CSMs and administrators). |
| Board Steps | `board_steps` | Lists (steps) of each active user's CSM task board. |
| Journey Templates | `journey_templates` | Journey templates the clients' journeys are created from. |
| Segments | `segments` | Client segments. |
| Groups | `groups` | Client groups. |
| Services | `services` | Lines of business (ramos de atividade) of the clients. |
| Portfolios | `portfolios` | Portfolios (carteiras) grouping clients and the users who handle them. |
| Sellers | `sellers` | Sellers linked to contracts. |
| Tags | `tags` | Tags available to clients and tasks. |
| Products | `products` | Products linked to journeys and contracts. |
| Contact Types | `contact_types` | Types of contact. |
| Custom Fields | `custom_fields` | Definitions of the custom fields of clients and contacts. Their values are in the custom\_attributes column of clients and contacts. |

Nested values (tags, phones, custom field values, labels, checklists) are JSON text. Records that have their own stream appear as ids in the others (for example `client_id` in contacts, tasks and tickets). Every timestamp is in UTC. Fields CustomerX returns that have no column yet are kept in `extra_fields`.

## Fields by stream

### Clients and contracts

<AccordionGroup>
  <Accordion title="Clients">
    Every client (customer account) managed in CustomerX, with address, status derived from its contracts, segment, group, line of business, portfolio, tags, phones and custom field values.

    Table: `clients` · Primary key: `id` · Sync: Incremental (`updated_at`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the client in CustomerX. |
    | `external_id_client` | String | Client code in your own systems (external ID); CustomerX generates a sequential one when none is given. |
    | `company_name` | String | Legal name (razão social) of the client. |
    | `trading_name` | String | Trade name (nome fantasia) of the client. |
    | `cnpj_cpf` | String | CNPJ (companies) or CPF (individuals) of the client, as formatted in CustomerX. |
    | `document_type` | String | Kind of document held in cnpj\_cpf. |
    | `ie_rg` | String | State registration (IE) for companies or identity card (RG) for individuals. |
    | `date_register` | Datetime | Date the client was registered as a customer (UTC). |
    | `email` | String | E-mail address of the client. |
    | `phone` | String | Phone number of the client. |
    | `cep` | String | Postal code (CEP) of the client's address. |
    | `country` | String | Country of the client's address. |
    | `state` | String | State (UF) of the client's address. |
    | `city` | String | City of the client's address. |
    | `street` | String | Street of the client's address. |
    | `district` | String | District (bairro) of the client's address. |
    | `number` | String | Street number of the client's address. |
    | `complement` | String | Address complement. |
    | `contract_status` | String | Client status derived by CustomerX from its contracts: without\_contract, active\_contract, contract\_canceled or contract\_finalized. |
    | `cancellation_date` | Datetime | When the client cancelled (UTC). |
    | `facebook` | String | Facebook page of the client. |
    | `linkedin` | String | LinkedIn page of the client. |
    | `twitter` | String | Twitter/X profile of the client. |
    | `instagram` | String | Instagram profile of the client. |
    | `youtube` | String | YouTube channel of the client. |
    | `site` | String | Website of the client. |
    | `client_segment_id` | Integer | Segment of the client (see the segments stream). |
    | `client_group_id` | Integer | Group of the client (see the groups stream). |
    | `client_service_id` | Integer | Line of business (ramo de atividade) of the client (see the services stream). |
    | `portfolio_id` | Integer | Portfolio (carteira) the client belongs to (see the portfolios stream). |
    | `parent_company` | Boolean | Whether the client is a head office (matriz) with branches. |
    | `branch_type` | String | How the client's branches relate to it: independent or dependent. |
    | `parent_client_id` | Integer | Head office of this client when it is a branch. |
    | `parent_client` | String (JSON) | Head office / branch information: is\_parent\_client and, for a branch, its head office (JSON). |
    | `origin` | String | Where the client record came from. |
    | `only_journey_by_contract` | Boolean | Whether the client's journeys are only created through contracts. |
    | `is_excluded` | Boolean | Whether the client was excluded in CustomerX. |
    | `exclusion_date` | Datetime | When the client was excluded (UTC). |
    | `tags` | String (JSON) | Tags linked to the client: id, description, color and dates of each tag (JSON). |
    | `journey_products` | String (JSON) | Journeys of the client and the products linked to each journey (JSON). |
    | `phones` | String (JSON) | Phone numbers of the client: number, ddi, is\_default, status (JSON). |
    | `custom_attributes` | String (JSON) | Values of the client's custom fields: custom\_attribute\_id, custom\_attribute\_external\_id, label, type\_attribute and value (JSON). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX, used as the incremental replication key (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Contacts">
    People at each client, with role, phones and custom field values.

    Table: `contacts` · Primary key: `id` · Sync: Incremental (`updated_at`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the contact in CustomerX. |
    | `external_id_contact` | String | Contact code in your own systems (external ID). |
    | `client_id` | Integer | Client the contact belongs to (see the clients stream). |
    | `external_id_client` | String | External ID of the client the contact belongs to. |
    | `name` | String | Name of the contact. |
    | `email` | String | E-mail address of the contact. |
    | `occupation` | String | Occupation / job title of the contact. |
    | `role` | String | Role of the contact at the client. |
    | `birthday` | Date | Birthday of the contact. |
    | `is_principal` | Boolean | Whether this is the client's main contact. |
    | `status` | Boolean | Whether the contact is active. |
    | `type_contact_id` | Integer | Contact type (see the contact\_types stream). |
    | `phone_fix` | String | Landline phone of the contact. |
    | `phone_cel` | String | Mobile phone of the contact. |
    | `phones` | String (JSON) | Phone numbers of the contact (JSON). |
    | `note` | String | Notes about the contact. |
    | `platform_active_user` | Boolean | Whether the contact is an active user of your platform. |
    | `custom_attributes` | String (JSON) | Values of the contact's custom fields: custom\_attribute\_id, custom\_attribute\_external\_id, label, type\_attribute and value (JSON). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX, used as the incremental replication key (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Contracts">
    Contracts of each client: values, periods, plan, seller, renewal and cancellation.

    Table: `contracts` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the contract in CustomerX. |
    | `external_id_contract` | String | Contract code in your own systems (external ID). |
    | `client_id` | Integer | Client of the contract (see the clients stream). |
    | `external_id_client` | String | External ID of the client of the contract. |
    | `description` | String | Description of the contract. |
    | `status` | String | Status of the contract (e.g. active, canceled, finalized). |
    | `date_sale` | Date | Date the contract was sold. |
    | `start_date` | Date | Start date of the current contract period. |
    | `final_date` | Date | End date of the current contract period. |
    | `cancellation_date` | Date | Date the contract was cancelled. |
    | `initial_start_date` | Datetime | Start of the contract's first period (UTC). |
    | `initial_final_date` | Datetime | End of the contract's first period (UTC). |
    | `contract_value` | Number | Current (recurring) value of the contract. |
    | `initial_value` | Number | Value of the contract when it was signed. |
    | `value_per_user` | Number | Value charged per user. |
    | `number_of_users` | Integer | Number of users covered by the contract. |
    | `auto_renovation` | Boolean | Whether the contract renews automatically. |
    | `renew_in_days` | Integer | Renewal period, in days. |
    | `cancellation_reason` | String | Free-text reason given for the cancellation. |
    | `reason_cancellation_id` | Integer | Registered cancellation reason. |
    | `reason_cancellation_description` | String | Description of the registered cancellation reason. |
    | `contract_plan_id` | Integer | Plan of the contract (see the contract\_plans stream). |
    | `seller_id` | Integer | Seller of the contract (see the sellers stream). |
    | `journey_products` | String (JSON) | Journeys and products linked to the contract (JSON). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Contract Additives">
    Amendments to contracts (upsells and downsells) with the value before and after each one.

    Table: `contract_additives` · Primary key: `id` · Sync: Incremental (`updated_at`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the additive in CustomerX. |
    | `external_id_additive` | String | Additive code in your own systems (external ID). |
    | `client_id` | Integer | Client of the additive (see the clients stream). |
    | `client_contract_id` | Integer | Contract the additive amends (see the contracts stream). |
    | `type_additive` | String | Kind of additive, as returned by CustomerX. |
    | `description` | String | Description of the additive. |
    | `note` | String | Notes about the additive. |
    | `date_sale` | Date | Date the additive was sold. |
    | `date_initial` | Date | Start date of the additive. |
    | `date_final` | Date | End date of the additive. |
    | `value_contract` | Number | Contract value before the additive. |
    | `value_additive` | Number | Value added (or removed) by the additive. |
    | `new_value_contract` | Number | Contract value after the additive. |
    | `value_per_user` | Number | Value charged per user. |
    | `number_of_users` | Integer | Number of users covered. |
    | `auto_renovation` | Boolean | Whether the additive renews automatically. |
    | `renew_in_days` | Integer | Renewal period, in days. |
    | `contract_plan_id` | Integer | Plan set by the additive (see the contract\_plans stream). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX, used as the incremental replication key (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Contract Plans">
    Plans that contracts can be linked to.

    Table: `contract_plans` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the plan in CustomerX. |
    | `external_id` | String | Plan code in your own systems (external ID). |
    | `description` | String | Name of the plan. |
    | `number_users` | Integer | Number of users included in the plan. |
    | `status` | Boolean | Whether the plan is active. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>
</AccordionGroup>

### Surveys

<AccordionGroup>
  <Accordion title="NPS Responses">
    Answers to NPS surveys: score, comment, send and answer dates, client and contact.

    Table: `nps_responses` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the NPS answer in CustomerX. |
    | `question` | String | Question asked in the NPS survey. |
    | `response` | Number | Score given (0 to 10). |
    | `note` | String | Comment left with the score. |
    | `date_send` | Datetime | When the survey was sent (UTC). |
    | `date_response` | Datetime | When the survey was answered (UTC). |
    | `user_email` | String | CustomerX user recorded on the answer (e-mail). |
    | `client_id` | Integer | Client that answered (see the clients stream). |
    | `external_id_client` | String | External ID of the client that answered. |
    | `contact_id` | Integer | Contact that answered (see the contacts stream). |
    | `external_id_contact` | String | External ID of the contact that answered. |
    | `contact_name` | String | Name of the contact that answered. |
    | `contact_email` | String | E-mail of the contact that answered. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="CSAT Responses">
    Answers to CSAT surveys: score, comment, dates, client and the question answered.

    Table: `csat_responses` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the CSAT answer in CustomerX. |
    | `response` | Number | Score given. |
    | `note` | String | Comment left with the score. |
    | `date_send` | Datetime | When the survey was sent (UTC). |
    | `date_response` | Datetime | When the survey was answered (UTC). |
    | `email` | String | E-mail of the contact that answered. |
    | `external_id_client` | String | External ID of the client that answered. |
    | `external_id_contact` | String | External ID of the contact that answered. |
    | `survey_question_id` | Integer | Question answered (see the csat\_questions stream). |
    | `survey_question_description` | String | Description of the survey the question belongs to. |
    | `survey_question_text` | String | Text of the question answered. |
    | `survey_question_type` | String | Kind of question (e.g. csat). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="CSAT Questions">
    Questions of the CSAT surveys.

    Table: `csat_questions` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the question in CustomerX. |
    | `description` | String | Description of the survey. |
    | `question_text` | String | Text of the question. |
    | `type` | String | Kind of question (e.g. csat). |
    | `status` | Boolean | Whether the question is active. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>
</AccordionGroup>

### Tasks, tickets and timeline

<AccordionGroup>
  <Accordion title="Tasks">
    Tasks of the CSM task board, with client, responsible user, schedule, completion and labels.

    Table: `tasks` · Primary key: `id` · Sync: Incremental (`updated_at`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the task in CustomerX. |
    | `title` | String | Title of the task. |
    | `description` | String | Description of the task. |
    | `status` | Boolean | Task status flag as returned by CustomerX (true when the task is done). |
    | `position` | Integer | Position of the task in its board list. |
    | `dashboard_activities_step_id` | Integer | Board list (step) the task is in (see the board\_steps stream). |
    | `client_id` | Integer | Client of the task (see the clients stream). |
    | `external_id_client` | String | External ID of the client of the task. |
    | `user_id` | Integer | User responsible for the task (see the users stream). |
    | `date` | Datetime | Date of the task (UTC). |
    | `date_scheduled` | Datetime | When the task is scheduled to start (UTC). |
    | `date_scheduled_final` | Datetime | When the task is scheduled to end (UTC). |
    | `date_closure` | Datetime | When the task was completed (UTC). |
    | `filed` | Boolean | Whether the task is archived. |
    | `labels` | String (JSON) | Labels of the task: id, description, color, added\_on\_task\_at (JSON). |
    | `additional_contacts` | String (JSON) | Additional contacts linked to the task (JSON). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX, used as the incremental replication key (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Journey Tasks">
    Tasks of the clients' journeys, with the journey step they belong to, responsible user, schedule, completion and checklists.

    Table: `journey_tasks` · Primary key: `id` · Sync: Incremental (`updated_at`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the journey task in CustomerX. |
    | `external_id` | String | Task code in your own systems (external ID). |
    | `title` | String | Title of the task. |
    | `description` | String | Description of the task. |
    | `position` | Integer | Position of the task within its journey step. |
    | `date_scheduled` | Datetime | When the task is scheduled to start (UTC). |
    | `date_scheduled_final` | Datetime | When the task is scheduled to end (UTC). |
    | `date_closure` | Datetime | When the task was completed (empty while open) (UTC). |
    | `checks_done` | Integer | Checklist items done. |
    | `checks_total` | Integer | Checklist items in total. |
    | `user_id` | Integer | User responsible for the task (see the users stream). |
    | `contact_id` | Integer | Contact the task is about (see the contacts stream). |
    | `creator_id` | Integer | User who created the task. |
    | `reporter_id` | Integer | User who reported the task. |
    | `journey_step_id` | Integer | Journey step (etapa) the task belongs to. |
    | `journey_step_description` | String | Name of the journey step. |
    | `journey_step_position` | Integer | Position of the step in the journey. |
    | `journey_step_progress` | String | Progress of the step (e.g. pending, in\_progress, done). |
    | `journeys_client_id` | Integer | The client's journey the task belongs to. |
    | `client_id` | Integer | Client of the journey (see the clients stream). |
    | `external_id_client` | String | External ID of the client of the journey. |
    | `journey_id` | Integer | Journey the task belongs to. |
    | `journey_description` | String | Name of the journey. |
    | `labels` | String (JSON) | Labels of the task (JSON). |
    | `additional_contacts` | String (JSON) | Additional contacts linked to the task (JSON). |
    | `checklists` | String (JSON) | Checklists of the task and their items (JSON). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX, used as the incremental replication key (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Tickets">
    Support tickets with type, priority, status, agent, deadlines, client and contact.

    Table: `tickets` · Primary key: `id` · Sync: Incremental (`updated_at`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the ticket in CustomerX. |
    | `external_id` | String | Ticket code in your own systems (external ID). |
    | `title` | String | Title of the ticket. |
    | `description` | String | Description of the ticket. |
    | `comment` | String | Comment on the ticket. |
    | `type_ticket` | String | Kind of ticket (e.g. BUG). |
    | `priority` | String | Priority of the ticket. |
    | `status` | String | Status of the ticket (e.g. pending). |
    | `attendant_name` | String | Name of the agent handling the ticket. |
    | `attendant_email` | String | E-mail of the agent handling the ticket. |
    | `date_opening` | Datetime | When the ticket was opened (UTC). |
    | `date_reopening` | Datetime | When the ticket was reopened (UTC). |
    | `date_closing` | Datetime | When the ticket was closed (UTC). |
    | `date_finalized` | Datetime | When the ticket was finalized (UTC). |
    | `date_deadline_attendance` | Datetime | Deadline for the first response (UTC). |
    | `date_deadline_closing` | Datetime | Deadline for closing the ticket (UTC). |
    | `client_id` | Integer | Client of the ticket (see the clients stream). |
    | `external_id_client` | String | External ID of the client of the ticket. |
    | `contact_id` | Integer | Contact who opened the ticket (see the contacts stream). |
    | `external_id_contact` | String | External ID of the contact who opened the ticket. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX, used as the incremental replication key (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Ticket Activities">
    Activities logged on tickets.

    Table: `ticket_activities` · Primary key: `id` · Sync: Incremental (`updated_at`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the activity in CustomerX. |
    | `external_id` | String | Activity code in your own systems (external ID). |
    | `ticket_id` | Integer | Ticket the activity belongs to (see the tickets stream). |
    | `ticket_external_id` | String | External ID of the ticket the activity belongs to. |
    | `title` | String | Title of the activity. |
    | `description` | String | Description of the activity. |
    | `comment` | String | Comment on the activity. |
    | `type_activity` | String | Kind of activity (e.g. Repasse). |
    | `date_registration` | Datetime | When the activity happened (UTC). |
    | `status` | Boolean | Activity status flag as returned by CustomerX. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX, used as the incremental replication key (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Timeline Events">
    Events of the clients' timelines (new contracts, changes, notes).

    Table: `timeline_events` · Primary key: `id` · Sync: Incremental (`updated_at`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the timeline event in CustomerX. |
    | `title` | String | Title of the event. |
    | `body` | String | Text of the event. |
    | `operation` | String | Kind of event (e.g. client\_contract). |
    | `client_id` | Integer | Client of the event (see the clients stream). |
    | `external_id_client` | String | External ID of the client of the event. |
    | `user_id` | Integer | User who generated the event (see the users stream). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX, used as the incremental replication key (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>
</AccordionGroup>

### Indicators

<AccordionGroup>
  <Accordion title="Client Health Scores">
    Monthly health score history of every client, one row per client and month. The current month is dated the day it was read and changes until the month closes. Costs one request per client on every run.

    Table: `client_health_scores` · Primary key: `client_id`, `reference_month` · Sync: Incremental (`date`)

    | Field | Type | Description |
    | :- | :- | :- |
    | `client_id` | Integer | Client the score belongs to (see the clients stream). |
    | `reference_month` | String | Month of the score (YYYY-MM). |
    | `external_id_client` | String | External ID of the client. |
    | `date` | Date | Date of the score: the month's last day, or the day it was read for the current (still changing) month; used as the incremental replication key. |
    | `value` | Number | Health score of the client in that month. |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Clients Churn Risk">
    Churn risk CustomerX currently assigns to each client.

    Table: `clients_churn_risk` · Primary key: `external_id_client` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `external_id_client` | String | External ID of the client. |
    | `churn_status` | String | Churn risk CustomerX assigns to the client: Muito Baixa, Baixa, Alta or Muito Alta. |
    | `client_id` | Integer | Client (see the clients stream), when CustomerX returns it. |
    | `company_name` | String | Legal name of the client. |
    | `trading_name` | String | Trade name of the client. |
    | `cnpj_cpf` | String | CNPJ or CPF of the client. |
    | `client_date_register` | Datetime | Date the client was registered as a customer (UTC). |
    | `client_email` | String | E-mail of the client. |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>
</AccordionGroup>

### Registers

<AccordionGroup>
  <Accordion title="Users">
    Users of your CustomerX account (CSMs and administrators).

    Table: `users` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the user in CustomerX. |
    | `external_id_user` | String | User code in your own systems (external ID). |
    | `name` | String | Name of the user. |
    | `email` | String | E-mail of the user. |
    | `status` | Boolean | Whether the user is active. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Board Steps">
    Lists (steps) of each active user's CSM task board. Users marked inactive in CustomerX are skipped.

    Table: `board_steps` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the board list (step) in CustomerX. |
    | `user_id` | Integer | User whose board the list belongs to (empty when CustomerX could not be asked per user). |
    | `description` | String | Name of the list. |
    | `position` | Integer | Position of the list on the board (ascending). |
    | `status` | Boolean | Whether the list is active. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Journey Templates">
    Journey templates the clients' journeys are created from.

    Table: `journey_templates` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the journey template in CustomerX. |
    | `external_id` | String | Journey template code in your own systems (external ID). |
    | `description` | String | Name of the journey template. |
    | `status` | Boolean | Whether the journey template is active. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Segments">
    Client segments.

    Table: `segments` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the segment in CustomerX. |
    | `external_id` | String | Segment code in your own systems (external ID). |
    | `description` | String | Name of the segment. |
    | `status` | Boolean | Whether the segment is active. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Groups">
    Client groups.

    Table: `groups` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the group in CustomerX. |
    | `external_id` | String | Group code in your own systems (external ID). |
    | `description` | String | Name of the group. |
    | `status` | Boolean | Whether the group is active. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Services">
    Lines of business (ramos de atividade) of the clients.

    Table: `services` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the line of business (ramo de atividade) in CustomerX. |
    | `external_id` | String | Line of business (ramo de atividade) code in your own systems (external ID). |
    | `description` | String | Name of the line of business (ramo de atividade). |
    | `status` | Boolean | Whether the line of business (ramo de atividade) is active. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Portfolios">
    Portfolios (carteiras) grouping clients and the users who handle them.

    Table: `portfolios` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the portfolio in CustomerX. |
    | `external_id` | String | Portfolio code in your own systems (external ID). |
    | `description` | String | Name of the portfolio. |
    | `status` | Boolean | Whether the portfolio is active. |
    | `client_ids` | String (JSON) | Ids of the clients in the portfolio (JSON). |
    | `user_ids` | String (JSON) | Ids of the users who handle the portfolio (JSON). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Sellers">
    Sellers linked to contracts.

    Table: `sellers` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the seller in CustomerX. |
    | `external_id` | String | Seller code in your own systems (external ID). |
    | `name` | String | Name of the seller. |
    | `status` | Boolean | Whether the seller is active. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Tags">
    Tags available to clients and tasks.

    Table: `tags` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the tag in CustomerX. |
    | `description` | String | Name of the tag. |
    | `color` | String | Color of the tag (hex). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Products">
    Products linked to journeys and contracts.

    Table: `products` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the product in CustomerX. |
    | `external_id` | String | Product code in your own systems (external ID). |
    | `name` | String | Name of the product. |
    | `description` | String | Description of the product. |
    | `status` | Integer | Status of the product as returned by CustomerX (1 = active). |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Contact Types">
    Types of contact.

    Table: `contact_types` · Primary key: `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Unique identifier of the contact type in CustomerX. |
    | `external_id` | String | Contact type code in your own systems (external ID). |
    | `description` | String | Name of the contact type. |
    | `status` | Boolean | Whether the contact type is active. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>

  <Accordion title="Custom Fields">
    Definitions of the custom fields of clients and contacts. Their values are in the custom\_attributes column of clients and contacts.

    Table: `custom_fields` · Primary key: `type_operation`, `id` · Sync: Full table

    | Field | Type | Description |
    | :- | :- | :- |
    | `id` | Integer | Identifier of the custom field in CustomerX (unique per type\_operation). |
    | `type_operation` | String | Whose field it is: client or contact. |
    | `external_id` | String | Custom field code (external ID), as referenced in custom\_attribute\_external\_id. |
    | `description` | String | Label of the custom field. |
    | `observation` | String | Notes about the custom field. |
    | `type_attribute` | String | Value type of the field: string, number, date or currency. |
    | `origin` | Integer | Origin of the field, as returned by CustomerX. |
    | `created_at` | Datetime | When the record was created in CustomerX (UTC). |
    | `updated_at` | Datetime | When the record was last changed in CustomerX (UTC). |
    | `extra_fields` | String (JSON) | Fields CustomerX returned that this connector does not map to a column yet, as a JSON object (null when none). |
  </Accordion>
</AccordionGroup>


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