---
title: EventPerson Mapping - Advanced
slug: docs/eventperson-mapping-advanced
createdAt: 2026-07-22T08:28:25.099Z
---

This article covers the advanced **EventPerson** field-map options that go beyond the starter mapping: making category roles mutually exclusive, migrating identifiers, and the fields the basic article only mentions in passing (items, program membership, and cancellation).

:::BlockQuote
New to EventPerson ingests? Start with the basic mapping and the mapping overview. This article assumes you already know how a field map reads keyMatch from your payload and writes to a type.
:::

## How it works

An EventPerson ingest creates or updates a person within a single event. A **field map** is a list of rules; each rule reads a value from your payload (keyMatch) and writes it to a Jomablue field (type). keyMatch is a path, so a value can sit anywhere in the payload, including inside nested objects (contact.details.email). A person is identified by organisation\_uid: a match updates the existing person, otherwise a new one is created. Anything the mapping does not reference is ignored, so an over-complete mapping never causes harm.

## The mapping

The complete mapping combines every technique in this article. Each section below explains one part of it.

:::BlockQuote
\[
&#x20; \{ "type": "organisation\_uid", "keyMatch": "legacy\_id|contact\_id" },
&#x20; \{ "type": "first\_name", "keyMatch": "first\_name" },
&#x20; \{ "type": "last\_name", "keyMatch": "last\_name" },
&#x20; \{ "type": "job\_title", "keyMatch": "job\_title" },
&#x20; \{ "type": "company", "keyMatch": "company" },
&#x20; \{ "type": "email", "keyMatch": "email" },
&#x20; \{ "type": "mobile", "keyMatch": "mobile", "mobileCountry": "country" },
&#x20; \{ "type": "cancelled", "keyMatch": "status", "valueMatch": "cancelled" },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Delegate", "mapToId": 1, "replaceExistingIds": \[2, 3, 4, 5] },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Sponsor",  "mapToId": 2, "replaceExistingIds": \[1, 3, 4, 5] },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Speaker",  "mapToId": 3, "replaceExistingIds": \[1, 2, 4, 5] },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Staff",    "mapToId": 4, "replaceExistingIds": \[1, 2, 3, 5] },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "VIP",      "mapToId": 5, "replaceExistingIds": \[1, 2, 3, 4] },
&#x20; \{ "type": "item", "keyMatch": "ticket\_type", "valueMatch": "gala", "mapToId": 12 },
&#x20; \{
&#x20;   "type": "program\_member",
&#x20;   "keyMatch": "memberships.\*",
&#x20;   "programUidKeyMatch": "program\_uid",
&#x20;   "programNameKeyMatch": "program\_name",
&#x20;   "programMemberUidKeyMatch": "member\_uid",
&#x20;   "programMemberStatusKeyMatch": "membership\_status",
&#x20;   "programMemberArchivedKeyMatch": "archived"
&#x20; },
&#x20; \{ "type": "custom\_field", "keyMatch": "custom\_fields.\*", "mapToKey": "\*" }
]
:::

## Matching on more than one unique identifier

The `organisation_uid` rule can list several payload paths separated by `|`, oldest first:

:::BlockQuote
\{ "type": "organisation\_uid", "keyMatch": "legacy\_id|contact\_id" }
:::

The endpoint reads whichever of those paths are present in the payload. This is useful when you change the identifier your system sends: a person first created under legacy\_id is still matched when you start sending contact\_id, so they are updated in place rather than duplicated. The right-most path is treated as the current identifier.

## Assigning categories

Categories group People by role or type (Delegate, Sponsor, Speaker, and so on). There are two ways to assign them, and a mapping should use **one style only**.

**By value.** Use value rules when your payload carries a role as text (for example "category": "Speaker"). Each rule fires when the payload value equals its valueMatch, and assigns the matching mapToId:

:::BlockQuote
\[
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Delegate", "mapToId": 1 },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Sponsor",  "mapToId": 2 },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Speaker",  "mapToId": 3 }
]
:::

If the path in keyMatch holds an array rather than a single string, the rule fires when valueMatch is one of the array's values. That lets a payload send several roles at once (for example "roles": \["Speaker", "VIP"]) and have each matching rule assign its category.

