EventMobi's Unified API is a comprehensive offering of all of EventMobi's public platform functionality.

If you have any questions or concerns please reach out to api@eventmobi.com.

---

Breaking changes from the beta version of UAPI are indicated below:

• Id Filters
  • List of Ids filter should be singular (id instead ids).
    Ex:https://uapi.eventmobi.com/events/41993/people?id=5df01d7c-8c2d-49a6-957f-87429f72d0cf,0341aea3-6930-49bd-87b6-7cc3fffab592
  • Impacts: All endpoints that accepts id as a filter (id, external_id, group_id, people_id, etc.)
• Location
  • Location has Map Location information on its Response Body
    • Impacts: Companies Location
• Includes
  • GET by ID endpoints now require includes to return nested information similar to collection endpoints.
    
    • Impacts: People and Companies
      Ex: https://uapi.eventmobi.com/events/41993/people/5df01d7c-8c2d-49a6-957f-87429f72d0cf?include=session_roles
• Images
  • Images attached to other entities are now set and returned within their own nested object instead of through image_id
• Webhooks
  • Webhooks are now versioned based on the API version they were created under
  • Schedule changes will no longer trigger the people webhook type, instead they have their own schedule type

To access the API, you'll need an API Key. Each key is associated with an Organizer and has the same access rights as that person does within the Organization the key was generated for. API Keys cannot be used accross multiple Organizations, even if the owner of the key exists in multiple.

API Keys can be generated and managed from Experience Manager. From the Organizations drop-down on the top-left of the screen, select Integrations. On the API Keys tab you will have the option to generate a new key for an Organizer within your Organization. You can also disable, delete, or regenerate existing keys.

Once you have your API Key, you can use it access endpoints for your Organization or Events within your Organization. The key must be included in every request in the Authorization Header.

Example: Authorization: Bearer YOUR_API_KEY_HERE

Providing the version number is mandatory when making calls to the API. Use the Accept header to specify the version.

Example: Accept: application/vnd.eventmobi+json; version=3

Rate Limits

Currently no hard rate limiting is in place, however excessive and inefficient use of the API will be monitored and may result in a warning or in extreme cases to the API key being disabled or removed.

Request Limits

The request line should not exceed 8k characters, doing so will result in a 414 Request-URI Too Large response. This situation is primarily applicable when applying a large number of csv values to filter by.

Some common rules regarding character data processing include:

• Generally each string in the input must not include any control characters except \t, \n, \r.
• In most cases HTML sanitization is not performed, it is the responsibility of the client to make sure that the data is not interpreted when it is not desired.

Custom formats

• id-string strings represent various IDs generated by EventMobi systems. The specific format is not guarenteed and may be changed without warning. For instance the format may be all numbers, or may be a UUID, but in all cases these ids should be treated as strings. All IDs are guaranteed to contain no more than 256 printable ASCII chars.
• printable-stripped-unicode-string strings can contain unicode characters, the whitespace characters are stripped from the beginning and the end of the string before further processing.
• external-id strings represent a settable id, useful for mapping ids from an external system to EventMobi resources. Resources can be retrieved by their external_id, and in some cases data relationships can be established based on external_id.
• csv-string string supports multiple values separated by a ,.

Error reporting is provided as a part of response envelope. There is an array in errors property which contains a list of objects describing errors. Error object is explained in detail as a part of response schema for each endpoint. We follow a few principles in error reporting:

• Error code is human- and machine-readable, snake-case string. Error code is unique per error type. The client does not have to consult other parts of error response to get the type of the error.
• Single error object can represent a generalized error, especially when the error is related to validation. In this case the error is related to single input element. The code can also represent a specific business error when it makes sense.
• The response HTTP status code is guaranteed to have non-2xx value if there was an error handling the request. In that case, if the response Content Type is valid, error details are provided as described above. Note that there is a chance that the response comes directly from intermediate system (for example, load balancer), in which case it won't contain proper Content Type header and response contents will be different.
• Error codes returned from application correspond to different HTTP status codes. 400 corresponds to any error which is related to the request itself (for example, validation error, or any business logic error). We use 401 and 403 for authentication and authorization errors. 404 is used only for not found URLs. 406 is used for content negotiation. 500 represents any other error.

Some endpoints might accept/return some Properties depending on the authorization of the caller - this Properties will have a x-authorization definition within its description.

The x-authorization defines what are the authorization required to read/write the given property. It can define a one or many authorizations, separated by comma, eg: x-authorization: "event_organizer"

