REST API Documentation

evvnt has 3 REST APIs:

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.

Publisher API

The Publisher API currently supports the following endpoints:

GET /events

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

By default a maximum of 20 records are returned.

Filters can be applied to narrow down the result set.

Valid filters are as follows

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 /v3/events?include=occurrences

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

By default a maximum of 20 records are returned.

Filters can be applied to narrow down the result set.

Valid filters are as follows

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/v3/events?occurrences=includes
[
 {
    "id": 46658,
    "title": "The Event Title",
    "category_id": 124,
    "sub_category_ids": [],
    "timestamp": "2016-02-10T05:19:39.666806Z",
    "start_time": "2016-02-12T01:00:00+00:00",
    "end_time": "2024-08-17T23:00:00+01:00",
    "door_time": null,
    "last_entry_time": null,
    "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.",
    "organiser_name": "John Smith Event Organisers Ltd",
    "hashtag" : "event2013"
    "image_url": "http://example.com/the_url_of_the_image_associated_with_the_event",
    "image_urls": ["http://example.com/the_url_of_the_image_associated_with_the_event"],
    "links": {
      "Website": "https://go.evvnt.com/UUnkit",
      "Twitter": "https://go.evvnt.com/fswtgv",
      "Booking": "https://go.evvnt.com/ergy42"
    },
    "artists": "",
    "keywords" : "Example, event, keywords",
    "prices": {
        "Training": "USD 0"
    },
    "workflow_state": "reported_on",
    "capacity": null,
    "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
    },
    "contact": {
      "name": "John Smith",
      "email": "johnsmith@example.com",
      "tel": "020 1111 2222"
    },
    "occurrences": [
        {
            "id": 466548,
             "title": "The Event Title",
            "category_id": 124,
            "sub_category_ids": [],
            "timestamp": "2016-02-10T05:19:39.666806Z",
            "start_time": "2016-02-12T01:00:00+00:00",
            "end_time": "2024-08-17T23:00:00+01:00",
            "door_time": null,
            "last_entry_time": null,
            "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.",
            "organiser_name": "John Smith Event Organisers Ltd",
            "hashtag" : "event2013"
            "image_url": "http://example.com/the_url_of_the_image_associated_with_the_event",
            "image_urls": ["http://example.com/the_url_of_the_image_associated_with_the_event"],
            "links": {
              "Website": "https://go.evvnt.com/UUnkit",
              "Twitter": "https://go.evvnt.com/fswtgv",
              "Booking": "https://go.evvnt.com/ergy42"
            },
            "artists": "",
            "keywords" : "Example, event, keywords",
            "prices": {
                "Training": "USD 0"
            },
            "workflow_state": "reported_on",
            "capacity": null,
            "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
            },
            "contact": {
              "name": "John Smith",
              "email": "johnsmith@example.com",
              "tel": "020 1111 2222"
            }
        }
    ]
}
]

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:

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:

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:

Valid parameters are as follows:

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:

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

Valid parameters are as follows:

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:

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:

¹ 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.

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

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

² 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"
        }
      ]

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:

• event_id → ID of event
• broadcast_results: Summary of broadcast status of event
  • num_sites_total → Total number of sites the event has been sent to
  • num_sites_live → Number of publishers where the event is confirmed live on their site
  • num_sites_submitted → Number of publishers the event has ben sent to but is not confirmed to be live yet
• audience_reach: Estimates of the number of people who will see the event
  • uniques → Estimate of the number of views this event should receive
  • local_reach → Estimate of the number of views at the event's local level
  • mobile_apps → Number of mobile apps event will be published to
• clicks_by_day: Breakdown of the number of clicks we have tracked on the event, by day.

  x	Site 1	Site 2	Site …	Total clicks
  Date 1	n	n	n	n
  Date 2	n	n	n	n
  Date …	n	n	n	n

• referrers: Details of where referrer clicks are coming from
  • site_name1 → number of clicks
  • site_name2 → number of clicks
  • site_name3 → number of clicks
  • ...
• search_indexing: A list of URLs which can be used to check search engines for the event
  • google_url → Google URL to search for event by name
  • yahoo_url → Yahoo URL to search for event by name
  • bing_url → Bing URL to search for event by name
  • ask_url → Ask URL to search for event by name
  • aol_url → AOL URL to search for event by name
• broadcasts: a list of all the published instances of the event. Each broadcast contains:
  • url → URL of published event (if event has been successfully published, and verified)
  • category → The category of the publisher in evvnt’s reporting. This is a summation of location_type_description and the genre targetting of the publisher
  • authorise_publisher_url → URL to allow user to authorise evvnt with publisher using oauth. This URL will only be present for publishers which support authorisation (eventful), and when the user has not already authorised the publisher.
  • publisher: Details of the site/mobile app event has been published to
    • id → ID of publisher
    • name → Name of publisher
    • url → URL of publisher website
    • location_type_description → Categorises the reach and audience this publisher has. Can be one of: 'Global', 'National', 'Local', 'Social', 'Association'
    • site_unique_users → Estimate of number of unique users site has monthly
    • local_reach → Estimate of number of monthly users local to the event's location
    • mobile_app → Does publisher have a mobile app (true/false)
    • blog_post_url → URL of evvnt blog post describing publisher

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",
       "baidu_url": "http://www.baidu.com/s?wd=My+Event+Title",
       "yandex_url": "https://yandex.com/search/?text=My+Event+Title",
       "duckduckgo_url": "https://duckduckgo.com/?q=My+Event+Title",
       "wolfram_alpha_url": "https://www.wolframalpha.com/input/?i=My+Event+Title",
       "webcrawler_url": "https://www.webcrawler.com/serp?q=My+Event+Title",
       "search_com_url": "https://www.search.com/web?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

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"
          }
        ]
      }

GET /v3/publishers

This call will get you the list of publishers associated to this API Client.

An example return packet looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/v3/publishers
      {
        "data": [
          {
            "id": 9999,
            "name": "The Argus",
            "url": "http://www.theargus.co.uk/local-events"
          }
        ],
        "meta": {
          "current_page": 1,
          "total_pages": 1,
          "total_count": 1,
          "per_page": 10
        }
    }

GET /v3/staff

This call will get you the list of all the staff associated to your account, these IDs can be used as seller_id when creating a new package.

An example return packet looks like this:

      curl -X GET -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/v3/staff
      {
        "data": [
          {
            "id": 99999,
            "email": "user_99999@example.com",
            "role": "Sales"
          }
        ],
        "meta": {
          "current_page": 1,
          "total_pages": 1,
          "total_count": 1,
          "per_page": 10
        }
    }

POST /v3/staff

This call allow you to add a new staff member to your partner account.

Valid parameters are as follows:

An example request is as follows:

curl -X POST -H "Accept: application/json" -u API_KEY:API_SECRET https://api.evvnt.com/v3/staff
{
  "name": "Test User",
  "email": "test@example.com",
  "role": "Admin"
 }

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:

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:

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:

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:

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:

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:

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

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