Endpoints
Bulk Create/Update People
This API is designed for bulk adding adding new people or patch updating existing people (upserting) to a Jomablue event.. People are created or updated based on the existence of an organisation UID.
Properties
Property | More |
|---|---|
event_id | required | integer The Jomablue event ID. This is found on the events list once logged into Jomablue. |
cancelled | true or false. If the person is cancelled they are not able to attend or interact with Jomablue experiences. true = Person is cancelled from the event. |
organisation_uid | required string A globally unique ID of a person that exists in another system. Using the same organisation_uid across different events in Jomablue will update the 'basic details' for that person across all events. |
first_name | required string The person's first name. Up to 190 characters |
last_name | required string The person's last name. Up to 190 characters |
job_title | The person's job title (eg: CEO, Analyst). Up to 190 characters |
company | The organisation name/company (eg: Acme, Spacex). Up to 190 characters |
Must be a valid email address format | |
mobile | Must be a valid E.165 mobile/cell number (eg: +400000000 or +15417543010) |
categories | An object of categories the person belongs too (eg: Delegate, VIP, Media), the categories must exactly match existing categories (case sensitive). Jomablue can add organisational policies to enforce category names across all events in your organisation an ensure they match API calls. Errors will be returned if the categories don't match any configured events. Omitting 'categories' all together assigns a 'default category' to the person. |
custom_fields | A place to store key/value data against a person record. eg, dietary requirements, data segmentation, interests, campaign identifiers or opt in statuses. Jomablue makes this available against people in exports/reports. The keys should be consistent but values are generally unique against an individual. Key must be all lowercase and use hyphens or underscores only. eg: dietary_requirement. Values must be a string. |
items | Add or remove Item entitlements for a person. Items are collected by the person at the event using their smart badge. Items must exist in Jomablue prior to making the API request to allocate them to the person. Multiple items can be added, including multiple of the same item. Items can also be removed - as long as they have not been collected. Important: When adding: replaying the same items with 'true' in multiple requests will keep adding additional items to the person. If you only want to allocate one to the person, only make one request that includes the items. When removing: All items (it could be one or many) that have not been collected by the person at the event will be removed (providing the item does not belong to an 'paid order' which may require a refund) |
Example Requests
Adding New People - A request that contains 3 new people with categories and custom fields
Updating Company Names - A request that contains organisaion_uid's of known people in Jomabue, only the minimum fields and changes to the company names.
Changing Category - A request that contains organisaion_uid's of known people in Jomabue, only the minimum fields and changes to the persons category by using true/false values.
Updating Custom Fields - A request that contains organisaion_uid's of known people in Jomabue, only the minimum fields and changes to some custom field values, including removing a custom field from a person by including #N/A.
Adding items - Adding Item ID 2 and Item ID 3 to a person. These Items are "Swag Bag" and "Lunch Token" respectivly. Removing Items - Removing Item ID 2 (Swag Bag) and adding an additional Item 2 (Lunch Token) regardless of how many existing lunch tokens the person had. Item 2 will only be removed if its not already colelcted or doesn't belong to a 'paid order' (aka, they paid for the item and may require a refund).
{
"event_id": 23,
"people": [{
"organisation_uid": "970457bc-783a-401c-a1dd-0759fd23e287",
"first_name": "Sherwin",
"last_name": "Urien",
"categories": {
"Delegate": false,
"VIP": true,
"After Party": false
}
}, {
"organisation_uid": "a6fd4204-912c-49e4-b274-a11f53f9c977",
"first_name": "Larissa",
"last_name": "Abbate",
"job_title": "Occupational Therapist",
"categories": {
"Delegate": true,
"VIP": false,
"After Party": false
}
}, {
"organisation_uid": "fd88f3e6-2411-4eac-a948-4b243d2a5f55",
"first_name": "Lilly",
"last_name": "Ilem",
"categories": {
"Delegate": false,
"VIP": true,
"After Party": true
}
}]
}
Example Results
{
"success":true,
"data":{
"import_id":494,
"records_processing":3,
"status":"pending"
},
"included":[]
}
Important Considerations
Default Category
This must be set in Jomablue before this API can be used, this is done in the Jomablue webapp. People in the API request that don't contain a category will be added to this default category automatically (all people must have a relationship to at least one category).
Limits
Up to 250 people can be included per request. Multiple requests can be made providing you keep within request rate and size limits. Regardless of the number of people in the request, there is an total size limit of 200 kb for the request body. Exceeding the 200 kb will return a 413 - Payload too large error.
Validation
Jomablue requires valid data to ensure attendees have a frictionless experience. Invalid data (such as incorrectly formatted mobile numbers or email addresses) will return a error (400 - Bad Request) and no records in that request will be processed. The required validation is detailed in the properties section below.
Processing Time
A successful response does not indicate the people are immediately added, rather it's queued for processing. Generally you can expect a HTTP response within 5 seconds and then people to be created or updated at a rate of 5 people per second with exponential increases over time.
Handling Updates
Default Fields (eg: first_name, last_name, job title, company name, mobile_number, email_address) The fields are updated only if they are provided in the data, otherwise they are left unchanged. (first_name and last_name are always updated as they must always be supplied). For Categories Categories are only updated if they are included in the data - If the value of the category is 'true' it is added if it is not already assigned, if the value is false it the category is removed if it is already assigned. If the category is not included but is already assigned it will remain assigned.
For Custom Fields Custom fields are only updated if they are included in the data - If the the custom field already exists, it will be updated with the new value, if it does not exist it will be added. Custom fields which are not included in the data will remain. In order to remove a custom field altogether it must be provided in the request with the value "#N/A".