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

# Falaê as a data source

> Bring survey answers (NPS), coupons, loyalty-program awards and review-site summaries from Falaê to Nekt.

Falaê is a customer-experience platform for restaurants and retail: it collects NPS survey answers from customers, issues coupons and loyalty-program rewards, and tracks reviews on Google, iFood and TripAdvisor. The Nekt connector extracts that data into your Catalog, so you can analyze customer satisfaction together with your sales and operations data.

## Before you start

You need the **API token** (a JWT) of your Falaê account. Falaê provides it on request: ask the Falaê team for an integration token. The token decides which companies (units) the connector can see. If Falaê revokes or replaces it, update it in the source configuration.

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

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

### 1. Add account access

The following configurations are available:

* **API Token**: The integration token provided by the Falaê team. Paste only the token, without quotes and without the word `Bearer`.
* **Start Date**: The earliest day to extract answers, coupons, awards and daily reports from. A long period makes the first extraction slower, because the daily reports are requested one day at a time.

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.

> 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 and changed 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.

We recommend INCREMENTAL for answers, coupons, awards and the daily reports: each extraction reads only the last few days again, while FULL\_TABLE reads everything since the start date on every run.

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. Answers arrive throughout the day, so a few runs per day keep them fresh; once a day is enough for the daily reports.

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. A monthly full sync is enough to pick up coupons that changed long after they were created.

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 |
| - | - | - |
| Companies | `companies` | The companies (units or stores) your token can access. |
| Searches (surveys) | `searches` | The surveys configured for those companies. |
| Answers | `answers` | One row per survey answer: NPS score, comment, rated criteria, company, survey and client. |
| Coupons | `coupons` | One row per coupon: code, reward, use and expiration dates, company and client. |
| Awarded entries | `awardeds` | One row per winning registration in a loyalty-program draw or roulette. |
| Consolidated report (daily) | `consolidated_report_daily` | Per company and day: answers, promoters, neutrals, detractors, NPS, coupons created and used, and NPS by criterion. |
| Google reviews (daily) | `google_reviews_daily` | Per company and day: number of Google reviews, average rating, stars and replies. |
| iFood reviews (daily) | `ifood_reviews_daily` | Same summary for iFood reviews. |
| TripAdvisor reviews (daily) | `tripadvisor_reviews_daily` | Same summary for TripAdvisor reviews. |

The rated criteria of an answer and the NPS by criterion of the consolidated report are stored as JSON text, for example `json_extract_scalar(criteria, '$[0].nick')`.

## Fields by stream

> [accordion] Companies
>
> Stream name: `companies`.
>
> **Sync Strategy:**
>
> * Full table
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier (UUID) of the company |
> | `name` | String | Name of the company (unit or store) |

> [accordion] Searches (surveys)
>
> Stream name: `searches`.
>
> **Sync Strategy:**
>
> * Full table
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier (UUID) of the search (survey) |
> | `name` | String | Name of the search (survey) |
> | `company_id` | String | Identifier of the company the search belongs to |

> [accordion] Answers
>
> Stream name: `answers`.
>
> **Sync Strategy:**
>
> * Incremental on `created_at` (re-reads the last 2 days)
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier (UUID) of the answer |
> | `created_at` | Timestamp | When the answer was created, used as the incremental replication key |
> | `is_enps` | Boolean | True for employee eNPS answers, false for customer NPS answers; null when the API returned the answer for both (the account does not separate them) |
> | `nps` | Number | NPS score (0 to 10) given in the answer |
> | `discursive_question` | String | Free-text comment written in the answer's open (discursive) question, if any |
> | `company_id` | String | Identifier of the company the answer is about |
> | `company_name` | String | Name of the company the answer is about |
> | `search_id` | String | Identifier of the search (survey) answered |
> | `search_name` | String | Name of the search (survey) answered |
> | `page_id` | String | Identifier of the survey page (channel) of the answer |
> | `page_name` | String | Name of the survey page (channel) of the answer |
> | `consumption_id` | String | Identifier of the consumption (purchase) linked to the answer |
> | `consumption_order_id` | String | Order identifier of the linked consumption in the point of sale |
> | `client_id` | String | Identifier of the client (customer) who gave the answer |
> | `client_name` | String | Name of the client who gave the answer |
> | `client_email` | String | Email of the client who gave the answer |
> | `client_phone` | String | Phone number of the client who gave the answer |
> | `client_cpf` | String | CPF (Brazilian tax id) of the client who gave the answer |
> | `client_born_date` | Date | Birth date of the client who gave the answer (normalized to YYYY-MM-DD) |
> | `criteria` | String | Criteria rated in the answer, as a JSON array of objects with nick (criterion label), name (the answer value), suggestion and type (NPS, Rating, Emoticon...) |

