# Customer Designated UUID Sync

{% hint style="info" %}
This is a feature exclusively for enterprise accounts
{% endhint %}

The Customer Designated UUID Sync allows Untitled to capture a customer-defined identifier from the page environment and attach it to the visitor resolution process (similar to a cookie-sync protocol).

This enables downstream workflows where a client needs to **join Untitled identity resolution data with their own system identifiers** (such as customer IDs, event IDs, order IDs, form submission IDs, or internal partner identifiers).

Once configured, the identifier(s) are captured during page load by the Untitled tag and stored alongside the associated external pageview identifier **(`external_id`)**, allowing them to be joined to visitor resolution data in downstream systems, such as [client-provisioned database resource](/custom-connections.md).

***

## How It Works

When enabled, the Untitled tag will:

1. Wait for the page to fully load.
2. Extract the configured identifier(s) from the page environment.
3. Append those values to a payload associated with the pageview.
4. Attach Untitled’s internal `external_id` (the pageview UUID).
5. Send the payload to the Untitled attribution endpoint.
6. Store the resulting records in a client-accessible table.

This allows the client to join their identifiers with Untitled’s resolution data using the shared `external_id`.

***

### Supported Extraction Methods

Identifiers can be extracted from several locations on the page depending on how the client exposes them.

#### DOM Elements

Values can be retrieved directly from HTML elements.

Example:

```
document.getElementById('OrderFormInstance').value
```

This method is commonly used for:

* form instance identifiers
* transaction IDs
* dynamically generated form values

***

#### JavaScript Objects (dataLayer)

Identifiers can also be extracted from JavaScript objects such as a `dataLayer`.

Example:

```
dataLayer[0].partnerId
```

This method is common for:

* analytics variables
* partner identifiers
* campaign metadata
* event identifiers

***

### Example Field Mapping

Below is an example of how a customer’s identifiers may be mapped.

| Customer Field      | Extraction Method                                    | Example Source                    |
| ------------------- | ---------------------------------------------------- | --------------------------------- |
| `partner_id`        | `dataLayer[0].partnerId`                             | Partner identifier from dataLayer |
| `OrderEventId`      | `dataLayer[0].eventId`                               | Event identifier                  |
| `OrderFormInstance` | `document.getElementById('OrderFormInstance').value` | Form instance identifier          |

These values are captured during page load and associated with the pageview.

***

### Data Model

Each captured record includes the following fields:

| Field                 | Description                         |
| --------------------- | ----------------------------------- |
| `external_id`         | Untitled pageview identifier (UUID) |
| `partner_id`          | Client partner identifier           |
| `order_event_id`      | Event identifier from the page      |
| `order_form_instance` | Form instance identifier            |
| `timestamp`           | Time of capture                     |

The `external_id` allows these values to be joined to visitor resolution records.

***

### Accessing the Data

Captured identifiers are made available in a **client-provisioned database resource**. 

Example table:

```
{untitled-client-name}_attribution
```

This table contains a row for every instance where the configured identifiers were successfully extracted. The dataset updates approximately **every 15 minutes**.

{% hint style="info" %}
It is on our roadmap to make this functionality available via API
{% endhint %}

***

### Joining to Resolution Data

To associate the identifiers with Untitled visitor resolution data, join the attribution table with the resolutions table using `external_id`.

Example query:

```
SELECT *
FROM resolutions.pages p
INNER JOIN {untitled-client-name}_attribution ta
ON p.external_id = ta.external_id;
```

This allows customers to combine:

* Untitled resolved visitor data
* their internal identifiers
* page-level activity

***

## Setup Requirements

To configure a Customer UUID Sync, Untitled requires the following information from the client.

#### 1. Identifier Name and Example Value

Provide the literal field name and an example value.

Example:

```
ID name: MyUniqueId
Example value: 68dd9e83-3e98-4ae1-b16c-00420a1e2112
```

***

#### 2. Location of the Identifier

Indicate where the identifier appears on the page.

Examples:

* DOM element
* JavaScript variable
* dataLayer property

Providing a **Chrome DevTools screenshot** highlighting the identifier is highly recommended as this will help our team easily triangulate the ID you want us to test extracting. 

***

#### 3. Test URL

Provide a URL where:

* the Untitled tag is installed
* the identifier is present on page load

This allows our team to validate extraction from the page.

***

### Configuration Process

Once the required information is provided, Untitled will:

1. Validate that the identifiers can be retrieved from the page.
2. Configure the extraction logic for the client’s tag.
3. Deploy the updated tag configuration.
4. Enable ingestion into the attribution service.
5. Expose the resulting dataset in the client Postgres environment.

***

### Important Notes

* All identifiers must be available **at page load** for reliable extraction.
* If an identifier is missing, the event may not be recorded.
* Multiple identifiers can be captured in the same configuration.
* **This feature is configured per client environment and requires 5–7 business days for setup once the necessary implementation details have been provided.** This timeframe allows our team to validate the identifiers, test extraction from the page environment, configure the endpoint, and deploy the workflow.

***

### Common Use Cases

Customer UUID Sync is commonly used for:

* event platform integrations
* CDP identifiers
* Customer order attribution
* Form submission linking
* Partner program tracking
* CRM or internal ID reconciliation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.getuntitled.ai/customer-designated-uuid-sync.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.