Welcome to the Integrate Events public API documentation. Here you can find out how to build customised applications and share your event lead data with Integrate Events.

Our API

Designed and built using REST principles - if you have experience working with APIs, then the decisions we’ve made here should be familiar. API responses (and in some instances, requests) are in JSON.

Generate your Client Credentials in the Integrate Events dashboard

You’ll need to get your unique Client Credentials from the Integrate Events dashboard; you can do this by logging in and navigating to Settings > API. Your client credentials are used to retrieve an access token from the API, which is used to authorise each request. For more information on this, including step-by-step instructions, see Help Centre article: Using the Integrate Events public API

Need technical help?

Direct questions to our Support team, [email protected].

Cross-Origin Resource Sharing (CORS) is enabled for the API, which allows for XHR requests to be processed. This can be acheieved by sending an OPTIONS preflight request, to which the server will respond with the following headers:

• Access-Control-Allow-Origin
• Access-Control-Allow-Headers
• Access-Control-Allow-Methods

To read more about Cross-Origin Resource Sharing, read a detailed explanation by Mozilla

Add filters to your API requests to determine the query outcome. The filter query string must:

• contain the parameter filters[]
• be an array - because it’s possible to supply multiple filter conditions
• be url encoded

Build your filter parameters in the following format:
{logic}-{field}-{operator}-{value}

Logic

The valid values for logic are and and or. These are used to split the filters[] array into groups of filters based on the position on the position of the logic value or. This allows more complex queries to be constructed specifying multiple groups of conditions.

Example:
?filters[]=and-event.name-like-%Data%20Capture%20Event%
&filters[]=and-event.type-eq-1
&filters[]=or-event.name-like-%Guest%20List%20Event%
&filters[]=and-event.type-eq-2

This could be represented as the following SQL query:

Field

The field name to be queried in the condition. You can check what fields are available to query on each collection endpoint schema.

Operator

Valid operators include:

• eq: Equals to
• neq: Not equals to
• lt: Less than
• lte: Less than or equals to
• gt: Greater than
• gte: Greater than or equals to
• like: Like

Value

This is the value for which the query is searching. This will be smartly parsed while the filter string is being transformed to convert the type to int, float and null.

To sort the the results returned by a collection endpoint, the request should:

• contain the query string parameter sorts[]
• be an array as it is possible to supply multiple sort conditions

Build your sort parameter with the following format:
{field}-{direction}

Below is an example of sorting events in ascending order by the endDate and then by name:
/v2/events/{eventID}?sorts[]=event.endDate-asc&sorts[]=event.name-asc

Field

The field name the collection will be sorted by. You can check what fields you can use to sort a collection on each endpoint schema.

Direction

Define how the results should be ordered using one of the following:

• asc: Ascending
• desc: Descending

The results returned from a collection endpoint will be paginated by default with the maximum number of results set to 50. This value can be changed by specifying the query parameter per_page or limit. The maximum value that can be specified is 200.

The header Link will be returned with the response following the format specified in RFC5988.

Example:
</v2/events?per_page=50&page=1>; rel="self",
</v2/events?per_page=50&page=2>; rel="next",
</v2/events?per_page=50&page=3>; rel="last"

The available pagination query parameters are:

• per_page - The number of results per page
• page - The page number to fetch the results for

Includes allows related data to be included in the response from the server. For example, when querying Records, the Resources are not included in the response by default. To include the resources, supply the query parameter include (use comma separators to define multiple includes).

Here is an example query string, which would retrieve an event, plus template and records:
/v2/events/{eventID}?include=template,records

Integrate Events formats dates according to RFC3339 (HTTP-date)

Integrate Events domains only support requests using encryption with TLS 1.2 or greater. Any requests using TLS versions less than 1.2 will be blocked. Unsecured connections are not allowed, and are redirected to HTTPS (port 443). We also send a HTTP Strict Transport Security header to help protect against Man-In-The-Middle attacks.

We want to ensure all customers have the best possible experience using our API. The number of API requests that customers make is therefore logged, and if deemed to be excessive, we may impose limits to usage. For more information, you can request access to our Fair Usage Policy.

In order to provide Enterprise level security and other authentication related features we leverage Auth0 as an authentication provider across the entire Integrate platform, including the Integrate Events API.

The API endpoints require requests to contain an access token with the Authorization header. This is a relatively straightforward process; use the API Secret Key and Client ID (generated in your account dashboard - Settings > API) to perform a POST to the authorization endpoint. This will return your access (bearer) token on success.

You should then store the access (bearer) token in your application until it expires; it will be used in every subsequent API request for authorization.

Events consist of defined questions and expected data responses. They also contain a collection of records.

Event Type

