Applying to use the evvnt APIs

To apply for API access, simply sign up at: https://evvnt.com/partner

evvnt REST API Documentation

evvnt has 3 REST APIs:

Publisher API Provides a feed of evvnt's data for publishing to your site or app. Also used as the basis for our discovery plugin product.
Event Organiser API Allows you to submit your businesses events for network publishing.
Partner API evvnt partners can resell & whitelabel evvnt's products through this API.

All 3 APIs use JSON over HTTPS and are hosted and are hosted at https://api.evvnt.com. Authentication is performed by passing an API key and API secret as the username/password combination of an HTTP Basic Authentication header.

evvnt Publisher API

The Publisher API currently supports the following endpoints:

GET /events List Events
GET /events/:event_id Get one event
GET /categories List categories
GET /publishers List my publishing sites
GET /publishers/:publisher_id/categories List categories for a publisher
GET /publishers/:publisher_id/published_events List published events for a publisher
GET /publishers/:publisher_id/published_events/:event_id Get a published event
PUT /publishers/:publisher_id/published_events/:event_id Update the live-link of a published event

GET /events

This API endpoint returns an array of event data in JSON format. An event has the following fields:

Field name Always present? Type Description
id Yes Integer Unique ID for the event
title Yes String The main title of the event
capacity No Integer Capacity of the event
category_id Yes Integer Category of the event (see GET /categories)
sub_category_ids Yes Array of Integers Sub-Categories of the event (see GET /categories)
timestamp Yes ISO8601 String ISO8601 time representation of when the event was last updated.
start_time Yes ISO8601 String ISO8601 time representation of the event start time. This is expressed as local time with a correct offset from UTC.
end_time Yes ISO8601 String ISO8601 time representation of the event end time. This is expressed as local time with a correct offset from UTC.
door_time No ISO8601 String ISO8601 time representation of the event's doors open time, if supplied. This is expressed as local time with a correct offset from UTC.
last_entry_time No ISO8601 String ISO8601 time representation of the event's last entry time. This is expressed as local time with a correct offset from UTC.
summary Yes String Summary of the event. Max length of 200 characters.
description Yes String Full description of the event. Max length of 2000 characters.
image_urls No Object An array of image urls associated with the event.
organiser_name No String The Organiser, Company or those responsible for hosting and managing the event
contact Yes Object Object containing contact information for someone responsible for the event as follows:
contact.name Yes String Name of the contact for the event.
contact.email Yes String Email address of the contact for the event.
contact.tel Yes String Telephone number of the contact for the event.
venue Yes Object Object containing the venue details as follows:
venue.id Yes Integer Unique ID of the venue hosting the event.
venue.name Yes String Name of the venue hosting the event.
venue.address_1 Yes String First line of the venue address.
venue.address_2 No String Second line of the venue address.
venue.town Yes String Town/city of the venue.
venue.country Yes String Two letter ISO code representing the country of the venue.
venue.postcode No String Post code / Zip code of the Venue. Always present for UK and US events.
venue.longitude No Decimal Approximate longitude of the venue, if known.
venue.latitude No Decimal Approximate latitude of the venue, if known.
links No Object URLs associated with the event expressed as key: value, where valid keys are: "Website", "Booking", "Inquiries", "Tickets", "Facebook", "Twitter", "MySpace", "YouTube", "Brochure", "MobileApp", "Periscope"
prices Yes Object Prices associated with the event are expressed as key:value pairs. Keys represent the ticket/price information and their corresponding values represent the currency amount.
artists No String Comma delimited list of artists or speakers featured in the events.
keywords No String Comma delimited list of relevant keywords.
hashtag No String Optional string to pass as a hashtag to supported sites. Only letters A-Z, 0-9 and underscore(_) are allowed. Any other characters will be removed.

By default a maximum of 20 records are returned.

Filters can be applied to narrow down the result set.

Valid filters are as follows

Name Type Description
max_results Integer Return a maximum of this many results. Values over 100 will be ignored.
newer_than ISO8601 String Return only events with a timestamp newer than this value. Format of value should be ISO8601. Useful for paging through results.
category_id Comma delimited Integers Comma delimited list of category_ids (see GET /categories) to only return events in selected categories, or children of those categories.
country String 2 Letter iso code of the country to restrict the result set to.
page Integer Return results paginated by max_results (or 20 ) records, on this page number.

An empty array will be returned if no events match the filter set

An example return packet with a single event looks like this:

curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/events?some_filters...
[
  {
    "id": 12345,
    "title": "The Event Title",
    "capacity": 100,
    "category_id": 17,
    "sub_category_ids": [],
    "timestamp": "2013-02-07T17:35:22Z",
    "start_time": "2013-02-23T22:00:00Z",
    "end_time": "2013-02-24T03:00:00Z",
    "summary": "This is an example event summary\r\nIt may have up to 200 characters. Line breaks look like this.\r\n",
    "description": "This is the complete event description. Line breaks still look like this.\r\n The full description can have up to 2000 characters.",
    "image_urls": ["http://example.com/the_url_of_the_image_associated_with_the_event"],
    "organiser_name": "John Smith Event Organisers Ltd",
    "contact" : {
      "name": "John Smith",
      "email": "johnsmith@example.com",
      "tel": "020 1111 2222"
    },
    "venue": {
      "id": "15",
      "name": "Venue name",
      "address_1": "Venue Address Line 1",
      "address_2": "Venue Address Line 2",
      "town": "Venue town / city",
      "country": "Venue Country",
      "postcode": "Venue post code / zip code",
      "latitude": 52.1234,
      "longitude": -0.5678
    },
    "links": {
      "Website": "https://go.evvnt.com/UUnkit",
      "Twitter": "https://go.evvnt.com/fswtgv",
      "Booking": "https://go.evvnt.com/ergy42"
    },
    "prices": {
      "price 1": "GBP 3.5",
      "price 2": "GBP 1.0"
    },
    "artists" : "Richard Green, Groucho Marx",
    "keywords" : "Example, event, keywords",
    "hashtag" : "event2013"
  }
]

GET /events/:event_id

Returns a single event which matches :event_id in the same format as GET /events. Returns a 404 if a matching event is not found.

An example return packet looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/events/12345
      {
        "id": 12345,
        "title": "The Event Title",
        "capacity": 100,
        "category_id": 17,
        "sub_category_ids": [22, 23],
        "timestamp": "2013-02-07T17:35:22Z",
        "start_time": "2013-02-23T22:00:00Z",
        "end_time": "2013-02-24T03:00:00Z",
        "summary": "This is an example event summary\r\nIt may have up to 200 characters. Line breaks look like this.\r\n",
        "description": "This is the complete event description. Line breaks still look like this.\r\n The full description can have up to 2000 characters.",
        "image_urls" : ["http://example.com/the_url_of_the_image_associated_with_the_event"],
        "organiser_name": "John Smith Event Organisers Ltd",
        "contact" : {
          "name": "John Smith",
          "email": "johnsmith@example.com",
          "tel": "020 1111 2222"
        },
        "venue": {
          "id": "15",
          "name": "Venue name",
          "address_1": "Venue Address Line 1",
          "address_2": "Venue Address Line 2",
          "town": "Venue town / city",
          "country": "Venue Country",
          "postcode": "Venue post code / zip code",
          "latitude": 52.1234,
          "longitude": -0.5678
        },
        "links": {
          "Website": "https://go.evvnt.com/UUnkit",
          "Twitter": "https://go.evvnt.com/fswtgv",
          "Booking": "https://go.evvnt.com/ergy42"
        },
        "prices": {
            "price 1": "GBP 3.5",
            "price 2": "GBP 1.0"
         },
        "artists" : "Richard Green, Groucho Marx",
        "keywords" : "Example, event, keywords"
      }

GET /categories

Returns the currently supported hierarchical list of categories and supported by evvnt.

There are no valid filters for this api call.

The format of a category record is as follows:

Field name Always present? Type Description
id Yes Integer Unique ID of the category.
parent_id Yes Integer or null The unique ID of the category of this subcategory's parent in the category tree. The category 'All', the only category at the root level in the hierarchy, will explicity specify a null value in this field.
name Yes String Name of the category.

An example call to retrieve the category list is as follows:

curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/categories

[
  { "id": 126,
    "parent_id": 2,
    "name": "Academic / Learning"
  },
  { "id": 49,
    "parent_id": 48,
    "name": "Accounting"
  },
  { "id": 96,
    "parent_id": 95,
    "name": "Agriculture"
  },
  { "id": 26,
    "parent_id": null,
    "name": "All"
  },
  { "id": 50,
    "parent_id": 48,
    "name": "Alternative Investment"
  },
  ....
]

GET /publishers

This API endpoint returns an array of publisher data in JSON format. You will only see publishers you have been specifically given access to. A publisher has the following fields:

Field name Always present? Type Description
id Yes Integer Unique ID for the publisher
name Yes String Internal name for publisher
url No String URL of publisher website

An empty array will be returned if you are not assigned any publishers.

An example return packet with a single publisher looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/publishers
      [
        {
          "id":324,
          "name":"Suuper Events",
          "url":"http://suuperevents.example.com
        }
      ]

/publishers/:publisher_id/categories

This API endpoint returns an array of categories that a publisher is interested in. You can only find categories for publishers you have been given permission for - you can find your list of publishers and their IDs with the GET /publishers API endpoint.

Categories have the following fields:

Field name Always present? Type Description
id Yes Integer Unique ID of the category.
parent_id Yes Integer or null The unique ID of the category of this subcategory's parent in the category tree. The category 'All', the only category at the root level in the hierarchy, will explicity specify a null value in this field.
name Yes String Name of the category.

Valid parameters are as follows:

Name Type Description
filter String

Optional. Can be one of the following (`all` is default):

all Return the categories directly linked to the publisher, their ancestor and their descendants categories

