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

# Leadstaker as a data source

> Bring contacts, deals, chats, messages, calls, leads, tasks, notes and ad touchpoints from Leadstaker to Nekt.

Leadstaker is a platform to capture, qualify and manage leads. It brings together the CRM (contacts and deals moving through pipelines), conversations on WhatsApp and other channels, phone calls with transcripts and AI summaries, chatbot forms, tasks and notes, and traces every lead back to the ad, campaign or channel that brought it.

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

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

### 1. Add account access

You'll need a Leadstaker **API key**. In the Leadstaker dashboard, open the **project settings** and click **generate token**. Copy the key right away: Leadstaker shows it only once.

The following configurations are available:

* **API Key**: the Leadstaker project API key. A key reads exactly one project; if you have more than one project, create one source per project.

* **Start Date**: (Optional) On the first sync, and on any full sync, contacts, deals, chats, messages, calls, leads, tasks and notes are read from records updated on or after this date. Leave it empty to bring all history.

* **Full walk interval (hours)**: (Advanced, default: 24) The Messages, Calls and Touchpoints streams are read chat by chat or contact by contact. Between full walks, a sync only visits the chats and contacts updated since the previous sync, which keeps it fast; every this many hours it visits all of them. A new message or call that does not update its chat or contact can take up to this long to appear. Set it to 0 to visit all of them on every sync (no delay, but much slower on large projects).

> [!WARNING]
>
> Every Leadstaker API key has an expiration date. When it expires, the sync fails with a message asking for a new key: generate a new one in the project settings and update it in the source.

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**: you can choose between INCREMENTAL and FULL\_TABLE.
  * Incremental: every time the extraction happens, we'll get only the new data, which is good if, for example, you want to keep every record ever fetched.
  * Full table: every time the extraction happens, we'll get the current state of the data, which is good if, for example, you don't want to have deleted data in your catalog.

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

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)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while. Leadstaker does not report deleted records, so a periodic full sync is the way to remove them from incremental tables.

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 | Description |
| - | - | - |
| Contacts | `contacts` | People in the project, with the values of their fields. Incremental by last update. |
| Deals | `deals` | Opportunities moving through a pipeline, each tied to a contact. Incremental by last update. |
| Chats | `chats` | Conversations with a contact over a connected channel (such as WhatsApp). Incremental by last update. |
| Messages | `messages` | Every message of every chat, inbound and outbound. Incremental by last update. |
| Calls | `calls` | Phone calls with their recording status, transcript and AI summary. Incremental by last update. |
| Touchpoints | `touchpoints` | Each time a lead reached the business, traced to the ad, campaign, channel or form that brought it. Refreshed for the contacts each sync visits. |
| Leads | `leads` | Chatbot conversations captured in the project, with the answers and where the visitor came from. Incremental by last update. |
| Tasks | `tasks` | Follow-up activities with a due date, attached to a deal (pending, overdue and completed). Incremental by last update. |
| Notes | `notes` | Free text attached to a contact or a deal. Incremental by last update. |
| Pipelines | `pipelines` | Pipelines (ordered sets of stages). |
| Pipeline Stages | `pipeline_stages` | Stages of every pipeline, including the closed (won/lost) ones. |
| Tags | `tags` | Labels that can be attached to deals. |
| Loss Reasons | `loss_reasons` | The reasons a deal can be marked as lost. |
| Fields | `fields` | Field definitions (built-in and custom) of contacts and deals: label, type and options. |
| Field Groups | `field_groups` | Sections that organize the fields in the interface. |

> [!NOTE]
>
> The **Messages**, **Calls** and **Touchpoints** streams are read chat by chat or contact by contact, because Leadstaker has no single list of them. Most syncs only visit the chats and contacts that changed since the previous sync; every **Full walk interval** hours a sync visits all of them, which takes longer on projects with many chats or contacts.

## Fields by stream

Contacts and deals do not have fixed columns for name, phone, e-mail or price: in Leadstaker those are **fields** configured per project. Their values come in the `fields` column as a JSON list of `{fieldId, value}`; join `fieldId` with the `id` of the **Fields** table to get each field's label and type.

> [accordion] Contacts
>
> * `id` - Unique identifier of the contact
> * `project_id` - Leadstaker project the contact belongs to
> * `responsible_id` - User responsible for the contact
> * `avatar` - URL of the contact's picture
> * `fields` - Field values of the contact (JSON list of `{fieldId, value}`)
> * `created_at` - When the contact was created
> * `updated_at` - When the contact was last updated (replication key)

