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 post https //acme jomablue com/import/api/v1/people 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 email 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 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) adding new people { "event id" 23, "people" \[{ "organisation uid" "970457bc 783a 401c a1dd 0759fd23e287", "first name" "sherwin", "last name" "urien", "job title" "nurse", "company" "ozu", "email" "surien0\@etseey com", "mobile" "+61491570158", "categories" { "delegate" true, "vip" true, "after party" true }, "custom fields" { "opt in" "no", "business unit" "sales", "primary interest" "other", "phone" "992 398 5321", "country" "micronesia" } }, { "organisation uid" "a6fd4204 912c 49e4 b274 a11f53f9c977", "first name" "larissa", "last name" "abbate", "job title" "occupational therapist", "company" "twiyo", "email" "labbate1\@sciencedays com", "mobile" "+12025550100", "categories" { "delegate" false, "vip" false, "after party" true }, "custom fields" { "dietary" "paleo", "opt in" "yes", "business unit" "marketing", "primary interest" "networking", "phone" "904 641 4763", "country" "canada" } }, { "organisation uid" "fd88f3e6 2411 4eac a948 4b243d2a5f55", "first name" "lilly", "last name" "ilem", "job title" "nuclear power engineer", "company" "gigazoom", "email" "lilem2\@symantick com", "mobile" "+61491570006", "category" { "delegate" true, "vip" false, "after party" true }, "custom fields" { "dietary" "vegan", "opt in" "no", "business unit" "it", "primary interest" "networking", "phone" "503 927 2177", "country" "nigeria" } }] } updating company names { "event id" 23, "people" \[{ "organisation uid" "970457bc 783a 401c a1dd 0759fd23e287", "first name" "sherwin", "last name" "urien", "company" "ausbot pty ltd" }, { "organisation uid" "a6fd4204 912c 49e4 b274 a11f53f9c977", "first name" "larissa", "last name" "abbate", "company" "star link communitcations" }, { "organisation uid" "fd88f3e6 2411 4eac a948 4b243d2a5f55", "first name" "lilly", "last name" "ilem", "company" "gigazoomey" }] } changing category { "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 } }] } updating custom fields { "event id" 23, "people" \[{ "organisation uid" "970457bc 783a 401c a1dd 0759fd23e287", "first name" "sherwin", "last name" "urien", "custom fields" { "opt in" "yes", "business unit" "marketing", "primary interest" "other", "phone" "992 398 5321", "country" "australia" } }, { "organisation uid" "a6fd4204 912c 49e4 b274 a11f53f9c977", "first name" "larissa", "last name" "abbate", "custom fields" { "dietary" "#n/a", "opt in" "yes", "business unit" "marketing", "primary interest" "networking", "phone" "904 641 4763", "country" "canada" } }, { "organisation uid" "fd88f3e6 2411 4eac a948 4b243d2a5f55", "first name" "lilly", "last name" "ilem", "job title" "nuclear power engineer", "custom fields" { "dietary" "#n/a", "opt in" "no", "business unit" "it", "primary interest" "networking", "phone" "503 927 2177", "country" "spain" } }] } adding items { "event id" 1, "people" \[{ "organisation uid" "970457bc 783a 401c a1dd 0759fd23e287", "first name" "sherwin", "last name" "urien", "job title" "nurse", "company" "ozu", "email" "surien0\@etseety com", "mobile" "+61491570158", "categories" { "delegate" true, "vip" true, "after party" true }, "custom fields" { "opt in" "no", "business unit" "sales", "primary interest" "other", "phone" "992 398 5321", "country" "micronesia" }, 	 "items" \[{ 	 "id" "2", 	 "entitle" true 	 }, 	 { 	 "id" "3", 	 "entitle" true 	 } 	 ] 	}] } removing items { "event id" 1, "people" \[{ "organisation uid" "970457bc 783a 401c a1dd 0759fd23e287", "first name" "sherwin", "last name" "urien", "job title" "nurse", "company" "ozu", "email" "surien0\@etseety com", "mobile" "+61491570158", "categories" { "delegate" true, "vip" true, "after party" true }, "custom fields" { "opt in" "no", "business unit" "sales", "primary interest" "other", "phone" "992 398 5321", "country" "micronesia" }, 	 "items" \[{ 	 "id" "2", 	 "entitle" false 	 }, 	 { 	 "id" "3", 	 "entitle" true 	 } 	 ] 	}] } example results success (200) { "success"\ true, "data" { "import id" 494, "records processing" 3, "status" "pending" }, "included" \[] } validation failure (400) { "success" false, "message" "this is not a valid request", "error type" "validation error", "errors" "the people 0 email must be a valid email address " } configuration error (403) { "success"\ false, "error" "you must set a default category for this event before adding people, please login to jomablue on the web and set this under the event people are added to this category if a invalid or missing category is provided in the request " } 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"