direct Only return the categories directly linked to the publisher

direct_to_root Only return the categories directly linked to the publisher and their ancestor categories

An example return request to get direct only categories:

curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/publishers/324/categories?filter=direct

[
  { "id": 126,
    "parent_id": 2,
    "name": "Academic / Learning"
  },
  { "id": 49,
    "parent_id": 48,
    "name": "Accounting"
  },
  { "id": 96,
    "parent_id": 95,
    "name": "Agriculture"
  },
  { "id": 26,
    "parent_id": null,
    "name": "All"
  },
  { "id": 50,
    "parent_id": 48,
    "name": "Alternative Investment"
  },
  ....
]

/publishers/:publisher_id/published_events

This API endpoint returns an array of published events belonging to a specific publisher. You can only find events for publishers you have been given permission for - you can find your list of publishers and their IDs with the GET /publishers API endpoint.

Published events have the following fields:

Field name Always present? Type Description
publisher_id Yes Integer Unique ID for the publisher
event_id Yes Integer Unique ID for the event
url No String Published URL of the event on the publisher site
event_title Yes String Title of the event
event_start_time Yes Date ISO8601 time representation of the event start time. This is expressed as local time with a correct offset from UTC

An empty array will be returned if no upcoming published events exist for the publisher.

Valid parameters are as follows:

Name Type Description
newer_than ISO8601 String Return only events with a timestamp newer than this value. Format of value should be ISO8601. Useful for paging through results. This is expressed as local time with a correct offset from UTC

An example return packet with a single published event looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/publishers/324/published_events/
      [
         {
             "publisher_id": 324,
             "event_id": 1385,
             "url": 'http://suuperevents.example.com/events/3',
             "event_title": "Comedy Night",
             "event_start_time": "2024-05-10T15:00:00+01:00"
         }
      ]

/publishers/:publisher_id/published_events/:event_id

Returns a single published event which matches the :publisher_id and the :event_id. Returns a 404 error if a matching published event is not found.

An example return packet looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/publishers/324/published_events/1385

      {
         "publisher_id": 324,
         "event_id": 1385,
         "url": null,
         "event_title": "Accounting Conf 2",
         "event_start_time": "2014-05-10T15:00:00+01:00"
      }

/publishers/:publisher_id/published_events/:event_id

This call is used to set the URL of a published event. e.g. If you have just published an event on your site - use this endpoint to let evvnt know the URL.

Data should be sent in the the PUT body as a JSON packet with either only a URL or a slug. If both, a slug and a URL are provided, the slug is rejected.

A successful PUT where the published event is updated in the system will return a 200 response code.

A 404 will be returned if the event is not found in the system, or the ID of the event requested is not accessable by your API key.

An example of a PUT request with URL is as follows:

      curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/publishers/324/published_events/1385 -d '
      {
        "url": "http://new-url.example.com"
      }'

An example of a PUT request with slug is as follows:

      curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/publishers/324/published_events/1385 -d '
      {
        "slug": "foo/bar"
      }'

evvnt Event Organiser API

The Event Organiser API currently supports the following endpoints:

GET /contract Get contract information
POST /packages Create a package
GET /packages/mine List my packages
GET /packages/:package_id Get the details of a package
POST /events Create an event
PUT /events/:event_id Update an event
GET /events/mine List my events
GET /events/:event_id/report View report data for my event

Note all users of the Event Organiser API will be able to access all endpoints of the Publisher API.

GET /contract

This call gets the API-relevant details of the contract agreed between yourself and evvnt.

An example return packet looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/contract
      {
        "package_options": [
          {
            "id": 50
            "type": "SinglePackage"
            "broadcast_volume": 60,
            "currency": "GBP",
            "cost_per_event": "500.0"
          }
        ]
      }

POST /packages

This call is used to create a package. A package represents a purchase of an evvnt service.

Package data should be sent in the the POST body as a JSON packet with the following parameters:

Field name Mandatory? Type Description
id Yes Integer The ID 1 of the package option to purchase
event_quantity Yes Integer The number of events to broadcast
purchase_order_id No String A purchase order number
notes No String Arbitrary notes

1 The ID specified must match a contractually agreed package option (use GET /contract to get package options).

A successful POST where the package is created will return a 200 response code and the id of the created package. e.g.

      {"id": "550e8400-e29b-41d4-a716-446655440000"}

If invalid or missing values are supplied, a 400 response code will be returned with an array of the relevant error messages in the response body.

An example of such an error response is as follows:

      {
        "errors": [
          "Package event_quantity can't be blank, is not a number"
        ]
      }

An example of a POST request is as follows

      curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -u API_KEY:API_SECRET -d '{
        "id": 50,
        "event_quantity": 5,
        "purchase_order_id": "PO235",
        "notes": ""
      }' https://api.evvnt.com/packages

GET /packages/mine

This call lists all of the packages you have purchased.

