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

# Tagme as a data source

> Bring restaurant reservations, waitlist entries and venues from Tagme to Nekt.

Tagme is a restaurant platform for reservations, waitlists, digital menus and customer relationship. Its Partners API includes a **Reports API** that gives read access to the reservations and waitlist entries of your venues. The Nekt connector extracts that data into your Catalog, so you can analyze bookings, no-shows, waitlist demand and party sizes together with the rest of your data.

## Before you start

You need a **username and password for the Tagme Partners API** with access to the Reports API. Ask Tagme support for them; they are not the same as your Tagme panel login.

Tagme updates the report data once a day: the data available today goes **up to yesterday**. A reservation or waitlist entry made today appears in Nekt after the next day's extraction.

## Configuring Tagme 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 Tagme 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:

* **Username**: The username of your Tagme Partners API user.
* **Password**: The password of your Tagme Partners API user.
* **Start Date**: Reservations and waitlist entries **created** from this date on are synced.
* **Strict completeness check** (advanced, default off): when on, the extraction fails if a day still has fewer records than Tagme's own report summary counts. When off, the records received are kept and those days are reported as a warning. Check the logs of the first extractions; once they show no such warning, turn it on.

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 **Reservations** and **Waitlists**: a full table extraction reads everything again from 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. Since Tagme updates the report data once a day, one extraction per day (in the morning) is enough.

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. It is usually not needed for this connector (see [Implementation Notes](#implementation-notes)).

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 |
| - | - | - |
| Reservations | `reservations` | One row per reservation: venue, visit day and time, party size, status, origin, section and customer. |
| Waitlists | `waitlists` | One row per waitlist entry: venue, day, party size, status, origin and customer. |
| Venues | `venues` | Active venues visible to your user: name, contact, address, coordinates, opening hours and cuisines. Not selected by default (see the warning below). |

Nested objects (customer, address, phones, opening hours, names in several languages) are stored as JSON text, for example `json_extract_scalar(customer, '$.email')`. The most used customer and address fields are also available as their own columns.

> [!WARNING]
>
> Tagme's venues list has no filter by company, so it may include restaurants of other Tagme customers. The **Venues** stream is therefore not selected by default. If you select it, check on the first extraction that only your venues came back; if not, unselect it and use the `venue_id` of the other tables.

## Fields by stream

> [accordion] Reservations
>
> Stream name: `reservations`. One row per reservation.
>
> **Sync Strategy:**
>
> * Incremental on `created_at` (see [how changes are captured](#how-changes-are-captured))
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the reservation in Tagme (primary key). |
> | `venue_id` | String | Identifier of the venue; joins with `venues.id`. |
> | `status` | String | Reservation status: New, Confirmed, Canceled or Seated. |
> | `origin` | String | Channel the reservation came from (e.g. Reservation Widget, Phone, partner apps). |
> | `party_size` | Integer | Number of people. |
> | `note` | String | Note entered for the reservation. |
> | `created_at` | Datetime | When the reservation was created (UTC). |
> | `created_at_raw` | String | Creation date exactly as returned by Tagme. |
> | `reservation_date` | Date | Day of the visit. |
> | `reservation_day_raw` | String | Visit day exactly as returned by Tagme. |
> | `reservation_time` | String | Time of the visit (HH:MM). |
> | `section` | String | Area of the venue the reservation is for. |
> | `customer_name` | String | First name of the customer. |
> | `customer_last_name` | String | Last name of the customer. |
> | `customer_email` | String | E-mail of the customer. |
> | `customer_phone` | String | Phone number of the customer. |
> | `customer` | String | Full customer object (JSON). |
> | `additional_fields` | String | Fields returned by Tagme that are not documented yet (JSON). |

> [accordion] Waitlists
>
> Stream name: `waitlists`. One row per waitlist entry.
>
> **Sync Strategy:**
>
> * Incremental on `created_at`
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the waitlist entry in Tagme (primary key). |
> | `venue_id` | String | Identifier of the venue; joins with `venues.id`. |
> | `status` | String | Waitlist status: Arrived, Notified, Canceled or Seated. |
> | `origin` | String | Channel the entry came from (e.g. Widget, Restaurant). |
> | `party_size` | Integer | Number of people. |
> | `note` | String | Note entered for the entry. |
> | `created_at` | Datetime | When the entry was created (UTC). |
> | `created_at_raw` | String | Creation date exactly as returned by Tagme, when present. |
> | `waitlist_date` | Date | Day of the waitlist entry. |
> | `waitlist_day_raw` | String | Day exactly as returned by Tagme. |
> | `customer_name` | String | First name of the customer. |
> | `customer_last_name` | String | Last name of the customer. |
> | `customer_email` | String | E-mail of the customer. |
> | `customer_phone` | String | Phone number of the customer. |
> | `customer` | String | Full customer object (JSON). |
> | `additional_fields` | String | Fields returned by Tagme that are not documented yet (JSON). |

> [accordion] Venues
>
> Stream name: `venues`. One row per active venue visible to your user. Not selected by default.
>
> **Sync Strategy:**
>
> * Full table
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the venue (primary key); joins with `venue_id` in the other tables. |
> | `name` | String | Venue name (Portuguese, or the first language available). |
> | `name_translations` | String | Venue name in every language (JSON). |
> | `short_name` | String | Short name of the venue. |
> | `short_name_translations` | String | Short name in every language (JSON). |
> | `description` | String | Description of the venue in every language (JSON). |
> | `email` | String | Contact e-mail. |
> | `site` | String | Website. |
> | `phones` | String | Phone numbers (JSON list of name and value). |
> | `operation_hours` | String | Opening hours per weekday (JSON list of day, start and end). |
> | `address` | String | Full address (JSON). |
> | `address_street` | String | Street. |
> | `address_complement` | String | Address complement. |
> | `address_number` | String | Street number. |
> | `address_neighborhood` | String | Neighborhood. |
> | `address_city` | String | City. |
> | `address_state` | String | State. |
> | `address_zip` | String | Postal code. |
> | `address_country` | String | Country. |
> | `longitude` | Number | Longitude. |
> | `latitude` | Number | Latitude. |
> | `theme` | String | Images of the venue's theme (JSON). |
> | `cuisines` | String | Cuisine types (JSON). |
> | `additional_fields` | String | Fields returned by Tagme that are not documented yet (JSON). |

## Implementation Notes

### How changes are captured

Tagme's Reports API lists reservations and waitlist entries by their **creation date**; it has no filter for "changed since". The connector handles this as follows:

* Every incremental extraction reads again the **last 7 days** of created records, so the one-day delay of Tagme's reports, a late daily update or a few failed runs never leave gaps.
* A reservation keeps changing until the visit happens (it is confirmed, canceled or marked as seated), which can be weeks after it was created. The connector remembers the oldest reservation whose visit day has not passed yet and reads again from its creation date, so the status of every reservation is updated until 3 days after its visit day. Reservations created more than a year ago are not followed anymore.
* Waitlist entries are created and closed on the same day, so the 7-day window is enough for them.
* If the first extraction finds no records at all (for example, your venues are not linked to the Partners API user yet), the next extraction reads again from the Start Date, so no history is skipped once Tagme links them.

### Data Quality Considerations

* Data is available up to yesterday. Today's reservations and waitlist entries appear after the next day's extraction.
* Dates are converted to standard format (`YYYY-MM-DD` and UTC timestamps); the original values are kept in the `*_raw` columns.
* Records deleted in Tagme are not reported by its API. If you need them removed from your tables, run a full sync; keep in mind that it reads everything again from the Start Date.
* The connector was built from Tagme's API documentation. Fields that Tagme returns but does not document are kept in `additional_fields` instead of being dropped.

### API Limits & Performance

* Tagme returns each period in a single response. To make sure nothing was cut, the connector compares every period with Tagme's own report summary (the number of records Tagme counts for that period); a period that comes back short is read again in smaller pieces. If a single day is still short, its records are kept and the extraction log shows one warning naming the days (or the extraction fails, with **Strict completeness check** on). If Tagme's summary is not available for your user, the log says so once and the data is still synced.
* Each request covers 14 days of created records (Tagme accepts up to 31), plus the last day of the previous period. When Tagme cannot answer a period in time, the connector splits it into smaller periods, down to one day. The first extraction reads from the Start Date in 14-day steps. Daily extractions of waitlists need one or two requests; reservations also read back to the oldest reservation whose visit has not happened yet (one request per 14 days).
* Tagme does not document a rate limit. The connector waits between requests and, when Tagme asks it to slow down or is temporarily unavailable, waits and retries automatically.
* If an extraction fails, the next one reads the same period again, so nothing is skipped.

## Troubleshooting

| Error or symptom | What it means | What to do |
| :- | :- | :- |
| "Tagme rejected the username or password of this source" | The Partners API login was refused. | Check the username and password with Tagme and update them in the source configuration. |
| "The Tagme user of this source is disabled" | Tagme disabled the Partners API user. | Ask Tagme to enable it, or provide another user. |
| "Tagme denied this user access to this data" | The user has no permission for that report. The other tables continue. | Ask Tagme to grant the permission, or unselect the stream. |
| "Tagme returned no records created since the Start Date" | The user sees no reservations or waitlist entries yet. | Check with Tagme that your venues are linked to the Partners API user; the next extraction reads again from the Start Date. |
| "Tagme returned N active venues for this user" | The venues list is long and may include restaurants that are not yours. | Check the Venues table; if it has other companies' venues, unselect the stream. |
| "For some days Tagme returned fewer records than its own report summary counts" (warning) | Those days came back short even one day at a time. The records received were saved. | If it repeats, contact support. With **Strict completeness check** on, this fails the extraction instead. |
| "Tagme's report summary is not available for this user" (warning) | The completeness check is off for this extraction; data is still synced. | Ask Tagme to enable the reports summary for the Partners API user. |
| "kept failing ... even one day at a time" | Tagme could not deliver a period. Records of earlier periods may already be saved. | Run the extraction again later; the same period is read again. Contact support if it repeats. |
| "Tagme returned no active venues for this user" | The venues list came back empty, so the table was kept as it was. | Check with Tagme which venues the user can access, or unselect the Venues stream. |
| "The Tagme API asked us to slow down or is temporarily unavailable" | Tagme answered with a rate limit or an error. | Nothing to do; the extraction retries on its own. |
| Today's reservations are missing | Tagme's reports are updated once a day (data up to yesterday). | They appear after the next day's extraction. |


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