> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the HighLevel data source in Adriel.

## Introduction

HighLevel (internally `goHighLevel`) is a CRM and marketing-automation platform for agencies. The connector imports HighLevel objects — contacts, opportunities, invoices, forms, calendar events, email campaigns, and phone numbers — over OAuth2 and stores them as rows in a per-data-source table.

HighLevel imports **one object type per data source**. To bring several object types from the same HighLevel location into a workspace, create one data source per type from the same authorized location. Because the connector imports raw objects rather than a fixed performance-metric set, the available columns are discovered from each object type and from the location's own fields, and the set can grow over time as HighLevel returns new fields.

To connect this data source, see [How to connect HighLevel to Adriel](/data-sources/g-n/highlevel/how-to-connect).

## Data refresh strategy

HighLevel is a **simple file-cache** connector. Each object type is cached as rows in its own table, and each scheduled run refreshes that cache in place (insert new rows, update existing rows by their unique key). There is no separate architecture-versus-reports split — a single cache holds the imported objects.

**Refresh schedule.** The cache refreshes **every 2 hours at minute 0 (UTC)** (cron `0 */2 * * *`). The refresh type is decided at runtime:

* **Full refresh** when the hour is 00, 06, 12, or 18 UTC (four of the twelve daily runs), when the cache table does not yet exist, or in development mode. A full refresh re-imports all available records for the object type.
* **Partial refresh** on every other run. Each object type uses a date cursor (see [Architecture levels](#architecture-levels)) to fetch only records changed since the last saved record, then upserts them into the cache.

Calendar events are the exception: they always re-fetch a fixed date window in full and ignore the partial cursor (see [Limitations](#limitations)).

## Architecture levels

HighLevel does not expose an ad-style account hierarchy. Each data source resolves to a single location and a single object type:

Location → Object type (one of: Contacts, Opportunities, Invoices, Forms, Calendar events, Email campaigns, Phone numbers)

Each object type is imported from its own HighLevel endpoint and uses its own partial-refresh cursor:

| Object type         | Partial-refresh cursor   | Unique key |
| ------------------- | ------------------------ | ---------- |
| Contacts            | `dateUpdated`            | `id`       |
| Opportunities       | `updatedAt`              | `id`       |
| Invoices            | `updatedAt`              | `id`       |
| Forms (submissions) | `createdAt`              | `id`       |
| Calendar events     | None — fixed window only | `id`       |
| Email campaigns     | `updatedAt`              | `id`       |
| Phone numbers       | `dateUpdated`            | `sid`      |

## Metrics

<Note>
  **How to read the columns**
  **Data type** uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
  **API Key** in code style like `dateUpdated` is the HighLevel object field name. Nested fields are flattened with an underscore delimiter (for example `contact.name` becomes `contact_name`). *Italic text* describes how a value is produced when it does not map cleanly to a single field.

  HighLevel imports raw objects, so the columns below are **representative** of each object type. The exact column set is discovered per object type and per location and can grow as HighLevel returns new fields; a location's custom fields appear as additional columns resolved by name.
</Note>

### Contacts & audience

Imported from the Contacts object type.

| Metric        | Description                                                                  | Data type | API Key                 |
| ------------- | ---------------------------------------------------------------------------- | --------- | ----------------------- |
| Contact ID    | Unique HighLevel contact identifier.                                         | Text      | `id`                    |
| First name    | Contact first name.                                                          | Text      | `firstName`             |
| Last name     | Contact last name.                                                           | Text      | `lastName`              |
| Email         | Contact email address.                                                       | Text      | `email`                 |
| Phone         | Contact phone number.                                                        | Text      | `phone`                 |
| Tags          | Tags applied to the contact.                                                 | Array     | `tags`                  |
| Source        | How the contact entered HighLevel.                                           | Text      | `source`                |
| Postal code   | Contact postal code, stored with a `code:` prefix to preserve leading zeros. | Text      | `postalCode`            |
| Age           | Not imported — hardcoded to the literal string "NA".                         | Text      | `age`                   |
| Date added    | When the contact was created.                                                | Date      | `dateAdded`             |
| Date updated  | When the contact was last modified (partial-refresh cursor).                 | Date      | `dateUpdated`           |
| Custom fields | Location-defined custom fields, resolved by name into their own columns.     | Text      | *Resolved per location* |

### Opportunities & pipeline

Imported from the Opportunities object type. Records are flattened; the nested `notes`, `tasks`, `calendarEvents`, `customFields`, and `followers` fields are omitted, and `contact.tags` is joined into a comma-separated string.

| Metric            | Description                                                             | Data type | API Key                 |
| ----------------- | ----------------------------------------------------------------------- | --------- | ----------------------- |
| Opportunity ID    | Unique opportunity identifier.                                          | Text      | `id`                    |
| Opportunity name  | Opportunity title.                                                      | Text      | `name`                  |
| Status            | Opportunity status (for example open, won, lost, abandoned).            | Text      | `status`                |
| Pipeline ID       | Pipeline the opportunity belongs to.                                    | Text      | `pipelineId`            |
| Pipeline stage ID | Current stage within the pipeline.                                      | Text      | `pipelineStageId`       |
| Monetary value    | Opportunity value.                                                      | Currency  | `monetaryValue`         |
| Contact ID        | Associated contact.                                                     | Text      | `contactId`             |
| Contact tags      | Tags on the associated contact, joined into one comma-separated string. | Text      | *`contact.tags` joined* |
| Date updated      | When the opportunity was last modified (partial-refresh cursor).        | Date      | `updatedAt`             |

### Campaigns & sends

Imported from the Email campaigns (schedules) object type. The `emails` alias resolves to the same import. The `__v`, `child`, `_id`, `sendDays`, and `resendInfo` fields are stripped before storage.

| Metric        | Description                                                   | Data type | API Key     |
| ------------- | ------------------------------------------------------------- | --------- | ----------- |
| Campaign ID   | Unique email campaign / schedule identifier.                  | Text      | `id`        |
| Campaign name | Email campaign name.                                          | Text      | `name`      |
| Status        | Campaign status.                                              | Text      | `status`    |
| Date updated  | When the campaign was last modified (partial-refresh cursor). | Date      | `updatedAt` |

### Appointments & activities

This category covers three object types — calendar events, form submissions, and phone numbers — each imported into its own data source.

**Calendar events.** Fetched per calendar over a fixed window (now − 3 days to now + 50 days); drafted calendars are skipped.

| Metric             | Description                       | Data type | API Key             |
| ------------------ | --------------------------------- | --------- | ------------------- |
| Event ID           | Unique calendar-event identifier. | Text      | `id`                |
| Title              | Event / appointment title.        | Text      | `title`             |
| Start time         | Event start.                      | Date      | `startTime`         |
| End time           | Event end.                        | Date      | `endTime`           |
| Appointment status | Status of the appointment.        | Text      | `appointmentStatus` |

**Form submissions.** Fetched from form submissions; full sync starts at `2000-01-01`. Records are flattened.

| Metric        | Description                                                | Data type | API Key     |
| ------------- | ---------------------------------------------------------- | --------- | ----------- |
| Submission ID | Unique form-submission identifier.                         | Text      | `id`        |
| Form ID       | Form the submission belongs to.                            | Text      | `formId`    |
| Date created  | When the submission was received (partial-refresh cursor). | Date      | `createdAt` |

**Phone numbers.** Fetched per location; the unique key is `sid`.

| Metric           | Description                                                        | Data type | API Key       |
| ---------------- | ------------------------------------------------------------------ | --------- | ------------- |
| Phone number SID | Unique phone-number identifier.                                    | Text      | `sid`         |
| Phone number     | The provisioned phone number.                                      | Text      | `phoneNumber` |
| Date updated     | When the number record was last modified (partial-refresh cursor). | Date      | `dateUpdated` |

### Revenue

Imported from the Invoices object type, using the `altId` / `altType=location` request parameters.

| Metric         | Description                                                  | Data type | API Key         |
| -------------- | ------------------------------------------------------------ | --------- | --------------- |
| Invoice ID     | Unique invoice identifier.                                   | Text      | `id`            |
| Invoice number | Human-readable invoice number.                               | Text      | `invoiceNumber` |
| Total          | Invoice total amount.                                        | Currency  | `total`         |
| Amount paid    | Amount paid against the invoice.                             | Currency  | `amountPaid`    |
| Status         | Invoice status (for example draft, sent, paid, void).        | Text      | `status`        |
| Date updated   | When the invoice was last modified (partial-refresh cursor). | Date      | `updatedAt`     |

## Breakdowns

<Note>
  Because HighLevel imports raw object rows into a generic table, any imported column can be used to group rows — there is no fixed breakdown allowlist. The columns available for grouping depend on the object type and on the location's own fields, and can grow over time as HighLevel returns new fields.
</Note>

### Object attributes

Group rows by any categorical column on the imported object. Common examples per object type:

| Breakdown      | Description                                                           | API Key           |
| -------------- | --------------------------------------------------------------------- | ----------------- |
| Status         | Group by object status (opportunity, invoice, campaign, appointment). | `status`          |
| Pipeline stage | Group opportunities by pipeline stage.                                | `pipelineStageId` |
| Source         | Group contacts by acquisition source.                                 | `source`          |
| Tags           | Group contacts by tag.                                                | `tags`            |
| Form           | Group form submissions by form.                                       | `formId`          |

### Date grouping

<Note>
  Date groupings are Adriel-side aggregations applied to an object's date field (for example `dateUpdated`, `updatedAt`, or `createdAt`); they are not returned by HighLevel.
</Note>

| Breakdown           | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| Auto Time Breakdown | Automatically picks the best granularity for the date range. |
| Daily               | Split rows by day.                                           |
| Weekly              | Split rows by week.                                          |
| Monthly             | Split rows by calendar month.                                |
| Quarterly           | Split rows by calendar quarter.                              |
| Yearly              | Split rows by calendar year.                                 |

## Limitations

* **One object type per data source** — each HighLevel data source imports exactly one object type. To combine object types, create one data source per type from the same location.
* **Per-run row cap** — each object type imports up to 100 pages of 100 records (10,000 rows) per run; locations with more records may not be fully represented in a single run.
* **Calendar events use a fixed window** — calendar events are always fetched for now − 3 days to now + 50 days and the full window is re-fetched every run. Events outside that window are not retained, and the partial-refresh cursor is ignored.
* **Server region restriction** — only HighLevel accounts hosted in the EU or KR server regions are supported.
* **Single-use refresh tokens** — each token refresh issues a new refresh token that supersedes the prior one; a HighLevel-side revocation is only detected on the next scheduled sync.
* **Dynamic schema** — the column set is discovered at import time and is not static; new fields returned by HighLevel appear as new columns on subsequent syncs.

## API references

* [HighLevel (LeadConnector) API documentation](https://highlevel.stoplight.io/docs/integrations/)
* [Contacts API](https://highlevel.stoplight.io/docs/integrations/contacts-api)
* [Opportunities API](https://highlevel.stoplight.io/docs/integrations/opportunities-api)
* [Invoices API](https://highlevel.stoplight.io/docs/integrations/invoices-api)
* [Calendars API](https://highlevel.stoplight.io/docs/integrations/calendars-api)
* [Forms API](https://highlevel.stoplight.io/docs/integrations/forms-api)

## See also

* [How to connect HighLevel to Adriel](/data-sources/g-n/highlevel/how-to-connect) (paired how-to)
* [HubSpot Deals data reference](/data-sources/g-n/hubspot-deals/data-reference) — for deal pipeline and revenue reporting
* [Active Campaign data reference](/data-sources/a-f/active-campaign/data-reference) — for another CRM / marketing-automation source