The possible authorization levels are:

• event_organizer: authenticated user is an event organizer for the related event;
• resource_owner: authenticated user is the explicit owner of the resource, such as an event attendee retrieving their own profile

Includes allow for optional nested relational data to be returned when reading resources. This can be useful to customize the resource representation for a particular usecase. It is important not to abuse includes by including excessive amounts or unnecessary information. Such abuse may result in a temporary or permanent ban on using EventMobi's API. Please be especially conscious of using minimal includes when retriving large collections of entities.

Includes are identified with the x-include definition on its description, indicating which include value to use to retrieve it.

Most endpoints that return lists of objects support pagination and sorting.

Pagination

Parameters:

• page: Specifies the page index. Starts from 0.
• limit: | Specifies the maximum number of items per page (page size). The maximum limit, unless stated otherwise, is 1000.

Sorting

Unless otherwise stated by default results are sorted by created_at. Sorting will be done in ascending order by default. To sort in descending order, a minus sign (-) should be added to the beginning of the sorting parameter. Example: sort: '-name'

Parameters:

• sort: List of fields to sort the query by, separated by comma.

Response Metadata:

When an endpoint returns paginated data, metadata will be returned within the response, containing the current page, returned record count and total record count.

• limit: Limit of items per page.
• page: Current page index.
• page_items_count: Amount of items returned in current page.
• total_items_count: Total amount of items in the query.
• sort: Fields used to sort items.

Some endpoints support searching, or filtering by specific fields.

Searching

Endpoints that support search will have a specific set of fields that are used for searching. The fields used for searching are documented per endpoint. Currently only non-fuzzy searches are supported.

Parameters:

• search: Search term to use.

Filtering

Filters are passed in, and documented as query parameters.

Use a comma to pass in multiple filter values. Example: ?group_ids=id1,id2. Records matching any of the values will be returned.

Meta data for files is handled separately from the actual data stream. Use the images endpoints to create images in the system before referencing them in other requests.

To upload an image the following steps have to be taken:

• POST Request to the images endpoint /events/{event_id}/images
• The call returns a temporary upload URL specific to this image. Upload your image to this URL using a PUT call. Make sure to include the Content-Type header and set it to the same type specified in the image metadata.
• When the upload is complete you must finalize the image upload by making a PATCH call to update the image through the image endpoint using the id returned by the original POST request (for example /events/{event_id}/images/{image_id}). The status field must be set to 'finalized' in the request body. If an uploaded image is not finalized with 24 hours, it will be deleted.

The following is a sample block of code in python to create and upload an image to an event, and then associate it to a newly created company.

import requests

IMG_URL = 'https://uapi.eventmobi.com/events/{event_id}/images'
IMG_DETAIL_URL = 'https://uapi.eventmobi.com/events/{event_id}/images/{image_id}'
COMPANY_URL = 'https://uapi.eventmobi.com/events/{event_id}/companies'

headers = {
    'Accept': "application/vnd.eventmobi+json; version=3",
    'Authorization': "Bearer {api_key}",
}

# Read Local Image Bytes
IMG_LOCATION = 'IMG_20191114_135203.jpg'
with open(IMG_LOCATION, 'rb') as f:
    image_bytes = f.read()

# Create Company Image Metadata in EventMobi
image_response = requests.post(
    IMG_URL,
    headers=headers,
    json={
        'name': 'mycompanyimage',
        'mime_type': 'image/jpeg',
        'length': len(image_bytes)
    },
).json()
upload_url = image_response['data']['upload']['url']
image_id = image_response['data']['id']

# Upload Image bytes to Upload URL
upload_response = requests.put(
    upload_url,
    data=image_bytes,
    headers={
        'content-type': 'image/jpeg'
    }
)
assert upload_response.status_code == 200

# Finalize the Image in EventMobi
image_finalize_response = requests.patch(
    url=IMG_DETAIL_URL.format(image_id=image_id),
    headers=headers,
    json={
        'status': 'finalized'
    }
)
assert image_finalize_response.status_code == 200

# Create a Company with the image
company_response = requests.post(
    COMPANY_URL,
    headers=headers,
    json={
        'name': 'SuperMegaCorp',
        'image_id': image_id,
    },
).json()

The Image entities returned from the Image endpoint contain a URL to the image's file. The image that this URL represents can be the original one or it can be manipulated and transformed according to querystring parameters. Also, when creating a new image, a predefined crop, based on coordinates, can be set to be used by the system before resizing.