**By ID.** Use the wildcard form when your payload already carries Jomablue category IDs as an array:

:::BlockQuote
\{ "type": "category", "keyMatch": "categories.\*", "mapToKey": "\*" }
:::

This reads the array at categories and assigns each entry as a category ID. Only integer IDs are accepted; anything else in the array is ignored. Category IDs are specific to each instance, not each event: a given ID identifies the same category across every event in your instance.

:::BlockQuote
The numbers used here are placeholders. Look up the real category IDs from your instance, and set valueMatch to the strings your system actually sends.
:::

If an ingest assigns no category, the event's default category is applied.

## Replacing categories (mutually exclusive roles)

By default categories are **additive**: assigning one leaves any the person already has. To make roles mutually exclusive, so a person ends up in exactly one, add replaceExistingIds to each value rule listing the other IDs in the set:

:::BlockQuote
\[
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Delegate", "mapToId": 1, "replaceExistingIds": \[2, 3, 4, 5] },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Sponsor",  "mapToId": 2, "replaceExistingIds": \[1, 3, 4, 5] },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Speaker",  "mapToId": 3, "replaceExistingIds": \[1, 2, 4, 5] },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Staff",    "mapToId": 4, "replaceExistingIds": \[1, 2, 3, 5] },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "VIP",      "mapToId": 5, "replaceExistingIds": \[1, 2, 3, 4] }
]
:::

When a rule assigns its category, the IDs in its replaceExistingIds are removed from the person. A rule never lists its own mapToId. Any category the person holds that is not in the list is left untouched.

With the set above, sending "category": "Speaker" assigns category 3 and removes 1, 2, 4, and 5. Send "category": "Sponsor" next time and the person moves from Speaker to Sponsor. This is the technique to reach for when each person maps to a single role and re-sends should overwrite the previous one.

## Assigning a single item

The item type assigns a fixed item (a gala dinner ticket, a workshop place, a piece of merchandise) when a payload value is present:

:::BlockQuote
\{ "type": "item", "keyMatch": "add\_dinner\_ticket", "mapToId": 12 }
:::

The item with mapToId is assigned when the value at keyMatch is present and truthy. Add valueMatch to require a specific value:

:::BlockQuote
\{ "type": "item", "keyMatch": "ticket\_type", "valueMatch": "gala", "mapToId": 12 }
:::

Here the item is assigned only when ticket\_type equals gala. Unlike categories, assigning an item does not remove other items, and mapToId is required.

## Program and campaign membership

The program\_member type links a person to a membership in one of your programs or campaigns. It reads a nested object (or an array of them) and needs the program's UID and the membership's UID at minimum:

:::BlockQuote
\{
&#x20; "type": "program\_member",
&#x20; "keyMatch": "memberships.\*",
&#x20; "programUidKeyMatch": "program\_uid",
&#x20; "programNameKeyMatch": "program\_name",
&#x20; "programMemberUidKeyMatch": "member\_uid",
&#x20; "programMemberStatusKeyMatch": "membership\_status",
&#x20; "programMemberArchivedKeyMatch": "archived"
}
:::

- **keyMatch** points at the membership object. Use a wildcard (memberships.\*) when the payload carries an array of memberships; the remaining paths are then read from each element.
- **programUidKeyMatch** and **programMemberUidKeyMatch** are required. A membership is only created when both resolve to a value.
- **programNameKeyMatch**, **programMemberStatusKeyMatch**, and **programMemberArchivedKeyMatch** are optional.

For a single membership, point keyMatch at the object ("keyMatch": "membership") and drop the wildcard.

## Cancellation status

The cancelled type sets a person's registration status from a value in your payload:

:::BlockQuote
\{ "type": "cancelled", "keyMatch": "status", "valueMatch": "cancelled" }
:::

When the value at keyMatch equals valueMatch, the person is marked cancelled. Any other non-empty value marks them registered. If the field is absent, the status is left unchanged. valueMatch is required, and defines which incoming value means cancelled.

## Custom fields: named and wildcard

The wildcard form maps every key inside an object to a custom field, reusing the payload's own keys:

:::BlockQuote
\{ "type": "custom\_field", "keyMatch": "custom\_fields.\*", "mapToKey": "\*" }
:::

