---
title: Bulk Import API
slug: docs/bulk-import-api
createdAt: 2025-01-16T01:27:37.907Z
---

## Introduction

Jomablue’s Bulk Import API is designed for external systems to add people records to Jomablue. People records are entities that attend events or experiences hosted in-person, hybrid or virtually on Jomablue.  People can be created or updated in Bulk via a REST POST request using a valid Bearer token. 



## Rate Limit

The number of API calls is based on your Jomablue plan. A soft default is 5 requests per minute and 250 person records per request (ie. 1500 people records per minute). If this rate is exceeded the API will return 429 - Rate Limit Exceeded until the requests fall below 6 requests a minute. We recommend having a minimum of 10 second wait between pushing batch requests of records to Jomablue to stay within these limits.&#x20;

:::hint{type="info"}
There is a rate limit of 6 requests per minute due to this being a bulk insert API (as opposed to single record inserts). This still allows you to achieve around 1500 people per minute.&#x20;
:::



## Dates & Times

All date/times returned in our API's are in UTC format (no timezone offsets are applied). Noting that some endpoints do not return timestamps.

## Encoding

For all requests URL encoding (percent encoding) should be performed on the URI.

## Organisation UID (organisation\_uid)

The Organisation UID is a unique identifier of a person from an external system (eg: CRM’s). For example, if you have a person record in your *Salesforce CRM* that has indicated they are attending a Jomablue event, the Jomablue Organisation UID would be the Salesforce Lead/Contact ID.&#x20;

This allows your systems to keep track of people between systems as well as perform subsequent updates to particular people. 

Organisation UID’s are expected to be globally unique and therefore a single Organisation UID may denote a person that has a relationship to multiple events in Jomablue. Making updates to a person that is attending multiple Jomablue events will update the persons details (first\_name, last\_name, job\_title, company, mobile and email) for all events. Noting that categories and custom fields are event specific.&#x20;



## Request Headers

The client must include the following headers for each request.

:::BlockQuote
Content-Type: application/json
Accept: application/json
:::

When accessing a protected resource, the client must send an Authorization header using the Bearer schema.

:::BlockQuote
Authorization: Bearer &#x7B;token}
:::



## API URL’s

The general format for API requests is:

[https://your\_organisation\_name.jomablue.com/import/api/v1/resource](https://your_organisation_name.jomablue.com/import/api/v1/resource)

**Your\_organisaion\_name:&#x20;**&#x54;he Organisation name as provided by Jomablue
**Api\_version:&#x20;**&#x54;he 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.



## Whitelisting

To ensure our application or network firewalls don't misdiagnose your legitimate traffic, we ask for source IP's or identifying headers from your application to allow us to whitelist your traffic and prevent an interruption of service.&#x20;

Alternatively, we can provide you with custom HTTP request header values to include in your requests.&#x20;