If scale_width and scale_height are not defined, fit_in, smart_crop and fill_color will be ignored.

If fit_in is false, fill_color will be ignored. If fit_in is true, smart_crop will be ignored.

user_crop

Determines if the image will be cropped using the user's predefined coordinates before resizing to scale dimensions. Default true.

scale_width and scale_height

Defines the image's size when returned.

smart_crop

Determines if the image will be automatically cropped using smart face detection. Ignored if fit_in is true.

fit_in

Defines the resizing strategy. It is turned on by default when scale_width and scale_height are defined.

• When it is turned off, the image will be auto-resized and auto-cropped to have the exact size defined by scale_width and scale_height, but it won't stretch.
  • If the image is smaller than the requested size, it will be first scaled up so that the whole area defined by scale_width and scale_height is filled and then, if its aspect ratio is different than the requested, it will be cropped from the center.
  • If the image is bigger than the requested size, it will be first scaled down so that the whole area defined by scale_width and scale_height is filled and then, if its aspect ratio is different than the requested, it will be cropped from the center.
• When it is turned on, the image will be resized to fit in the imaginary box defined by scale_height and scale_width without changing its aspect ratio. If the image's aspect ratio is different than the requested, the 'fill_color' parameter can be used to determine a color to fill in the missing area on the imaginary box defined by scale_height and scale_width size. If fill_color is not used the image will be returned with its original aspect ratio (one of the sides will be smaller than the requested size).

fill_color

Defines the color that will be used to fill in any missing areas on a image resized with fit_in.

There are several different ways to manipulate an image when making a request to the images endpoint. These examples will hopefully make it easy to understand how they work.

Original Image 1

For the examples, we are going to consider that this image was created with predefined crop coordinates of top: 100px, left: 100px, width: 300px, height: 300px.

Original Image 2

For the examples, we are going to consider that this image was created with no user crop.

Retrieving the original image

scale_width	(not present)
scale_height	(not present)
user_crop	false
smart_crop	ignored
fit_in	ignored
fill_color	ignored

Retrieving with predefined crop

The image can be retrieved with the crop defined during creation. If no crop was specified, the original image will be returned.

scale_width	(not present)
scale_height	(not present)
user_crop	true
smart_crop	ignored
fit_in	ignored
fill_color	ignored

Resizing the image

An image can be resized by specifying both scale_width and scale_height. Other parameters such as fit_in, smart_crop and fill_color can be used combined with scale_width and scale_height to determine how the image will be resized.

Resizing without fitting in

When fit in is not enabled, the image will be resized so that one of its dimensions matches the requested size.

Different aspect ratio than the original image

In this example, the image's height will be reduced from 360 to 300, making its width decrease from 640 to 533. However, 533 is still larger than the 300 pixels requested scale width, so the image will have its extremities cropped out, half of the excedent size will be taken from the left side, and half from the right side.

scale_width	300
scale_height	300
user_crop	false
smart_crop	false
fit_in	false
fill_color	ignored

Same aspect ratio as the original image

When fit in is not enabled, if the requested dimensions have the same aspect ratio as the original image, the image will just be scaled up or down.

scale_width	800
scale_height	450
user_crop	false
smart_crop	false
fit_in	false
fill_color	ignored

Face Detection

Face detection will be used when the image is requested with smart_crop parameter set to true and fit_in set to false.

scale_width	200
scale_height	200
user_crop	false
smart_crop	true
fit_in	false
fill_color	ignored

Resizing and fitting in

When fit in is enabled, the image will be resized so that it fits inside the area defined by scale_width x scale_height. If the image's area is bigger than the requested area, it will be scaled down, however, if the image is smaller than the requested area, it won't be scaled up, as it is considered that it already fits in the requested area, fit_in makes the image keep its aspect ratio.

fill_color can be used to fill in with a solid color any difference between the requested area and the image's area.

Different aspect ratio than the original image

In this example, the image's width will be reduced from 640 to 300, making its height decrease from 360 to 169. The returned image's size will be 300 X 169.

scale_width	300
scale_height	300
user_crop	false
smart_crop	false
fit_in	true
fill_color	not present

Using fill_color

scale_width	300
scale_height	300
user_crop	false
smart_crop	false
fit_in	true
fill_color	#FFC0CB

Fit in doesn't scale up

scale_width	700
scale_height	400
user_crop	false
smart_crop	false
fit_in	true
fill_color	#FFC0CB