> [accordion] Coupons
>
> Stream name: `coupons`.
>
> **Sync Strategy:**
>
> * Incremental on `created_at` (re-reads the last 2 days) plus every coupon used since the previous run
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier (UUID) of the coupon |
> | `code` | String | Coupon code |
> | `name` | String | Name of the reward (bonus) the coupon grants |
> | `status` | Boolean | Whether the coupon is still available (false once it is used) |
> | `date_of_use` | Date | Day the coupon was used; null while unused |
> | `expiration_date` | Date | Day the coupon expires |
> | `created_at` | Timestamp | When the coupon was created, used as the incremental replication key |
> | `company_id` | String | Identifier of the company that issued the coupon |
> | `company_name` | String | Name of the company that issued the coupon |
> | `client_id` | String | Identifier of the client who owns the coupon |
> | `client_name` | String | Name of the client who owns the coupon |
> | `client_email` | String | Email of the client who owns the coupon |
> | `client_phone` | String | Phone number of the client who owns the coupon |
> | `client_cpf` | String | CPF (Brazilian tax id) of the client who owns the coupon |
> | `client_born_date` | Date | Birth date of the client who owns the coupon (normalized to YYYY-MM-DD) |

> [accordion] Awarded entries
>
> Stream name: `awardeds`.
>
> **Sync Strategy:**
>
> * Incremental on `created_at` (re-reads the last 2 days)
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier (UUID) of the winning registration |
> | `created_at` | Timestamp | When the winning registration was created, used as the incremental replication key |
> | `awarded_id` | String | Identifier of the award (prize) won |
> | `awarded_name` | String | Name of the award (prize) won |
> | `client_id` | String | Identifier of the client (customer) who won the award |
> | `client_name` | String | Name of the client who won the award |
> | `client_email` | String | Email of the client who won the award |
> | `client_phone` | String | Phone number of the client who won the award |
> | `client_cpf` | String | CPF (Brazilian tax id) of the client who won the award |
> | `client_born_date` | Date | Birth date of the client who won the award (normalized to YYYY-MM-DD) |
> | `company_id` | String | Identifier of the company of the winning registration |
> | `company_name` | String | Name of the company of the winning registration |

> [accordion] Consolidated report (daily)
>
> Stream name: `consolidated_report_daily`.
>
> **Sync Strategy:**
>
> * Incremental on `date` (re-reads the last 7 days)
> * Primary key(s): `date`, `company`, `uf`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `date` | Date | Day the figures refer to, used as the incremental replication key |
> | `company` | String | Name of the company the figures refer to (the export has no company id) |
> | `uf` | String | State (UF) of the company; empty string when Falaê has none |
> | `total` | Integer | Number of answers Falaê counts for the day in this report (computed by Falaê; it can differ from the rows of the answers table) |
> | `clients` | Integer | Number of the day's answers that identified the client |
> | `promoter` | Integer | Number of promoter answers (NPS 9-10) |
> | `neutral` | Integer | Number of neutral answers (NPS 7-8) |
> | `detractor` | Integer | Number of detractor answers (NPS 0-6) |
> | `nps` | Number | NPS of the day (percent promoters minus percent detractors) |
> | `coupons_created` | Integer | Coupons-created figure Falaê reports for the company; it is not limited to the day (seen as a running total), so do not sum it across days |
> | `coupons_used` | Integer | Number of coupons used on the day |
> | `criteria` | String | NPS of each rated criterion on the day, as a JSON array of objects with name and nps |

> [accordion] Google reviews (daily)
>
> Stream name: `google_reviews_daily`.
>
> **Sync Strategy:**
>
> * Incremental on `date` (re-reads the last 30 days)
> * Primary key(s): `date`, `company_id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `date` | Date | Day the figures refer to, used as the incremental replication key |
> | `company_id` | String | Identifier of the company the reviews are about |
> | `company_name` | String | Name of the company the reviews are about |
> | `rating` | Number | Average rating (1 to 5) of the reviews received on the day |
> | `published_rating` | Number | Rating published by the review site for the company (overall, not only the day) |
> | `total` | Integer | Number of reviews received on the day |
> | `total_answers` | Integer | Total number of reviews the review site reports for the company |
> | `answered` | Integer | Number of the day's reviews that were replied to |
> | `five_stars` | Integer | Number of 5-star reviews on the day |
> | `four_stars` | Integer | Number of 4-star reviews on the day |
> | `three_stars` | Integer | Number of 3-star reviews on the day |
> | `two_stars` | Integer | Number of 2-star reviews on the day |
> | `one_star` | Integer | Number of 1-star reviews on the day |

> [accordion] iFood reviews (daily)
>
> Stream name: `ifood_reviews_daily`.
>
> **Sync Strategy:**
>
> * Incremental on `date` (re-reads the last 30 days)
> * Primary key(s): `date`, `company_id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `date` | Date | Day the figures refer to, used as the incremental replication key |
> | `company_id` | String | Identifier of the company the reviews are about |
> | `company_name` | String | Name of the company the reviews are about |
> | `rating` | Number | Average rating (1 to 5) of the reviews received on the day |
> | `published_rating` | Number | Rating published by the review site for the company (overall, not only the day) |
> | `total` | Integer | Number of reviews received on the day |
> | `total_answers` | Integer | Total number of reviews the review site reports for the company |
> | `answered` | Integer | Number of the day's reviews that were replied to |
> | `five_stars` | Integer | Number of 5-star reviews on the day |
> | `four_stars` | Integer | Number of 4-star reviews on the day |
> | `three_stars` | Integer | Number of 3-star reviews on the day |
> | `two_stars` | Integer | Number of 2-star reviews on the day |
> | `one_star` | Integer | Number of 1-star reviews on the day |

