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

# Humanitix as a data source

> Bring ticketing and event data from Humanitix to Nekt.

Humanitix is a ticketing platform for events. This connector extracts events, orders, tickets, and organizers' tags from the Humanitix API into Nekt for analysis.

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

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

### 1. Add account access

You'll need your Humanitix API key. Add your credentials:

* **API Key**: Humanitix API key. Found under `Account > Advanced > Public API key`.
* **Start Date**: The earliest record date to sync (ISO 8601 format). Records created or updated after this date will be extracted from the source.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync:

* `events`
* `orders`
* `tickets`
* `tags`

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, and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables once the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this 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 to make this process faster!
* **Sync Type**: you can choose between `INCREMENTAL` and `FULL_TABLE`.
  * Incremental: every run fetches only new/updated records since the last replicated timestamp (supported for `events`, `orders`, and `tickets` via `updatedAt`).
  * Full table: every run fetches the current state of the stream. Use this for `tags` (replication is not incremental).

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.

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.

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>

# Streams and Fields

Below you'll find all available data streams from Humanitix and their corresponding fields.

<AccordionGroup>
  <Accordion title="Events">
    Master data about events and their attributes.

    **Key Fields:**

    * `_id`: Unique event identifier (primary key)
    * `userId`, `organiserId`
    * `currency`
    * `name`, `description`, `sharingDescription`, `slug`, `url`
    * `tagIds`
    * `category`
    * `classification.category`, `classification.subcategory`
    * `artists[]`: `origin`, `name`, `externalId`, `spotifyId`
    * `public`, `published`, `suspendSales`, `markedAsSoldOut`
    * `startDate`, `endDate`, `timezone`, `totalCapacity`
    * `ticketTypes[]`:
      * `_id`, `name`, `price`, `quantity`
      * `priceRange.enabled`, `priceRange.min`, `priceRange.max`
      * `priceOptions.enabled`, `priceOptions.options[]` (`value`)
      * `description`, `disabled`, `deleted`, `isDonation`
      * `tickets[]`: `ticketTypeId`, `quantity`
    * `pricing.minimumPrice`, `pricing.maximumPrice`
    * `paymentOptions.refundSettings.refundPolicy`, `paymentOptions.refundSettings.customRefundPolicy`
    * `publishedAt`
    * `additionalQuestions[]`: `_id`, `inputType`, `question`, `required`, `description`, `perOrder`, `disabled`, `createdAt`, `updatedAt`
    * `bannerImage.url`, `featureImage.url`, `socialImage.url`
    * `eventLocation`: `type`, `venueName`, `address`, `latLng[]`, `instructions`, `placeId`, `onlineUrl`, `mapUrl`, `city`, `region`, `country`
    * `dates[]`: `_id`, `startDate`, `endDate`, `scheduleId`, `disabled`, `deleted`
    * `packagedTickets[]`: `_id`, `name`, `price`, `quantity`, `description`, `disabled`, `deleted`
    * `packagedTickets[].tickets[]`: `ticketTypeId`, `quantity`
    * `accessibility`:
      * `contactName`, `contactNumber`, `travelInstructions`, `entryInstructions`, `afterEntryInstructions`
      * `hazards`, `toiletLocation`, `disabledParking`
      * `features.access`, `features.wheelchairAccessibility`, `features.audioDescription`, `features.telephoneTypewriter`, `features.volumeControlTelephone`, `features.assistiveListeningSystems`, `features.signLanguageInterpretation`, `features.accessiblePrint`, `features.closedCaptioning`, `features.openedCaptioning`, `features.brailleSymbol`
    * `affiliateCode.code`
    * `keywords[]`
    * `location`
    * `createdAt`, `updatedAt` (replication)
  </Accordion>

  <Accordion title="Orders">
    Orders placed by users for event ticket purchases.

    **Key Fields:**

    * `_id`: Unique order identifier (primary key)
    * `eventId`: References `events._id`
    * `userId`, `currency`, `eventDateId`
    * `status`, `financialStatus`
    * `firstName`, `lastName`, `organisation`
    * `mobile`, `email`, `accessCode`
    * `discounts.autoDiscount.discountAmount`
    * `discounts.discountCode.code`, `discounts.discountCode.discountAmount`
    * `businessPurpose`, `businessTaxId`, `businessName`
    * `paymentType`, `paymentGateway`, `manualOrder`, `tipFees`
    * `clientDonation`, `notes`, `organiserMailListOptIn`
    * `incompleteAt`, `completedAt`, `waitlistOfferId`
    * `isInternationalTransaction`
    * `totals`: `subtotal`, `amexFee`, `zipFee`, `humanitixFee`, `bookingFee`, `passedOnFee`, `clientDonation`, `netClientDonation`, `donation`, `dgrDonation`, `giftCardCredit`, `credit`, `outstandingAmount`, `feesIncluded`, `bookingTaxes`, `passedOnTaxes`, `taxes`, `totalTaxes`, `discounts`, `refunds`, `netSales`, `grossSales`, `referralAmount`, `total`
    * `purchaseTotals`: same shape as `totals`
    * `additionalFields[]`: `questionId`, `value`, `details.street`, `details.suburb`, `details.postalCode`, `details.city`, `details.state`, `details.country`
    * `salesChannel`, `location`
    * `createdAt`, `updatedAt` (replication)
  </Accordion>

  <Accordion title="Tickets">
    Individual tickets issued for event purchases.

    **Key Fields:**

    * `_id`: Unique ticket identifier (primary key)
    * `eventId`: References `events._id`
    * `orderId`: References `orders._id`
    * `eventDateId`, `userId`, `currency`
    * `status`
    * `firstName`, `lastName`, `email`, `mobile`, `organisation`
    * `ticketTypeName`, `ticketTypeId`
    * `price`
    * `accessCode`
    * `checkedIn`, `checkedInAt`, `checkedInBy`
    * `checkedOut`, `checkedOutAt`
    * `refunded`, `refundedAt`
    * `cancelled`, `cancelledAt`
    * `transferred`, `transferredAt`
    * `qrCode`
    * `seatLabel`, `tableLabel`
    * `additionalFields[]`: `questionId`, `value`, `details.street`, `details.suburb`, `details.postalCode`, `details.city`, `details.state`, `details.country`
    * `salesChannel`, `location`
    * `createdAt`, `updatedAt` (replication)
  </Accordion>

  <Accordion title="Tags">
    Tags from Humanitix used to categorize organizers/events.

    **Key Fields:**

    * `_id`: Unique tag identifier (primary key)
    * `name`
    * `colour`
    * `userId`, `organiserId`
    * `createdAt`, `updatedAt`
  </Accordion>