The type of event is indicated by an integer value for the property type. There are two types of events:

1. Data Capture

An event type used for capturing and editing records through forms built using the event template.

2. Check-in

This event type is primarily used to track attendance at an event, by storing an “attended” state on each visitor or guest’s record. The event usually contains a list pre-populated records (uploaded, pre-registered, or partially complete records) that were added prior to the event start date. These records can be queried and updated to indicate whether somebody attended an event. This event type also supports the creation of new records (for example, walk-ins).

List of Available Event Types

Please note, the following Event Type IDs have been deprecated as of API v2 and are no longer supported:

It’s no longer possible to create events with the deprecated IDs. Any existing events using the event types 2, 3 and 4 should be treated as event type 5.

Event Status

The status of an event is indicated by the property status and may be filtered when requesting a list of events. The value of status may be one of the following:

Event Template

An event template defines the attributes of an event form. To see an example of how an event template is structured go to the event response schema and expand the template property.

Event templates also include an array of questions that are answered by a user. In this documentation, event questions are referred to as fields.

Common structure of a field

Every field must contain an ID and type (while some fields require additional specific parameters). Common parameters are defined below.

{
  "required": "This field is required"
}

Field Types

This section describes what type of form fields should be displayed by the client and how they should behave.

{
  id: "firstName",
  type: "text",
  label: "Full name",
  required: true,
  autoCapitalize: "words",
  placeholder: "string",
  autoCorrect: "off",
  subtype: "multiline",
  ...
}

{
  id: "emailAddress",
  type: "email",
  label: "Email address",
  required: true,
  placeholder: "e.g [email protected]",
  autoCorrect: "off",
  autoCapitalize: "none",
  ...
}

{
  id: "priority",
  type: "number",
  label: "Priority",
  minVal: 1,
  maxVal: 10,
  ...
}

{
  id: "telephoneNumber",
  type: "tel",
  label: "Telephone Number",
  ...
}

{
  id: "websiteURL",
  type: "url",
  label: "Website URL",
  placeholder: "e.g www.integrate-events.com",
  ...
}

{
  id: "country",
  type: "autocomplete",
  label: "Country",
  placeholder: "string",
  limit: 10,
  selectedQuantity: 1,
  allowNewEntries: true,
  options: [
    'United Kingdom',
    'United States of America'
  ],
  ...
}

{
  id: "dateOfBirth",
  type: "date",
  label: "Date of birth",
  subtype: "date",
  startRange: "1561935600",
  endRange: "1564613999"
  ...
}

{
  id: "information",
  type: "label",
  label: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  ...
}

{
  id: "moreInformation",
  type: "checkbox",
  label: "Would you like to receive more information?",
  initialVal: true,
  ...
}

{
  id: "productInterest",
  type: "checkboxGroup",
  label: "string",
  options: [
    "Product 1",
    "Product 2",
    "Product 3"
  ],
  ...
}

{
  id: "title",
  type: "select",
  label: "string",
  addEmpty: true,
  multiSelect: true,
  options: [
    "Mr",
    "Mrs",
    "Miss",
    "Ms",
    "Dr",
    "Professor"
  ],
  ...
}

{
  id: "gender",
  type: "radio",
  label: "string",
  options: [
    "Male",
    "Female",
    "Not specified"
  ],
  ...
}

{
  type: "rating",
  id: "string",
  label: "Rating",
  maxRating: 5,
  ...
}

{
  id: "moreInformation",
  type: "linkbuilder",
  label: "Select products to send more information about",
  links: [
    {
      label: 'Product 1',
      url: 'http://link.to/product-1-brochure.pdf'
    },
    {
      label: 'Product 2',
      url: 'http://link.to/product-2-brochure.pdf'
    }
  ],
  ...
}

{
  id: "photo",
  type: "cameraPhoto",
  label: "Take a picture",
  ...
}

{
  id: "businessCardScan",
  type: "businessCard",
  label: "Scan a business card",
  ...
}

{
  id: "badgeScan",
  type: "barcodeScanner",
  label: "Scan a badge",
  ...
}

Display logic

Logic works by defining expressions for displayed fields. Logic expressions work like MongoDB queries on the values already entered into the form.

Any questions that are set as not displayed, are not considered required by the form validation.

{
  ...,
  displayed: {
    OTHER_FIELD_ID: {
      "$OPERATOR": "VALUE"
    },
    ...
  },
  ...
}

{
  OTHER_FIELD_ID: {
      "$displayed": "boolean"
    }
}

{
  OTHER_FIELD_ID: {
      "$eq": "any"
    }
}

{
  OTHER_FIELD_ID: "any"
}

{
  OTHER_FIELD_ID: {
      "$ne": "any"
    }
}

