---
title: EventPerson Mapping
slug: docs/eventperson-mapping
createdAt: 2026-07-07T04:09:19.837Z
---

An **EventPerson** ingest creates or updates a person in an event from a JSON payload — usually a webhook from your CRM. A **field map** lists rules; each rule reads a value from your payload (keyMatch) and writes it to a Jomablue field (type). The person is identified by `organisation_uid`: a match updates the existing person, otherwise a new one is created. Anything in the payload that no rule references is ignored.

## The mapping

:::BlockQuote
\[
&#x20; \{ "type": "organisation\_uid", "keyMatch": "organisation\_uid" },
&#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": "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 },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "Staff",    "mapToId": 4 },
&#x20; \{ "type": "category", "keyMatch": "category", "valueMatch": "VIP",      "mapToId": 5 },
&#x20; \{ "type": "custom\_field", "keyMatch": "custom\_fields.\*", "mapToKey": "\*" }
]
:::

## The fields

**Identifier and text fields.** `organisation_uid` is the person's unique ID in your system — it decides update-vs-create, so use something stable like a CRM contact ID. `first_name`, `last_name`, `job_title`, `company`, and `email` are straight copies from the payload path in keyMatch.

**mobile.** Numbers are stored in international E164 format. With mobileCountry pointing at a country field, local formats are converted automatically — `0402 222 111` with AU becomes `+61402222111`. Country accepts codes like `AU`/`AUS`. Without mobileCountry, the number must already start with `+`.

**category.** Each rule fires when the payload's category field equals its valueMatch, and assigns the matching `mapToId`:

| category value | Category ID |
| -------------- | ----------- |
| Delegate       | 1           |
| Sponsor        | 2           |
| Speaker        | 3           |
| Staff          | 4           |
| VIP            | 5           |

Categories are **additive** here: assigning one leaves any categories the Person already has in place. That's the difference from the advanced version, which removes the other roles when it assigns one. If no Category is assigned, the event's default Category is applied.

:::hint{type="info"}
Note: The IDs 1–5 are placeholders. Use your event's real category IDs, and set valueMatch to the strings your system actually sends.
:::

**custom\_field.** The wildcard rule takes every key/value pair inside the payload's custom\_fields object and stores each as a custom field, reusing the payload's own keys. Use snake\_case keys. Custom Fields must always be a string value, booleans are not accepted.

:::hint{type="info"}
Note: if a custom\_field wildcard mapping is used, then the custom\_field object **must** be included in the payload, even if it is empty.
:::



## Worked example

**Payload:**

:::BlockQuote
\{
&#x20; "organisation\_uid": "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; "category": "Staff",
&#x20; "custom\_fields": \{ "dietary\_requirements": "Vegetarian", "tshirt\_size": "L", "attending\_dinner": "true" }
}
:::

**Result:** a person CRM-10432 (created or updated) named Jordan Avery, Head of Partnerships at Northwind Labs, email as given, mobile +61402222111, category Speaker (ID 3) added, plus custom fields dietary\_requirements = Vegetarian, tshirt\_size = L, and attending\_dinner = true

## Validation

You can validate the payload before it's mapped. A payload that fails is rejected before anything is created.

:::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; "company": "nullable|string",
&#x20; "job\_title": "nullable|string",
&#x20; "category": "nullable|in\:Delegate,Sponsor,Speaker,Staff,VIP"
}
:::

`required` fields must be present (the identifier and the names needed to create a person). `nullable` fields are only checked when present. The `in:` rule limits category to the five known roles, catching typos before they map to nothing. Match the keys to your payload, and update the in: list to your own values.

## Other available fields

EventPerson also supports cancelled, item, and program\_member. See the full Ingest Endpoints reference for those.