> [accordion] TripAdvisor reviews (daily)
>
> Stream name: `tripadvisor_reviews_daily`.
>
> **Sync Strategy:**
>
> * Incremental on `date` (re-reads the last 30 days)
> * Primary key(s): `date`, `company_id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `date` | Date | Day the figures refer to, used as the incremental replication key |
> | `company_id` | String | Identifier of the company the reviews are about |
> | `company_name` | String | Name of the company the reviews are about |
> | `rating` | Number | Average rating (1 to 5) of the reviews received on the day |
> | `published_rating` | Number | Rating published by the review site for the company (overall, not only the day) |
> | `total` | Integer | Number of reviews received on the day |
> | `total_answers` | Integer | Total number of reviews the review site reports for the company |
> | `answered` | Integer | Number of the day's reviews that were replied to |
> | `five_stars` | Integer | Number of 5-star reviews on the day |
> | `four_stars` | Integer | Number of 4-star reviews on the day |
> | `three_stars` | Integer | Number of 3-star reviews on the day |
> | `two_stars` | Integer | Number of 2-star reviews on the day |
> | `one_star` | Integer | Number of 1-star reviews on the day |

## Implementation Notes

### Data Quality Considerations

* **Answers** are read by the day they were created. Each extraction reads the last 2 days again, so late answers are not missed. The answer's workflow status and closed-loop notes are not available in Falaê's API and are not extracted.
* **NPS and eNPS**: Falaê asks for the answer type on every request, but for some accounts it returns the same answers for both types. The `is_enps` column is filled only when Falaê tells them apart, and is empty otherwise.
* **Coupons** change after they are created, when they are used. Each incremental extraction also reads every coupon used since the previous extraction, so `date_of_use` and `status` stay up to date. A coupon that only expires is not read again; use `expiration_date` to tell expired coupons.
* **Daily reports** are aggregates per company and day. The consolidated report is read again for the last 7 days, and the review summaries for the last 30 days (replies to reviews keep arriving), so recent days are refreshed. Today's row is partial until the next extraction.
* The consolidated report has no company id: each row is identified by the day, the company name and its state (`uf`, empty when Falaê has none). If two units have the same name and state, only one of them is kept for that day and the run log warns about it; give them different names in Falaê to keep both. If a company is renamed, recent days (up to 7 days back) get a row under the new name next to the old one.
* The consolidated report's figures are calculated by Falaê and do not always match the other tables: `total` can differ from the number of rows in the answers table, and `coupons_created` is not limited to the day, so do not add it up across days. Days older than 7 days are not read again; run a full sync if you need them recalculated.
* Client, company and survey names on answers, coupons and awards are the values at the time the record was read. Changes made in Falaê more than 2 days after the record was created only show up after a full sync.
* `published_rating` and `total_answers` in the review summaries describe the company on the review site overall, not the day.
* Client fields (name, e-mail, phone, CPF, birth date) are filled only when the client identified themselves. Birth dates are normalized to `YYYY-MM-DD`.

### API Limits & Performance

* Lists are read 50 records per request (Falaê's maximum), with a short pause between requests. When Falaê asks the connector to slow down or is temporarily unavailable, it waits and retries automatically.
* Each period is saved only after all of its pages were read and they add up with the total reported by Falaê. New answers and coupons that arrive while a period is being read do not disturb it (they are picked up by the next extraction). If records are deleted while a period is being read, that period is read again (up to three times), so no record is duplicated or missed.
* The daily reports make one request per day and per report. A start date far in the past makes the first extraction take longer; later extractions only read the last days.

## Troubleshooting

| Error or symptom | What it means | What to do |
| :- | :- | :- |
| "Falaê rejected the API token" | The token is missing, wrong, revoked or was replaced. | Ask the Falaê team for a valid token and update it in the source configuration. |
| "The Falaê API asked us to slow down or is temporarily unavailable" | Falaê answered with a rate limit or a temporary error. | Nothing to do; the extraction retries on its own. If it fails, run it again later. |
| "did not deliver a complete, consistent list" | The pages returned by Falaê did not add up three times in a row. That table was not fully updated. | Run the extraction again later. If it keeps happening, contact support. |
| "Falaê returned an empty list for this token although the previous run had rows" | The companies or surveys list came back empty. The table was kept as it was. | Check with Falaê that the token still has access to your companies. |
| "two companies that cannot be told apart" | The consolidated report has two units with the same name and state on the same day; only one is kept. | Give the units different names in Falaê. |
| A review table is empty | The company has no reviews on that site, or the site is not connected in Falaê. | Nothing to do, or connect the site in Falaê. |


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