Explore API

overview jomablue’s api belong to the rest category and allows you to perform ‘restful’ operations such as reading, modifying, adding or deleting data jomablue api’s are designed in accordance with json\ api v1 specification ( http //jsonapi org/ ) this document doesn’t cover all the structures of the api or the responses for the response format and how to navigate/link records via the api, please refer to json\ api specification methods used by jomablue command purpose post submitting data to the api get fetch one or more objects or resources rate limit the number of api calls is based on your plan enterprise customers have access to 3600 requests per hour (60 request per minute) if this rate is exceeded the api will return 429 rate limit exceeded until the requests fall below 60 requests a minute dates & times all date/times returned by the api are in gmt/utc format (no local time zones are applied) the timezone of the event can be found in the event attributes by calling api/v1/events/{event} this timezone can be applied to any time returned by the api to display local time of the interaction or event detail we utilise available php supported timezones (available here http //php net/manual/en/timezones php ) encoding for all requests url encoding (percent encoding) should be performed on the uri organisation uid (organisation uid) in certain endpoints, an organisaion uid is present this is generally an identifier from an external system (probably yours) for example, we might consider a session as session id 25, but in your marketing campaigns you might consider someone that attends that session a member of campaign 28199bba in this case, when exploring sessions you can see your identifiers represented as organisation uid please note we will need to learn of these identifiers beforehand to ensure we can load it to the right entities in jomablue otherwise this will return blank request headers as details in json\ api, the client must include the following headers for each request server will also respond with a matching header content type application/vnd api+json when accessing a protected resource, the client must send an authorization header using the bearer schema authorization bearer \<token> api url’s the general format for api requests is https //your organisation name jomablue com/api/api version/resource your organisaion name the organisation name as provided by jomablue api version the version of the api you are interacting with resource the resource you are interacting with a sample organisation named “acme” is used as an example throughout this document authentication before making any requests to protected resources, you must authenticate using an email address and password to obtain an access token credentials to access api resources differ from user credentials for portal access excessive failed attempts will result in throttling post https //acme jomablue com/api/v1/auth/login email required password required curl l x post "https //acme jomablue com/api/v1/auth/login" \\ h "content type application/vnd api+json" \\ d '{"email" "hello\@jomablue com", "password" "mypassword"}' example response { "token" "eyj0exaioijk izii6mtuzmdq5otmwncwianrpijoioffmz0nzulm1cgk3sdfiqsisi" } token validity token validity is customisable for high risk applications (please contact us), but has a default long lived setting of 20160 minutes at which point api requests will return 401 unauthorized the tokens expiry timestamp is encoded within the token if maintaining validity periods within your application is desired we highly recommend having an authentication workflow to request a new token if your current token becomes invalid and not simply rely on a manually obtained token and its lifetime jomablue reserves the right to revoke your token between feature releases if required the authentication endpoints will be immediately available so that you can obtain a fresh token an approach to narrow the possibility of token interception and misuse, is to call /destroy at completion of your api calls , this will blacklist your token and require re auth upon your next requests to protected resources destroy tokens can be destroyed by calling the following with a valid token in the authroization header authorization bearer \<token> post api/v1/auth/destroy tokens will be immediately invalidated and any future requests with this token will receive an 401 unauthorized error events an organisation can contain multiple events therefore ‘acme’ as the organisation can run acme convention 2020, acme small business seminar and acme con 2021 these three events are contained within the same organisation events have a name, start and finish date/time and contain people available endpoints get api/v1/events get api/v1/events/{event} get api/v1/events/{event}/relationships/{relationship name} get api/v1/events/{event}/person events get api/v1/events/{event}/person events/{person event} get api/v1/events/{event}/event categories get api/v1/events/{event}/event categories/{event category} people a person can be related to one or many events a single person record may contain different custom fields, categories or statues per event for example; john smith might belong to ‘delegate’ category for event 1 but ‘exhibitor’ category for event 2 people records contain 8 standard fields, these fields are field description organisation uid a customer provided id such as a crm id or similar that identifies a person record in jomablue to a person record in another system qr uid a jomablue system generated unique identifier (required) first name the persons first name (required) last name the persons last name (required) job title the person's job title company the persons company name email a formatted email address of the person (eg ) mobile a formatted mobile number, including country code prefixes (eg +61400111222) any data that does not fit into the above fields by definition are stored in jomablue as custom fields for example; “industry type” or “job role” will be stored as custom fields available endpoints get api/v1/people get api/v1/people/{person} get api/v1/people/{person}/relationships/{relationship name} get api/v1/people/{person}/person events get api/v1/people/{person}/person events/{person event} get api/v1/people/{person}/person event categories get api/v1/people/{person}/person event categories/{person event category} get api/v1/people/{person}/custom fields get api/v1/people/{person}/custom fields/{custom field} get api/v1/person events get api/v1/person events/{person event} get api/v1/person events/{person event}/relationships/{relationship name} get api/v1/person events/{person event}/event get api/v1/person events/{person event}/event/{event} get api/v1/person events/{person event}/person get api/v1/person events/{person event}/person/{person} get api/v1/person event categories get api/v1/person event categories/{person event category} get api/v1/person event categories/{person event category}/relationships/{relationship name} get api/v1/person event categories/{person event category}/event get api/v1/person event categories/{person event category}/event/{event} get api/v1/person event categories/{person event category}/category get api/v1/person event categories/{person event category}/category/{category} get api/v1/person event categories/{person event category}/person get api/v1/person event categories/{person event category}/person/{person} custom fields custom fields hold attributes of a person that don’t fit into the standard fields custom fields relate to a person and an event a person's custom fields are related to a specific event only and are not persistent across multiple events for example; a john smith person record might have a different custom field(s) for each event he is attending custom fields are described as ‘keys’ and ‘values’ for example; the key might be “job role” and the value might be “decision maker” available endpoints get api/v1/custom fields get api/v1/custom fields/{custom field} get api/v1/custom fields/{custom field}/relationships/{relationship name} get api/v1/custom fields/{custom field}/event get api/v1/custom fields/{custom field}/event/{event} get api/v1/custom fields/{custom field}/person get api/v1/custom fields/{custom field}/person/{person} categories categories are used to segment event related communications as well as defining an attendee’s onsite experience for example, people in the ‘delegate’ category might receive different branded emails to people in the ‘exhibitor’ category categories can be reused across multiple events, and a person can belong to one or many categories so john smith can be a “delegate” (category id 5) for event 1 but also be a “delegate” (category id 5) for event 2 available endpoints get api/v1/categories get api/v1/categories/{category} get api/v1/categories/{category}/relationships/{relationship name} get api/v1/categories/{category}/person event categories get api/v1/categories/{category}/person event categories/{person event category} get api/v1/categories/{category}/event categories get api/v1/categories/{category}/event categories/{event category} get api/v1/event categories get api/v1/event categories/{event category} get api/v1/event categories/{event category}/relationships/{relationship name} get api/v1/event categories/{event category}/event get api/v1/event categories/{event category}/event/{event} get api/v1/event categories/{event category}/category get api/v1/event categories/{event category}/category/{category} sessions an event can have none one or many sessions, every session is directly related to an event a session can’t belong to more than one event sessions can often happen concurrently and people can interaction with sessions in multiple ways generally speaking, the most common way to interact is by checking into the session (entry) other interactions include, exiting (when a person left the session) requesting related content (tapping their badge on a device to indicate they want more information about that session), or rating the session using the mobile app information about the sessions including start and end time, description and organisation uid can be found using these endpoints a person's interactions with sessions can also be explored using the following endpoints available endpoints get api/v1/sessions get api/v1/sessions/{session} get api/v1/interaction person sessions get api/v1/interaction person sessions/{interaction person session id} example request to get sessions with a valid authorization token curl request get \\ url https //acme jomablue com//api/v1/sessions \\ header ‘accept application/vnd api+json’ header 'authorization bearer eyj0exaioijkv1qilcjhbgcioijiuzi1nij9 eyjpc3mioijodhrwczovl2rvbw8uam9tywjsdwuuy29tly9wb3j0ywwvyxbpl2xvz2l2f1dggixasdaqiojjia51ding5evhzpiiwic3viijoyniwichj2ijoioduuahdasdasdajvlasdjh771ahiiahasdasdafasdifaajsjdi organisation uid as described earlier, the organisation uid is an identifier from another system it has no meaning within jomablue and is designed to maintain campaign codes or other attributes that is meaningful to your existing systems this is optionally provided to jomablue when configuring the sessions at an event restricted sessions a restricted session indicates that a person will only be granted entry to a session if they are entitled to attend currently there is no way to retrieve a list of people registered for a session, this is handled in jomablue if a person that is not entitled to attend a session, and the sesion is restricted, the person will be presented with a red error at the session door and no interaction records created in jomablue if a person is entitled to attend, and the person enters the session, the person will receive and entry interaction the exception to this, is if session override is enabled this allows the door usher to override the denied entry a person receives if they are not entitled if a person is permitted entry at the discretion of the door usher, and enters they will receive two interactions an entry and a override entry this is to allow counting of attendance (entry) and counting of override entries (override entry) independently duplicates duplicate session interactions are included, for all interaction types in an example; a person may have more than one entry interaction with a session a common, real world scenario is someone leaves the session mid way through for a bathroom break before returning to the session calculating time spent if you want to calculate the amount of time someone spent in a session, this can be achieved by calculating the time between the entry interaction and the subsequent exit interaction noting that it is possible to have only an entry or only an exit interaction reminder all timestamps are stored in utc/gmt, the local timezone can be found by calling the event apis restricted vs unrestricted logic non restricted session restricted session override enabled entitled to attend entry granted entry granted entry granted no entitlement entry granted entry refused entry granted the interaction types are as follows interaction description entry a person has entered a session room the session may or may not have been restricted override entry recording the fact a person was allowed entry using override the person will have a sequential interaction as ‘enty’ exit a person has left the session room, irrespective of when the session ends related content requested a person has tapped their badge on a jomablue device in the session room indicating they are interested in more related content related content sent we have successfully sent the content to the person requesting it (via app push, email or sms) rating a value of 1 through 5 will be returned, indicating 1 5 star rating of the session submitted via the event app comment a free text value will be returned, this is a comment left by the attendee as a rating free text comments are submitted via the event app related content more information the content is subjective to the event and the session it could be presentation slides or similar if a person has only ‘related content requested’ interaction, it indicates we were unable to send the content to them, most likely because we didn’t have their email or phone number or it was poorly formatted filtering filtering can be used to refine the results returned by the api only results that match the filters will be returned supported filters nfc uid the unique identifier inside a jomablue smart badge email an email address associated with a person record encoding all uri’s should be url encoded for example hello\@jomablue com should be hello%40jomablue com /api/v1/people?filter\[nfc uid]\[]=1122334455 should be /api/v1/people?filter%5bnfc uid%5d%5b%5d=1122334455 results returned providing the request is structured correctly a http 200 response is returned with no matter if the filter matches any data if there were records in jomablue that match the provided filter, they are returned in “data” \[] within the body if there are no records in jomablue that match the filter provided, you will find the “data” \[] empty arrays a filter array can be used to find multiple records in one api call the array is constructed in the following form using the nfc uid as an example (please note the additional square brackets after the \[attribute] ) /api/v1/people?filter\[nfc uid]\[]=1122334455\&filter\[nfc uid]\[]=66778899 /api/v1/people?filter\[nfc uid]\[]=1122334455\&filter\[email]\[]=hello\@jomablue com multiple filters filters can be grouped to refine the results further for example you could filter on people records that match an email and a nfc uid please be mindful that adding multiple filters of different type (eg email and nfc uid) result in and logic (not or) additional information filtering by nfc uid the nfc uid is the nxp ntag216 7 byte serial number within the tag this is a manufacturer set data and is locked within the first 9 bytes of the tag refer to the manufacturer documentation https //www nxp com/docs/en/data sheet/ntag213 215 216 pdf for specifics filtering by nfc uid is constructed in the following form get /api/v1/people?filter\[nfc uid]=1122334455 get /api/v1/people?filter\[nfc uid]\[]=1122334455\&filter\[nfc uid]\[]=8899889922 where 1122334455 and 8899889922 is the nfc uid of a jomablue smart badge records matching the nfc uid will be returned important nfc uid should not contain any formatting, they should be represented as a set of numbers only (no colons) nfc uid’s are globally unique example nfc uids 040a5b32dd6081 0448e66a605d81 040a4e32dd6081 additional information filtering by email it is important to understand emails are not unique nor does jomablue validate for email uniqueness therefore an email address may not exist, exist once or many times if the filter is used to filter people's endpoints by email address, all the matching person records with that email address will be returned filtering by email is constructed in the following form get /api/v1/people?filter\[email]=hello\@jomablue com get /api/v1/people?filter\[email]\[]=hello\@jomablue com\&filter\[email]\[]=hi\@jomablue com where and is the email address associated with the jomablue person record all records matching the provided email address will be returned important email addresses are formatted on entry into jomablue and can generally be considered as well formatted a person's record may not contain an email address it’s not a required field quick start get all events curl request get \\ url https //acme jomablue com/api/v1/events \\ header 'authorization bearer eyj0exaioijkaafcjhbgcioijiu ' \\ header 'content type application/json' show me all people for event id 2 curl request get \\ url 'https //acme jomablue com/api/v1/events/2/person events?include=person' \\ header 'authorization bearer eyj0exaioijkaafcjhbgcioijiu ' \\ header 'content type application/json' get info specific data about a session curl request get \\ url https //acme jomablue com/api/v1/sessions/5 \\ header 'authorization bearer eyj0exaioijkaafcjhbgcioijiu ' \\ header 'content type application/json' filter results by email address curl request get \\ url 'https //acme jomablue com/api/v1/people?filter%5bemail%5d%5b%5d=hello%40jomablue com' \\ header 'authorization bearer eyj0exaioijkaafcjhbgcioijiu ' \\ header 'content type application/json'