{
  OTHER_FIELD_ID: {
      "$in": ["any"]
    }
}

{
  OTHER_FIELD_ID: {
      "$nin": ["any"]
    }
}

{
  OTHER_FIELD_ID: {
      "$and": [
        {
          OTHER_FIELD_ID: {
            "$OPERATOR": "value"
          }
        },
        {
          OTHER_FIELD_ID: {
            "$OPERATOR": "value"
          }
        },
        ...
      ]
    }
}

{
  OTHER_FIELD_ID: {
      "$or": [
        {
          OTHER_FIELD_ID: {
            "$OPERATOR": "value"
          }
        },
        {
          OTHER_FIELD_ID: {
            "$OPERATOR": "value"
          }
        },
        ...
      ]
    }
}

Available Includes

The availble includes are:

• records - records captured for the event
• resources - resources associated with the event
• template - event template containing the form questions
• recordsLastModified - datetime representing the last time a record was modified for the event

For more information see the includes explanation

A record consists of a collection of data from an individual. It includes:

• the time the data was collected
• responses to questions, comments and starring
• who collected the data
• plus more

Values

The answers to questions defined for an event are stored in the record’s values object, which needs to be structured in the following format:

• The property names for the values object must be match the field ID's defined in the event template
• The value for each property must be an object (value object)
• The value object must contain the property value

Below are example values for each field type:

    
{
  "values" : {
    // Full Name
    "fullName": {
      "value": "John Doe"
    },
    // Email
    "email": {
      "value": "[email protected]"
    },
    // Phone Number
    "phone": {
      "value": "+447000000000"
    },
    // Company
    "company": {
      "value": "Integrate"
    },
    // Job Title
    "jobTitle": {
      "value": "Software Engineer"
    },
    // Opt in
    "emailMe": {
      "value": true
    },
    // Business Card Scan
    "businessCard" : {
      "value": "e9535020-ac60-11e9-880c-1fb645532f1f", // The ID returned from uploading binary data for a resource
      "metadata" : {
        "uploadGUID" : "e9535020-ac60-11e9-880c-1fb645532f1f" // The ID returned from uploading binary data for a resource
      }
    },
    // Badge Scan
    "badgeScan" : {
      "value": "8374;Tilly;Stewart;Assistant Director;Gustr;Building;Road;City;State;AB1 2CD;United Kingdom;ZZ1 1ZZ;Some Province;07826354611;+1;09876543210;[email protected]"
    },
    // Text
    "text": {
      "value": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do..."
    },
    // Number
    "number": {
      "value": 1
    },
    // Multiple Choice
    "radio": {
      "value": "Yes"
    },
    // Drop-down List
    "title": {
      "value": "Mr"
    },
    // Checkboxes
    "checkbox": {
      "value": [
        "Product 1",
        "Product 2"
      ]
    },
    // Date or Time
    "dateOfBirth": {
      "value": "1989-01-01T00:00:00+00:00"
    },
    // Rating / Stars
    "rating": {
      "value": 8
    },
    // Link Collection
    "moreInformation": {
      "value" : [
        'https://test.com/product_one_brochure.pdf',
        'https://test.com/product_three_brochure.pdf'
      ]
    },
    // Autocomplete
    "country": {
      "value": "United Kingdom"
    },
    // Website
    "websiteUrl": {
      "value": "https://www.integrate-events.com"
    },
    // Take a Photo
    "photo" : {
      "value": "e95217a0-ac60-11e9-880c-1fb645532f1f", // The ID returned from uploading binary data for a resource
      "metadata" : {
        "uploadGUID" : "e95217a0-ac60-11e9-880c-1fb645532f1f", // The ID returned from uploading binary data for a resource
      }
    },
    // Signature
    "signature": {
      "value": "0adac260-b209-11ea-8587-3bbc2ebcbdd8", // The ID returned from uploading binary data for a resource
      "metadata": {
          "private": true, // Must be always "true"
          "uploadGUID": "0adac260-b209-11ea-8587-3bbc2ebcbdd8" // The ID returned from uploading binary data for a resource
      }
    }
  }
}
    
  

Includes

The availble includes are:

• event - The event to which the record belongs
• resources - The resources that are related to the record
• parent - If a duplicate record: the parent record (main duplicate)
• children - If a main duplicate record: The child records (duplicates)

For more information see the includes explanation

A Resource is comprised of metadata and binary data of an asset (image/document) and is associated with a record or an event. To create and retrieve record resources, see Create the metadata for a record's resource.

Please note, the maximum file size that can be uploaded is limited to 25mb. The number of binaries that customers upload is logged, and if deemed to be excessive, we may impose limits to usage. For more information, you can request access to our Fair Usage Policy.