An example return packet looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/packages/mine
      [
        {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "type": "SinglePackage",
          "broadcast_volume": 60,
          "event_quantity": 5,
          "purchase_order_id": "PO235",
          "notes": "",
          "purchase_date": "2014-01-01"
        }
      ]

GET /packages/:package_id

This call gets the details of a specified package.

An example return packet looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/packages/550e8400-e29b-41d4-a716-446655440000
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "type": "SinglePackage",
        "broadcast_volume": 60,
        "event_quantity": 5,
        "purchase_order_id": "PO235",
        "notes": "",
        "purchase_date": "2014-01-01"
      }

POST /events

This call is used to create an event in the evvnt system.

Deprecated Functionality

We are changing the package_id parameter very soon:

Field name Always present? Type Description
package_id Yes String Package the event is to deplete the 'credits' of (see POST /packages).

package_id will become mandatory on September 25th 2015.

Event data should be sent in the the POST body as a JSON packet with the following parameters:

Field name Mandatory? Type Description
title Yes String The main title of the event
capacity No Integer Capacity of the event
category_id Yes Integer Category of the event (see GET /categories)
sub_category_ids No Array of Integers Sub-Categories of the event (see GET /categories)
package_id No String Package the event is to deplete the 'credits' of (see POST /packages)
start_time Yes ISO8601 String ISO8601 time representation of the event start time. This should be expressed as local time with a correct offset 1 from UTC.
end_time Yes ISO8601 String ISO8601 time representation of the event end time. This should be expressed as local time with a correct offset 1 from UTC.
door_time No ISO8601 String ISO8601 time representation of the (optional) event's doors open time. This should be expressed as local time with a correct offset 1 from UTC. If supplied, the door time must be before end_time and last_entry_time (if supplied).
last_entry_time No ISO8601 String ISO8601 time representation of the (optional) event's last entry time. This should be expressed as local time with a correct offset 1 from UTC. If supplied, the last entry time must be on or after the start_time, and on or before the end_time.
summary Yes String Summary of the event. Max length of 200 characters.
description Yes String Full description of the event. Max length of 2000 characters.
image_urls No Object An array of image urls associated with the event. Upto two urls can be supplied.
organiser_name No String The Organiser, Company or those responsible for hosting and managing the event
contact Yes 2 Object Object containing contact information for someone responsible for the event as follows:
contact.name Yes String Name of the contact for the event.
contact.email Yes String Email address of the contact for the event.
contact.tel Yes String Telephone number of the contact for the event.
venue Yes Object Object containing the venue details as follows:
venue.id Yes Integer Unique ID of the venue hosting the event.
venue.name Yes String Name of the venue hosting the event.
venue.address_1 Yes String First line of the venue address.
venue.address_2 No String Second line of the venue address.
venue.town Yes String Town/city of the venue.
venue.country Yes String Two letter ISO code representing the country of the venue.
venue.postcode No String Post code / Zip code of the Venue. Mandatory for UK and US events.
links No Object URLs associated with the event expressed as key: value, where valid keys are: "Website", "Booking", "Inquiries", "Tickets", "Facebook", "Twitter", "MySpace", "YouTube", "Brochure", "MobileApp", "Periscope"
prices Yes Object Prices associated with the event are expressed as key:value pairs. Keys represent the ticket/price information and their corresponding values represent the currency amount.
artists No String Comma delimited list of artists or speakers featured in the events.
keywords No String Comma delimited list of relevant keywords.
hashtag No String Optional string to pass as a hashtag to supported sites. Only letters A-Z, 0-9 and underscore(_) are allowed. Any other characters will be removed.

1 If the event's start/end times occur during observation of Daylight Saving Time (DST), the UTC offset must be specified accordingly.

2 Contact information is a recent addition to the API (September 2013). For backwards compatibility for existing API users, we will be accepting submissions without contact information for a limited time. However, all API users are urged to include contact information.

A successful POST where the event is created in the system will return a 200 response code and the id of the created event. e.g.

      {"id": 12345}

If invalid or missing values are supplied, a 400 response code will be returned with an array of the relevant error messages in the response body.

An example of such an error response is as follows:

      {
        "errors" : [
          "Event title can't be blank",
          "Venue name can't be blank"
        ]
      }

An example of a POST request is as follows

      curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -u API_KEY:API_SECRET -d '{
"title": "An Event Title",
"capacity": 100,
"category_id": 17,
"start_time": "2018-06-23T22:00:00+0100",
"end_time": "2018-06-24T03:00:00+0100",
"summary": "This is an example event summary\nIt may have up to 200 characters. Line breaks look like this.\n",
"description": "This is the complete event description. Line breaks still look like this.\n The full description can have up to 2000 characters.",
"image_urls": ["https://www.evvnt.com/assets/evvnt-logo-turquoise-eef2bd741d1234a691af6d8cfdbc067e.png"],
"organiser_name": "Event Organiser Ltd",
"contact": {
  "name": "John Smith",
  "email": "johnsmith@example.com",
  "tel": "020 1111 2222"
},
"venue": {
  "name": "evvnt",
  "address_1": "17a Newman Street",
  "address_2": "Fitzrovia",
  "town": "London",
  "country": "GB",
  "postcode": "W1T 1PD",
  "latitude": 51.517337,
  "longitude": -0.135175
},
"links" : {
  "Website": "http://example.com/url1",
  "Twitter": "http://example.com/url2",
  "Booking": "http://example.com/url3"
},
"prices": {
    "price 1": "GBP 50",
    "price 2": "GBP 100"
},
"artists" : "ELon Musk, Mark Zuckerberg",
"keywords" : "Example, Event, Keywords",
"hashtag" : "event2018"
    }' https://api.evvnt.com/events