> [accordion] Deals
>
> * `id` - Unique identifier of the deal
> * `project_id` - Leadstaker project
> * `contact_id` - Contact the deal belongs to
> * `pipeline_id` - Pipeline the deal is in
> * `stage_id` - Current stage of the deal
> * `stage_entered_at` - When the deal entered its current stage
> * `responsible_id` - User responsible for the deal
> * `agent_id` - AI agent assigned to the deal
> * `tag_ids` - Tags attached to the deal (list)
> * `loss_reason_id` - Reason the deal was lost
> * `closed_at` - When the deal was closed (won or lost)
> * `last_lead_message_at` - When the lead last sent a message
> * `is_test` - Whether this is a test deal
> * `fields` - Field values of the deal, including the price (JSON list of `{fieldId, value}`)
> * `created_at` - When the deal was created
> * `updated_at` - When the deal was last updated (replication key)

> [accordion] Chats
>
> * `id` - Unique identifier of the chat
> * `project_id` - Leadstaker project
> * `channel_id` - Connected channel of the chat
> * `channel_name` - Name the channel gave the lead (such as the WhatsApp profile name)
> * `external_id` - Identifier of the conversation on the channel
> * `contact_id` - Contact of the chat, when it has one
> * `pipeline_id` - Pipeline the chat is linked to
> * `status` - INBOX, OPEN or CLOSED
> * `unread_messages_count` - Number of unread messages
> * `is_test` - Whether this is a test chat
> * `identifier_phone`, `identifier_email`, `identifier_whatsapp_lid`, `identifier_test_id`, `identifier_custom` - How the lead is identified on the channel
> * `profile_name`, `profile_avatar` - Name and picture shown for the chat
> * `agent_id`, `agent_status` - AI agent of the chat and whether it is ACTIVE or DISABLED
> * `archived_at` - When the chat was archived
> * `created_at` - When the chat was created
> * `updated_at` - When the chat was last updated (replication key)

> [accordion] Messages
>
> * `id` - Unique identifier of the message
> * `chat_id` - Chat the message belongs to
> * `project_id` - Leadstaker project
> * `type` - Message type (TEXT, IMAGE, VIDEO, AUDIO, DOCUMENT…)
> * `text` - Text of the message, or the caption of a media message
> * `content` - Full message content (JSON)
> * `sender_type`, `sender_id`, `sender_name` - Who sent the message
> * `sender` - Full sender (JSON)
> * `timestamp` - When the message was sent or received
> * `status` - PENDING, SENT, RECEIVED, READ, PLAYED or FAILED
> * `read_by` - Who read the message and when (JSON)
> * `error`, `error_code`, `error_category` - Why a FAILED message failed
> * `edited_id`, `replied_id`, `forwarded_id` - Message this one edits, replies to or forwards
> * `deleted_at` - When the message was deleted
> * `archived_at` - When the message was archived
> * `created_at` - When the message was created
> * `updated_at` - When the message was last updated (replication key)

> [accordion] Calls
>
> * `id` - Unique identifier of the call
> * `contact_id` - Contact the call was listed under (the calls of a contact include those of its deals)
> * `project_id` - Leadstaker project
> * `entity_type`, `entity_id` - The deal the call is attached to, or the contact when it has no deal
> * `provider` - Telephony provider, or API for calls posted through the API
> * `external_id` - Call identifier on the telephony provider
> * `direction` - OUTBOUND or INBOUND
> * `call_from_type`, `call_from_number`, `call_from_user_id` - Caller side (extension or phone)
> * `call_to_type`, `call_to_number`, `call_to_user_id` - Called side (extension or phone)
> * `started_at`, `answered_at`, `ended_at` - When the call started, was answered and ended
> * `duration_in_seconds` - Talk time in seconds
> * `outcome` - ANSWERED, NO\_ANSWER, BUSY, VOICEMAIL or FAILED
> * `recording_status`, `recording_mime_type` - Recording status and media type
> * `transcription_status` - AVAILABLE, TOO\_LONG, PENDING, DONE or FAILED
> * `transcription_text` - Whole transcript, when the call was not split by speaker
> * `transcription` - Full transcript, including the turns by speaker (JSON)
> * `analysis_status`, `analysis_summary` - AI summary of the call
> * `created_at` - When the call was stored
> * `updated_at` - When the call was last updated, for example by its transcription (replication key)