To map a single, specifically named field, use a fixed keyMatch and mapToKey:

:::BlockQuote
\{ "type": "custom\_field", "keyMatch": "tshirt\_size", "mapToKey": "tshirt\_size" }
:::

You can combine both: a wildcard rule for the bulk of the object plus named rules for values that live elsewhere in the payload. Custom field keys should be snake\_case.

## Mobile numbers and country

Mobile numbers are stored in international E164 format (for example +61402222111). The mobileCountry option controls how local formats are handled:

:::BlockQuote
\{ "type": "mobile", "keyMatch": "mobile", "mobileCountry": "country" }
:::

- **With mobileCountry**: the number is parsed using that country's rules and converted to E164, so local formats are accepted. 0402 222 111 with country AU becomes +61402222111. mobileCountry points at the payload path holding the country. Accepted values are ISO 3166 alpha-2 (AU) or alpha-3 (AUS) codes, or country names.
- **Without mobileCountry**: the number must already be in E164 format (starting with +). Anything else is discarded.

If you only ever receive local numbers from one country, point mobileCountry at any payload field that reliably carries that country code.

## Worked example

**Payload:**

:::BlockQuote
\{
&#x20; "contact\_id": "CRM-10432",
&#x20; "first\_name": "Jordan",
&#x20; "last\_name": "Avery",
&#x20; "job\_title": "Head of Partnerships",
&#x20; "company": "Northwind Labs",
&#x20; "email": "jordan.avery\@northwindlabs.com",
&#x20; "mobile": "0402 222 111",
&#x20; "country": "AU",
&#x20; "status": "registered",
&#x20; "category": "Speaker",
&#x20; "ticket\_type": "gala",
&#x20; "memberships": \[
&#x20;   \{ "program\_uid": "PROG-2026", "program\_name": "Ambassadors", "member\_uid": "M-88", "membership\_status": "active", "archived": false }
&#x20; ],
&#x20; "custom\_fields": \{ "dietary\_requirements": "Vegetarian", "tshirt\_size": "L" }
}
:::

**Resulting person:**

| Field                | Value                                                                 |
| -------------------- | --------------------------------------------------------------------- |
| organisation\_uid    | CRM-10432 (read from contact\_id; matched if it exists, else created) |
| name                 | Jordan Avery                                                          |
| job\_title / company | Head of Partnerships, Northwind Labs                                  |
| email                | jordan.avery\@northwindlabs.com                                       |
| mobile               | +61402222111 (converted from local AU format)                         |
| status               | registered (not cancelled, so active)                                 |
| category             | Speaker (ID 3); IDs 1, 2, 4, 5 removed if present                     |
| item                 | gala dinner ticket (ID 12)                                            |
| program membership   | Ambassadors (PROG-2026), member M-88                                  |
| custom fields        | dietary\_requirements = Vegetarian, tshirt\_size = L                  |

Send the same identifier again with different values and the person is updated in place. Send "category": "Sponsor" next time and the person moves from Speaker to Sponsor.

## Validation

Before a payload is mapped, it can be checked against validation rules. Each rule targets a payload key (dot notation, including wildcards for arrays) and applies one or more checks separated by |. A payload that fails is rejected before any person is created or updated.

:::BlockQuote
\{
&#x20; "organisation\_uid": "required|string",
&#x20; "first\_name": "required|string",
&#x20; "last\_name": "required|string",
&#x20; "email": "nullable|email",
&#x20; "mobile": "nullable|string",
&#x20; "category": "nullable|in\:Delegate,Sponsor,Speaker,Staff,VIP",
&#x20; "status": "nullable|in\:registered,cancelled",
&#x20; "memberships.\*.program\_uid": "required\_with\:memberships|string",
&#x20; "memberships.\*.member\_uid": "required\_with\:memberships|string"
}
:::

- **required** rejects a payload where the field is missing or empty (the identifier and the names needed to create a person).
- **nullable** is only checked when present.
- **in:...** limits a value to a fixed list, catching typos before they map to nothing.
- **required\_with:...** requires a field only when a related field is present, so the membership identifiers are only enforced when memberships is sent.

Match these keys to your own payload paths, and update the lists to your own values.

##