Cropping before resizing

The user_crop parameter determines if the image should be cropped using the predefined coordinates before being resized. When user crop is used, the cropping will be done as a first step before resizing, so the same resizing rules shown above will be applied to the image after it was cropped using the predefined coordinates.

Another option is the 'pre_crop' parameter, which receives four comma separated numeric values representing coordinates to the top left and bottom right points that define the area of the image that should be cropped. For example, pre_crop=100,100,300,300 would mean that we want to crop the image from the point (100,100) to the point (300,300) in pixels. If 'pre_crop' is passed, user_crop will be ignored.

Resizing with the same aspect ratio without fit in

Apply user crop on Example 1 and resize it to 400 X 400

scale_width	400
scale_height	400
user_crop	true
smart_crop	false
fit_in	false
fill_color	ignored

Resizing with the same aspect ratio with fit in and fill color

scale_width	400
scale_height	400
user_crop	true
smart_crop	false
fit_in	true
fill_color	#FFC0CB

Webhooks allow you to be notified by our system when changes are made to certain types of data. You register a webhook with a callback URL and resource type, for a specific event. When changes are made to data with that type in the event your callback URL will be called.

Currently supported resource types

• people
• people_groups
• companies
• company_groups
• sessions
• tracks
• session_roles
• schedule - Webhook triggers per person when one or more of their scheduled sessions is changed. The resource_ids in this context are people_ids who have had their schedule modified.

Note that For entities like company_groups or people_groups we do not trigger webhooks for all of the entities under those groups. Example: a change to a people group, that is assigned to 10 people, will only trigger one people_groups webhook and no people webhooks.

Payload

When our system calls your callback URL the following payload will be provided:

Field	Description
operation	The operation that was done on the resources ("create", "update", or "delete")
resource_ids	List of IDs for all of the resources that were created/modified or deleted
event_id	Event ID
type	Resource type
change_request_origin	Value of X-Request-Origin header of the API call that triggered the data change
change_datetime	The datetime the change occured in UTC, formatted as an ISO formatted string

An Example payload may look like this:

{
  "operation": "update",
  "resource_ids": ["c408e457-7ebe-4b06-abd8-69a7c4fd3225", "93fda6bf-319b-44ad-ad14-359549855497"],
  "event_id": 1234,
  "type": "people"
  "change_request_origin": "integration_partner",
  "change_datetime": "2020-02-18T19:56:11.305246+00:00"
}

Usage Notes

The payload of a webhook may include one or many resource_ids (always in a list), depending on how my resources were created, updated, or deleted by a change.

The system will generally group all changed resources of a given type changed by one operation into one webhook payload with multiple resource_ids, however if a large number of resources were changed at once this may be split into multiple webhook payloads instead.

For the update operation, the webhook payload does not indicate which fields were modified. It is up to the integrated system to resync the data it cares about.

Preventing Circular Webhook Requests

There may be situations where you want to subscribe to webhooks for a resource type that your system also updates. In this scenario you need to be cautious not to create an infinite loop of updates (Your system makes a change to EventMobi, which fires a webhook back to your system, which sees the change and triggers another sync to EventMobi, etc.).

It is advised in this situation to prevent EventMobi from sending you webhooks triggered from your own changes. To do this, include the X-Request-Origin on each API request to EventMobi with a value unique to your integration, such as your company name. Then when you create a webhook set the request_origin field to the same value as you use in the X-Request-Origin header. When these two values match, the webhook will not send, preventing you from being notified of the changes you originated.

Errors

Failed calls to webhooks are retried by our system at a later time. A call is considered to have failed if the response code is something other than 200, 201 or 410. For the same call, each subsequent retry will be called with an increased delay.

If the same call to a webhook fails on the fifth retry, the webhook will be disabled. To re-enable the webhook, make a PATCH call to the webhooks endpoint (/events/{event_id}/webhooks/{webhook_id}) and set enabled to true.

When the system receives a 410 (gone) status code the webhook will be deleted. This can be used to automatically remove webhooks that are no longer needed.

Versioning

Webhooks are versioned like the rest of the API in order to prevent breaking changes. A webhook will automatically be given the version of the API request used to create it. A webhook's trigger mechanism and payload will remain consistent for it's version. A webhooks version can be updated, or the webhook can be removed and recreated under a new version when it's time to uprgade.

Managing webhooks

To create/register or delete webhooks please see the 'Webhooks' section for information on the specific endpoints.