> [accordion] Touchpoints
>
> * `id` - Unique identifier of the touchpoint
> * `contact_id`, `deal_id`, `chat_id`, `message_id` - Records it belongs to
> * `occurred_at` - When the lead reached the business
> * `entry` - How the lead came in: FORM, MESSAGE, CALL, MANUAL, IMPORT or UNKNOWN
> * `traffic` - Kind of traffic (PAID\_SEARCH, PAID\_SOCIAL, ORGANIC\_SEARCH, REFERRAL, DIRECT…)
> * `source` - Normalized source (google, instagram, whatsapp, direct…)
> * `platform` - Ad platform on paid traffic (META, GOOGLE, TIKTOK…)
> * `campaign_id`, `campaign_name`, `adset_id`, `adset_name`, `ad_id`, `ad_name` - Ad that brought the lead
> * `via_type`, `via_id`, `via_name`, `via_provider`, `via_phone_number` - Where in Leadstaker it came in
> * `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `utm_id` - UTMs from the URL
> * `click_ids` - Ad click ids such as gclid, fbclid, ctwaclid (JSON)
> * `url` - Page the lead came from
> * `record_type`, `record_id` - Record the touchpoint was read from
> * `editable_origin`, `manual_origin` - Whether a person may pick the origin, and the origin picked
> * `is_first_touch`, `is_last_touch` - Whether it is the deal's first or latest touch

> [accordion] Leads
>
> * `id` - Unique identifier of the lead
> * `project_id` - Leadstaker project
> * `source_id` - Chatbot that captured the lead
> * `session_id` - Chatbot session of the visitor
> * `is_complete` - Whether the visitor finished the chatbot flow
> * `answers` - Answers given in the chatbot (JSON)
> * `origin_url` - URL of the page the visitor came from
> * `url_params` - Query parameters of that URL, such as UTMs and click ids (JSON)
> * `created_at` - When the lead was created
> * `updated_at` - When the lead was last updated (replication key)

> [accordion] Tasks
>
> * `id` - Unique identifier of the task
> * `project_id` - Leadstaker project
> * `deal_id` - Deal the task belongs to
> * `title` - Title of the task
> * `due_at` - When the task is due
> * `responsible_id` - User the task is assigned to
> * `result` - Result written when the task was completed
> * `completed_at`, `completed_by` - When and by whom the task was completed
> * `created_by` - User who created the task
> * `created_by_automation` - Automation run that created the task (JSON)
> * `created_at` - When the task was created
> * `updated_at` - When the task was last updated (replication key)

> [accordion] Notes
>
> * `id` - Unique identifier of the note
> * `project_id` - Leadstaker project
> * `entity_type`, `entity_id` - Contact or deal the note is attached to
> * `content` - Text of the note
> * `author_type`, `author_id`, `author_name` - Who wrote the note (USER, AGENT or SYSTEM)
> * `author` - Full author (JSON)
> * `edited_at`, `edited_by` - When and by whom the note was last edited
> * `archived_at` - When the note was archived
> * `created_at` - When the note was created
> * `updated_at` - When the note was last updated (replication key)

> [accordion] Pipelines and Pipeline Stages
>
> **Pipelines:**
>
> * `id`, `project_id`, `name` - Pipeline identifier, project and name
> * `sort` - Order of the deals on the board
> * `appearance_config` - Board card appearance settings (JSON)
> * `stages` - Stages as returned with the pipeline (JSON)
> * `archived_at`, `created_at`, `updated_at`
>
> **Pipeline Stages:**
>
> * `id`, `pipeline_id`, `name` - Stage identifier, pipeline and name
> * `position` - Position of the stage in the pipeline
> * `type` - OPEN for working stages, CLOSED for the won/lost stages
> * `color` - Display color
> * `archived_at`, `created_at`, `updated_at`

> [accordion] Tags and Loss Reasons
>
> * `id`, `project_id`, `name` - Identifier, project and name
> * `color` - Display color (tags only)
> * `archived_at`, `created_at`, `updated_at`

> [accordion] Fields and Field Groups
>
> **Fields:**
>
> * `id` - Field identifier (the `fieldId` in the `fields` column of contacts and deals)
> * `label` - Label of the field
> * `type` - TEXT, NUMBER, DATE, DATETIME, BOOLEAN, OPTIONS, MULTISELECT, PHONE, EMAIL, CPF, CNPJ, CPF\_CNPJ, CEP, CURRENCY, TIME or LINK
> * `entity_type` - Whether the field belongs to deals or contacts
> * `field_group_id` - Group of the field
> * `position`, `level`, `code` - Position, visibility (USER or API) and built-in code (NAME, PHONE, EMAIL, PRICE…)
> * `config` - Type-specific settings, such as the options of an OPTIONS field (JSON)
> * `project_id`, `archived_at`, `created_at`, `updated_at`
>
> **Field Groups:**
>
> * `id`, `project_id`, `name` - Identifier, project and name
> * `entity_type` - Whether the group holds deal or contact fields
> * `position`, `code` - Position and built-in code
> * `archived_at`, `created_at`, `updated_at`

## Limitations

* **Deleted records**: Leadstaker does not report deletions, so a record deleted in Leadstaker (including touchpoints) stays in incremental tables until the next full sync.
* **Touchpoints**: Leadstaker returns at most the latest 100 touchpoints of each contact. When a contact has more, the sync warns you and the older ones are not in the table.
* **Delay for quiet chats and contacts**: a new message or call that does not update its chat or contact in Leadstaker appears at the next full walk, at most **Full walk interval** hours later.
* **One project per source**: each API key reads a single Leadstaker project.


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