PUT /events/:event_id

This call is used to update an event that already exists in the evvnt system.

Event data should be sent in the the PUT body as a JSON packet with the same format as the POST /events request.

A successful PUT where the event is updated in the system will return a 200 response code.

A 404 will be returned if the event is not found in the system, or the ID of the event requested does not belong to the user associated with the API_KEY.

Values omitted from the PUT request will leave the existing value unchanged, so only pass values you want to update.

An example of a PUT request is as follows:

      curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -u API_KEY:API_SECRET -d '{
        "title": "The Updated Event Title",
        "start_time": "2013-06-23T22:30:00+0100",
        "image_urls" : ["http://example.com/the_url_of_the_updated_image_associated_with_the_event"],
      }' https://api.evvnt.com/events/12345

GET /events/mine

This call is almost identical to GET /events (including all the same filters) except it will only return events created by the user associated with the API_KEY.

An example return packet with a single event looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/events/mine?some_filters...
      [
        {
          "id": 12345,
          "title": "The Event Title",
          "capacity": 100,
          "category_id": 17,
          "timestamp": "2013-02-07T17:35:22Z",
          "start_time": "2013-02-23T22:00:00Z",
          "end_time": "2013-02-24T03:00:00Z",
          "summary": "This is an example event summary\r\nIt may have up to 200 characters. Line breaks look like this.\r\n",
          "description": "This is the complete event description. Line breaks still look like this.\r\n The full description can have up to 2000 characters.",
          "image_urls" : ["http://example.com/the_url_of_the_image_associated_with_the_event"],
          "organiser_name": "John Smith Event Organisers Ltd",
          "contact" : {
            "name": "John Smith",
            "email": "johnsmith@example.com",
            "tel": "020 1111 2222"
          },
          "venue": {
            "name": "Venue name",
            "address_1": "Venue Address Line 1",
            "address_2": "Venue Address Line 2",
            "town": "Venue town / city",
            "country": "Venue Country",
            "postcode": "Venue post code / zip code",
            "latitude": 52.1234,
            "longitude": -0.5678
          },
          "links" : {
            "Website": "https://go.evvnt.com/UUnkit",
            "Twitter": "https://go.evvnt.com/fswtgv",
            "Booking": "https://go.evvnt.com/ergy42"
          },
          "prices": {
            "price 1": "GBP 3.5",
            "price 2": "GBP 1.0"
          },
          "artists" : "Richard Green, Groucho Marx",
          "keywords" : "Example, event, keywords",
          "hashtag" : "event2013",
          "report_url" : "https://app.evvnt.com/reports/ZW8AFEGZFE6G9"
        }
      ]

Deprecated Functionality

In addition the call returns one extra optional key for each event as follows:

Field name Always present? Type Description
report_url No String URL of a report that can be accessed with the results of the evvnt broadcast

GET /events/:event_id/report

View report data for an event belonging to me. This request will show you all the information you can normally see in an event report, including:

An example return packet with a single event looks like this:

curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/events/1234/report
{
   "event_id": 1234,
   "broadcast_results":
   {
       "num_sites_total": 90,
       "num_sites_live": 30,
       "num_sites_submitted": 60
   },
   "audience_reach":
   {
       "uniques": 79302819,
       "local_reach": 790108,
       "mobile_apps": 29
   },
   "clicks_by_day":
   [
       ["x", "Twitter", "Myspace", "Total clicks"],
       ["1 Mar", 5, 22, 27],
       ["2 Mar", 0, 0, 0],
       ["3 Mar", 9, 0, 9],
       ["4 Mar", 0, 3, 3]
   ],
   "referrers":
   {
       "facebook.com": 3,
       "twitter.com": 4
   },
   "search_indexing":
   {
       "google_url": "https://www.google.co.uk/search?q=My+Event+Title",
       "yahoo_url": "http://search.yahoo.com/search?p=My+Event+Title",
       "bing_url": "http://www.bing.com/search?q=My+Event+Title",
       "ask_url": "http://www.ask.com/web?q=My+Event+Title",
       "aol_url": "http://search.aol.com/aol/search?q=My+Event+Title"
   },
   "broadcasts":
   [
       {
           "url": "",
           "category": "Targeted",
           "publisher":
           {
               "id": 133,
               "name": "- Finance: Financial Conferences",
               "url": "http://www.financial-conferences.com/",
               "location_type_description": "Global",
               "site_unique_users": 15000,
               "local_reach": 150,
               "mobile_app": false,
               "blog_post_url": "http://evvnt.com/2012/10/the-guide-to-financial-conference-events-listing-site/"
           }
       },
       ... more broadcasts...
   ]
}

