> For the complete documentation index, see [llms.txt](https://docs.optibase.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optibase.io/integrations/marketo.md).

# Marketo

Complete these steps in your Marketo instance before configuring the integration in the Optibase dashboard.

{% stepper %}
{% step %}

## Create an API Role

Marketo requires a dedicated role with API permissions.

1. Go to **Admin → Users and Roles**
2. Click **New Role**
3. Give it a name (e.g. `Optibase API`)
4. Enable the following permissions:
   * **Access API**
   * **Read-Write Lead**
   * **Read-Write Activity**
5. Save the role
   {% endstep %}

{% step %}

## Create an API-Only User

1. Go to **Admin → Users and Roles**
2. Click **Invite New User**
3. Fill in a name and email
4. On the Roles step, assign the role created in Step 1
5. Check **API Only**
6. Complete the invite
   {% endstep %}

{% step %}

## Create a LaunchPoint Service

This generates the Client ID and Client Secret used by Optibase.

1. Go to **Admin → Integration → LaunchPoint**
2. Click **New → New Service**
3. Fill in:
   * **Display Name**: `Optibase`
   * **Service**: `Custom`
   * **API Only User**: select the user created in Step 2
4. Click **Create**
5. Click **View Details** on the new service — copy the **Client ID** and **Client Secret**
   {% endstep %}

{% step %}

## Find Your Munchkin ID

1. Go to **Admin → Integration → Munchkin**
2. Copy the **Munchkin Account ID** (format: `XXX-XXX-XXX`)
   {% endstep %}

{% step %}

## Create the Custom Activity Type

Optibase sends a custom activity to Marketo each time a visitor is exposed to a test variant.

1. Go to **Admin → Marketo Custom Activities**
2. Click **New Custom Activity**
3. Fill in:
   * **Name**: `Optibase Variant Seen`
   * **API Name**: leave as auto-generated
   * **Description**: `Fired when a visitor is assigned and exposed to a test variant in Optibase`
4. Set the **Primary Attribute**:
   * **Name**: `Test ID`
   * **API Name**: `testId`
   * **Data Type**: `String`
5. Add the following **Secondary Attributes** (click **Add Attribute** for each):

   | Name         | API Name      | Data Type |
   | ------------ | ------------- | --------- |
   | Variant ID   | `variantId`   | String    |
   | Variant Name | `variantName` | String    |
   | Test Name    | `testName`    | String    |
   | Workspace ID | `workspaceId` | String    |
   | Origin URL   | `originUrl`   | String    |
   | View ID      | `viewId`      | String    |

   > The **API Name** values must match exactly as shown — Optibase uses these to map data.
6. Click **Create**
7. Click **Approve** on the activity — it will not be usable until approved
8. Note the **Activity Type ID** shown in the Custom Activities list — you will need this in the Optibase dashboard
   {% endstep %}

{% step %}

## Set Up the Lookup Field

The **Lookup Field** is the Marketo Lead field that contains the same value you pass to Optibase as the user's external identifier.

When Optibase receives:

```javascript
optibase.setTestedUserExternalId(externalId)
```

it will search Marketo for a lead where:

```
{Lookup Field} = {externalId}
```

### Example

If your application calls:

```javascript
optibase.setTestedUserExternalId("user_123")
```

then the Marketo lead must contain:

| Marketo Field | Value      |
| ------------- | ---------- |
| `externalId`  | `user_123` |

If your application calls:

```javascript
optibase.setTestedUserExternalId("john@example.com")
```

then the Marketo lead must contain:

| Marketo Field | Value              |
| ------------- | ------------------ |
| `email`       | `john@example.com` |

The value stored in Marketo must exactly match the value being sent to Optibase.

### Option A — You pass the user's email address as `externalId`

If the value passed to Optibase is the user's email address:

```javascript
optibase.setTestedUserExternalId("john@example.com")
```

then you can use Marketo's built-in `email` field.

Enter:

```
email
```

as the Lookup Field in the Optibase dashboard.

No additional Marketo field setup is required.

### Option B — You pass any other identifier as `externalId`

If the value passed to Optibase is not an email address (for example a customer ID, CRM ID, user ID, or account ID), you must create a Marketo Lead field that stores that same value.

1. Go to **Admin → Field Management**
2. Click **New Custom Field**
3. Fill in:
   * **Object**: `Lead`
   * **Type**: `String` (or `Integer` if your identifier is numeric)
   * **Name**: any name you prefer (e.g. `External ID`)
   * **API Name**: note this value exactly (e.g. `externalId`, `crmUserId`, `customerId`)
4. Click **Create**

Enter the field's **API Name** as the Lookup Field in the Optibase dashboard.

### Example

Application:

```javascript
optibase.setTestedUserExternalId("user_123")
```

Marketo:

| Field        | Value      |
| ------------ | ---------- |
| `externalId` | `user_123` |

Optibase Lookup Field:

```
externalId
```

> The Lookup Field must contain the same value that your application passes to `optibase.setTestedUserExternalId(...)`. If the values do not match, Optibase will not be able to find the correct Marketo lead.

**If you leave the Lookup Field blank** in the Optibase dashboard, Optibase defaults to:

```
externalId
```

In that case, create a Marketo Lead field with API Name:

```
externalId
```

and store the same external identifier value that you pass to Optibase.
{% endstep %}

{% step %}

## Configure in Optibase

Go to **Optibase Dashboard → Settings → Integrations → Marketo** and enter:

| Field            | Where to find it                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------ |
| Munchkin ID      | Admin → Munchkin → Munchkin Account                                                        |
| Client ID        | LaunchPoint → View Details                                                                 |
| Client Secret    | LaunchPoint → View Details                                                                 |
| Lookup Field     | The API name of the field you chose in Step 6. Leave blank to use the default `externalId` |
| Activity Type ID | Admin → Custom Activities (the number shown next to your activity)                         |

Click **Connect** — Optibase will verify the credentials before saving.
{% endstep %}
{% endstepper %}

## How it works after setup

* When a visitor is identified in the app with the external identifier provided by your application, Optibase associates that identifier with the visitor
* Optibase looks up the lead in Marketo using the **Lookup Field** and the provided `externalId`
* If no lead exists, one is created automatically with that field set to the `externalId`
* Each test variant the visitor has been exposed to is sent to Marketo as an **Optibase Variant Seen** custom activity attached to that lead
* Previously seen variants from before identification are backfilled automatically

## Troubleshooting

**Connection fails on save**

* Double-check the Munchkin ID format (`XXX-XXX-XXX`)
* Ensure the Client ID and Secret are from the LaunchPoint service, not from another integration
* Confirm the API-only user has the role with all three permissions

**No activities appearing on leads**

* Confirm the custom activity is in **Approved** status
* Confirm the Activity Type ID in Optibase matches the one in Marketo Admin

**Lead not found / created with wrong field**

* Confirm the Lookup Field API name matches exactly (case-sensitive) what is in Marketo Field Management
* Confirm the `externalId` your app passes to Optibase matches the value stored on the lead in Marketo for that field