</AccordionGroup>

# Data Model

The following diagram illustrates the relationships between Humanitix entities. The arrows indicate the join keys that link the streams.

```mermaid theme={null}
graph TD;
  Events("Events");
  Orders("Orders");
  Tickets("Tickets");

  Events -- "events._id = orders.eventId" --> Orders;
  Events -- "events._id = tickets.eventId" --> Tickets;
  Orders -- "orders._id = tickets.orderId" --> Tickets;
```

# Use Cases for Data Analysis

This guide outlines common analysis patterns using Humanitix data.

### 1. Ticket sales by event (last 30 days)

Track how many tickets were sold per event and the total ticket price (using the `tickets` stream).

<Accordion title="SQL query">
  <Tabs>
    <Tab title="AWS">
      ```sql theme={null}
      -- Replace `nekt_raw.humanitix_events` / `nekt_raw.humanitix_tickets`
      -- with your configured layer + table names.
      SELECT
        e.name AS event_name,
        COUNT(*) AS tickets_sold,
        SUM(t.price) AS total_ticket_price
      FROM
        nekt_raw.humanitix_tickets t
      JOIN
        nekt_raw.humanitix_events e
      ON e._id = t.eventId
      WHERE
        CAST(t.updatedAt AS TIMESTAMP) >= current_timestamp - INTERVAL '30' DAY
      GROUP BY
        1
      ORDER BY
        total_ticket_price DESC
      ```
    </Tab>

    <Tab title="GCP">
      ```sql theme={null}
      -- Replace `nekt_raw.humanitix_events` / `nekt_raw.humanitix_tickets`
      -- with your configured dataset + table names.
      SELECT
        e.name AS event_name,
        COUNT(*) AS tickets_sold,
        SUM(t.price) AS total_ticket_price
      FROM
        `nekt_raw.humanitix_tickets` t
      JOIN
        `nekt_raw.humanitix_events` e
      ON e._id = t.eventId
      WHERE
        TIMESTAMP(t.updatedAt) >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
      GROUP BY
        1
      ORDER BY
        total_ticket_price DESC
      ```
    </Tab>
  </Tabs>
</Accordion>

## Implementation Notes

### Data quality considerations

* `events`, `orders`, and `tickets` support incremental sync using `updatedAt` as the replication key.
* `tags` does not provide an incremental replication key (`replication_key = None`), so `FULL_TABLE` is the appropriate sync type.
* Nested objects and arrays (for example `ticketTypes[]` and `additionalQuestions[]`) are available as structured columns in Nekt; inspect your table schema in the Catalog or use Explorer to validate how they are represented in SQL.

### Performance considerations

* `orders` and `tickets` are fetched per event (`/v1/events/{event_id}/...`). Syncing many events can increase extraction time.
* Use `start_date` to control how far back incremental history begins, and consider running incremental syncs regularly.

## Skills for agents

<Snippet file="agent-skills-intro.mdx" />

<Card title="Download Humanitix skills file" icon="wand-magic-sparkles" href="/sources/humanitrix.md">
  Humanitix connector documentation as plain markdown, for use in AI agent contexts.
</Card>