evvnt Partner API

This API is a non-public API intended only for partners who will be creating evvnt accounts and events on behalf of their users.

You should only use this API if you are using our white label service.

It is an extension of the publisher and event organiser APIs, so that documentation remains valid, except for differences mentioned here.

The Partner API currently supports the following endpoints:

GET /contract Get contract information
POST /users Create a user
GET /users Get a list of all users created by you
GET /users/:user_id Get details of a user
PUT /users/:user_id Update a user
POST /packages Create a package
GET /users/:user_id/packages Lists all of the packages belonging to a user
POST /events Create an event
PUT /events/:event_id Update an event
GET /events/ours Get events of you and your created users
GET /events/ours/:event_id Get event created by your or your sub users

GET /contract

This call gets the API-relevant details of the contract agreed between yourself and evvnt.

An example return packet looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/contract
      {
        "package_options": [
          {
            "id": 50
            "type": "SinglePackage"
            "broadcast_volume": 60,
            "currency": "GBP",
            "cost_per_event": "500.0"
          }
        ]
      }

POST /users

This request will create a new user in the evvnt system by the client. This request should be made before any events are created on behalf of the user.

User data should be sent in the the POST body as a JSON packet with the following parameters:

Field name Mandatory? Type Description
name Yes String The full name of the user
email Yes String The email address of the user

An example request is as follows:

      curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -u API_KEY:API_SECRET -d '{
        "name": "Richard Green",
        "email": "richard@example.com"
      }' https://api.evvnt.com/users

Successful POSTs will return a 200 response code, and an ID value for the user (which will be a uuid). e.g.:

      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }

Unsuccessful POSTs will return a 400 and an array of error messages. e.g.:

      {
        "errors" : [
          "Not a valid email address"
        ]
      }

GET /users

This request will return details for all users created by your account via the POST /users call above.

A JSON array of users will be returned. Each element of the array will contain the following fields:

Field name Always present? Type Description
uuid Yes String The unique identifier for this user. You will need to reference this UUID when creating events on a user's behalf.
name Yes String The full name of the user
email Yes String The email address of the user

An example request is as follows:

curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/users

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
    "name": "Richard Green",
    "email": "richard@example.com"
  },
  {
    "uuid": "af356362-b1cd-3e2a-22aa-112142abcded"
    "name": "Delores Smith",
    "email": "delores@example.com"
  }
]

GET /users/:user_id

This request will return the currently held details for a user created by the client.

Fields returned are as follows:

Field name Always present? Type Description
uuid Yes String The unique identifier for this user. You will need to reference this UUID when creating events on a user's behalf.
name Yes String The full name of the user
email Yes String The email address of the user

An example request is as follows:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/users/550e8400-e29b-41d4-a716-446655440000

      {
        "name": "Richard Green",
        "email": "richard@example.com"
      }

PUT /users/:user_id

This request will update the data held by evvnt for a client.

User data should be sent in the the PUT body as a JSON packet with the following parameters:

Field name Mandatory? Type Description
name No String The full name of the user
email No String The email address of the user

Only values that are being changed need to be passed.

An example request is as follows:

      curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -u API_KEY:API_SECRET -d '{
        "email": "richard2@example.com"
      }' https://api.evvnt.com/users/550e8400-e29b-41d4-a716-446655440000

POST /packages

This request is used to create a package on behalf of a user created by POST /users.

This is the same as the event organiser API request, except a URL query parameter for the user who the package is being created on behalf of must be appended to the URL. For example:

      POST https://api.evvnt.com/packages?user_id=550e8400-e29b-41d4-a716-446655440000

Package data should be sent in the the POST body as a JSON packet with the following parameters:

Field name Mandatory? Type Description
id Yes Integer The ID 1 of the package option to purchase
event_quantity Yes Integer The number of events to broadcast
purchase_order_id No String A purchase order number
notes No String Arbitrary notes

A successful POST where the package is created will return a 200 response code and the id of the created package. e.g.

      {"id": "550e8400-e29b-41d4-a716-446655440000"}

If invalid or missing values are supplied, a 400 response code will be returned with an array of the relevant error messages in the response body.

An example of such an error response is as follows:

      {
        "errors": [
          "Package event_quantity can't be blank, is not a number"
        ]
      }

If a valid used ID is not passed, a 403 response code will be returned with an array of the relevant error messages in the response body.

An example of such an error response is as follows:

      {
        "errors" : [
          "Unknown user id"
        ]
      }

An example of a POST request is as follows

      curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -u API_KEY:API_SECRET -d '{
        "id": 50,
        "event_quantity": 5,
        "purchase_order_id": "PO235",
        "notes": ""
      }' https://api.evvnt.com/packages?user_id=550e8400-e29b-41d4-a716-446655440000

GET /users/:user_id/packages

This call lists all of the packages belonging to a specified user created by POST /users

An example return packet looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/users/550e8400-e29b-41d4-a716-446655440000/packages
      [
        {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "type": "SinglePackage",
          "broadcast_volume": 60,
          "event_quantity": 5,
          "purchase_order_id": "PO235",
          "notes": "",
          "purchase_date": "2014-01-01",
          "user_id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ]

POST /events

This request is used to create an event on behalf of a user created by POST /users.

This is the same as the Event Organiser API request, except a URL query parameter for the user who the event is being created on behalf of must be appended to the URL. For example:

      POST https://api.evvnt.com/events?user_id=550e8400-e29b-41d4-a716-446655440000

The originating publisher site of the event can be specified by passing an optional query parameter "publisher_id" set to the unique ID of the publisher. For example:

      POST https://api.evvnt.com/events?user_id=550e8400-e29b-41d4-a716-446655440000&publisher_id=123456

In almost all cases a package ID should also be passed with the event, allowing us to join the user, related package and event together. (see POST /packages) For example:

      POST https://api.evvnt.com/events?user_id=550e8400-e29b-41d4-a716-446655440000&publisher_id=123456&package_id=550e8400-e29b-41d4-a716-446655440000

Event data should be sent in the the POST body as a JSON packet with the following parameters:

Field name Mandatory? Type Description
title Yes String The main title of the event
capacity No Capacity Capacity of the event
category_id Yes Integer Category of the event (see GET /categories)
package_id No String Package the event is to deplete the 'credits' of (see POST /packages)
start_time Yes ISO8601 String ISO8601 time representation of the event start time. This should be expressed as local time with a correct offset from UTC.
end_time Yes ISO8601 String ISO8601 time representation of the event end time. This should be expressed as local time with a correct offset from UTC.
door_time No ISO8601 String ISO8601 time representation of the (optional) event's doors open time. This should be expressed as local time with a correct offset 1 from UTC. If supplied, the door time must be on or after the start_time, and on or before the end_time.
last_entry_time No ISO8601 String ISO8601 time representation of the (optional) event's last entry time. This should be expressed as local time with a correct offset 1 from UTC. If supplied, the last entry time must be on or after the start_time, and on or before the end_time.
summary Yes String Summary of the event. Max length of 200 characters.
description Yes String Full description of the event. Max length of 2000 characters.
image_urls No String URL of the image associated with the event.
organiser_name No String The Organiser, Company or those responsible for hosting and managing the event
contact Yes Object Object containing contact information for someone responsible for the event as follows:
contact.name Yes String Name of the contact for the event.
contact.email Yes String Email of the contact associated with the event.
contact.tel Yes String Telephone number of the contact associated with the event.
venue Yes Object Object containing the venue details as follows:
venue.name Yes String Name of the venue hosting the event.
venue.address_1 Yes String First line of the venue address.
venue.address_2 No String Second line of the venue address.
venue.town Yes String Town/city of the venue.
venue.country Yes String Two letter ISO code representing the country of the venue.
venue.postcode No String Post code / Zip code of the Venue. Mandatory for UK and US events.
links No Object URLs associated with the event expressed as key: value, where valid keys are: "Website", "Booking", "Inquiries", "Tickets", "Facebook", "Twitter", "MySpace", "YouTube", "Brochure", "MobileApp", "Periscope"
prices Yes Object Prices associated with the event are expressed as key:value pairs. Keys represent the ticket/price information and their corresponding values represent the currency amount.
artists No String Comma delimited list of artists or speakers featured in the events.
keywords No String Comma delimited list of relevant keywords.
hashtag No String Optional string to pass as a hashtag to supported sites. Only letters A-Z, 0-9 and underscore(_) are allowed. Any other characters will be removed.

A successful POST where the event is created in the system will return a 200 response code and the id of the created event. e.g.

      {"id": 12345}

If invalid or missing values are supplied, a 400 response code will be returned with an array of the relevant error messages in the response body.

An example of such an error response is as follows:

      {
        "errors" : [
          "Event title can't be blank",
          "Venue name can't be blank"
        ]
      }

If a valid used ID is not passed, a 403 response code will be returned with an array of the relevant error messages in the response body.

An example of such an error response is as follows:

      {
        "errors" : [
          "Unknown user id"
        ]
      }

An example of a POST request is as follows

      curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -u API_KEY:API_SECRET -d '{
"title": "An Event Title",
"capacity": 100,
"category_id": 17,
"start_time": "2018-06-23T22:00:00+0100",
"end_time": "2018-06-24T03:00:00+0100",
"summary": "This is an example event summary\nIt may have up to 200 characters. Line breaks look like this.\n",
"description": "This is the complete event description. Line breaks still look like this.\n The full description can have up to 2000 characters.",
"image_urls": ["https://www.evvnt.com/assets/evvnt-logo-turquoise-eef2bd741d1234a691af6d8cfdbc067e.png"],
"organiser_name": "Event Organiser Ltd",
"contact": {
  "name": "John Smith",
  "email": "johnsmith@example.com",
  "tel": "020 1111 2222"
},
"venue": {
  "name": "evvnt",
  "address_1": "17a Newman Street",
  "address_2": "Fitzrovia",
  "town": "London",
  "country": "GB",
  "postcode": "W1T 1PD",
  "latitude": 51.517337,
  "longitude": -0.135175
},
"links” : {
  "Website": "http://example.com/url1",
  "Twitter": "http://example.com/url2",
  "Booking": "http://example.com/url3"
},
"prices”: {
    "price 1": "GBP 50",
    "price 2": "GBP 100"
},
"artists" : "ELon Musk, Mark Zuckerberg",
"keywords" : "Example, Event, Keywords",
"hashtag" : "event2018"
    }' https://api.evvnt.com/events?user_id=550e8400-e29b-41d4-a716-446655440000

PUT /events/:event_id

This call is used to update an event that already exists in the evvnt system.

This is the same as the event organiser API request, except a URL query parameter for the user who the event is being created on behalf of must be appended to the URL. e.g.:

      PUT https://api.evvnt.com/events/12345?user_id=550e8400-e29b-41d4-a716-446655440000

Event data should be sent in the the PUT body as a JSON packet with the same format as the POST /events request.

A successful PUT where the event is updated in the system will return a 200 response code.

A 404 will be returned if the event is not found in the system, or the ID of the event requested does not belong to the user associated with the API_KEY.

If a valid used ID for that event is not passed, a 403 response code will be returned with an array of the relevant error messages in the response body.

An example of such an error response is as follows:

      {
        "errors" : [
          "Incorrect user id"
        ]
      }

Values omitted from the PUT request will leave the existing value unchanged, so only pass values you want to update.

An example of a PUT request is as follows:

      curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -u API_KEY:API_SECRET -d '{
        "title": "The Updated Event Title",
        "start_time": "2013-06-23T22:30:00+0100",
        "image_urls" : ["http://example.com/the_url_of_the_updated_image_associated_with_the_event"],
      }' https://api.evvnt.com/events/12345?user_id=550e8400-e29b-41d4-a716-446655440000

GET /events/ours

This call is almost identical to GET /events from the public API (including all the same filters) except it will only return events associated users created by your API key. You can also filter by a specific user id.

Examples:

      GET https://api.evvnt.com/events/ours

      GET https://api.evvnt.com/events/ours?user_id=550e8400-e29b-41d4-a716-446655440000

Deprecated Functionality

Events which are ready for reporting will return one extra (optional) key as follows:

Field name Always present? Type Description
report_url No String URL of a report that can be accessed with the results of the evvnt broadcast

Note 1: In the Partner API the report URL should be treated with the same level of security you would treat a password. It will allow the a browser to start an authenticated session with evvnt with no further challenges (so your client app can directly link to the event report within the context of your app).

Note 2: This link will have a short expiry time (about 30 minutes) so when presenting this link to the user on a page, ensure it has been retrieved recently.

Note 3: Do not link to the report URL in an iframe. It does not play nicely with the "connect to facebook" and other OAuth functionality required to use evvnt's API integrations.

An example return packet with a single event looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/events/ours?some_filters...
      [
        {
          "id": 12345,
          "title": "The Event Title",
          "capacity": 100,
          "category_id": 17,
          "timestamp": "2013-02-07T17:35:22Z",
          "start_time": "2013-02-23T22:00:00Z",
          "end_time": "2013-02-24T03:00:00Z",
          "summary": "This is an example event summary\r\nIt may have up to 200 characters. Line breaks look like this.\r\n",
          "description": "This is the complete event description. Line breaks still look like this.\r\n The full description can have up to 2000 characters.",
          "image_urls" : ["http://example.com/the_url_of_the_image_associated_with_the_event"],
          "venue": {
            "name": "Venue name",
            "address_1": "Venue Address Line 1",
            "address_2": "Venue Address Line 2",
            "town": "Venue town / city",
            "country": "Venue Country",
            "postcode": "Venue post code / zip code",
            "latitude": 52.1234,
            "longitude": -0.5678
          },
          "links" : {
            "Website": "https://go.evvnt.com/UUnkit",
            "Twitter": "https://go.evvnt.com/fswtgv",
            "Booking": "https://go.evvnt.com/ergy42"
          }
          "artists" : "Richard Green, Groucho Marx",
          "keywords" : "Example, event, keywords",
          "user_id" : "550e8400-e29b-41d4-a716-446655440000"
          "report_url" : "https://app.evvnt.com/reports/ZW8AFEGZFE6G9?digest=24235235231asf08afcsafas&timestamp=13215125"
        }
      ]

GET /events/ours/:event_id

Can be used to return a single event which matches :event_id, in the same format as GET /events/:event_id, but containing the extra attributes: user_id and report_url. Returns a 404 if a matching event is not found. See the event organiser API documentation for more information.