Events

An event is an individual event against which attendees can register themselves. Each event will have one or more tickets for sale.

What can you do with Events?

Event properties

id
{"id":"123456"}
					

The unique numeric identifier for the event. Event ids are unique across the entire EventHQ system; no two events will have the same id, even if they're from different accounts.

url
{"url":"https:\/\/{your-subdomain}.eventhq.co.uk\/api\/v1\/events\/view\/event:introductory-bat-detector-workshop-milnthorpe-cumbria-may-2015:}
					

The full link to the /api/events/view endpoint. You need only append your authentication token. Note, the URL will contain the API endpoint you're using. If you're using a specific version then that version will be in the generated URL.

register_url
{"register_url":https:\/\/{your-subdomain}.eventhq.co.uk\/bookings\/start\/event:introductory-bat-detector-workshop-milnthorpe-cumbria-may-2015"}
					

The full URL to the EventHQ booking form.

name
{"name":"Introductory Bat Detector Workshop Milnthorpe Cumbria May 2015"}
					

The event name

slug
{"slug":"introductory-bat-detector-workshop-milnthorpe-cumbria-may-2015"}
					

A human-friendly unique string for the Event automatically generated from its name. The slug is unique to this event within the account. Unlike the id which is unique right across EventHQ, the slug is unique within the account but not necessarily across the whole of EventHQ.

location
{"location":"Preston Patrick Memorial Hall, Milnthorpe, Cumbria,  LA7 7NR"}
					

The location of the event

summary
{"summary":"An introductory bat detector workshop involving an evening classroom session followed by a practical field session starting around dusk."}
					

A short executive style summary of the event

registration_opens
{"registration_opens":"2014-12-09T00:00:00+0100"}
					

The date and time when event registration will open. The API returns this value in ISO 8601 format.

registration_closes
{"registration_closes":"2015-05-09T00:00:00+0100"}
					

The date and time when event registration will close. The API returns this value in ISO 8601 format.

event_starts
{"event_starts":"2015-05-09T00:00:00+0100"}
					

The date and time when the event starts. The API returns this value in ISO 8601 format.

event_ends
{"event_ends":"2015-05-09T00:00:00+0100"}
					

The date and time when the event ends. The API returns this value in ISO 8601 format.

tags
{"tags":["London","Conference"]}
					

Tags used to classify the event. If no tags used then this will be an empty array. Tags are commonly used for filtering and searching.

attendee_count
{"attendee_count":"300"}
					

The total number of attendees registered for this event, including any attendees currently in the booking process.

test
{"test":false}
					

Test flag. Events in test mode will not accept real payments and attendees booked onto an event in test mode are not charged for by EventHQ.

sold_out
{"sold_out":false}
					

Sold out flag. Events are marked as sold out either when the overall venue limit has been reached or when all primary ticket limits have been reached, whichever happens first.

products (events/view only)
{"id":"547c8483-d81c-4723-b83d-2fb5c0a80002"}
{"event_id":"123456"}
{"event_days":['Monday']}
{"primary":false}
{"name":"Individual Membership"}
{"description":"Individual Membership is £30. Members receive a £5 discount off of training courses (hence the cost of £25)"}
{"total_available":null}
{"admin_only":false}
{"max_order_per_attendee":"1"}
{"vat_rate":null}
{"position":"1"}
{"total_used":null}
{"published":true}
{"deleted":false}
{"deleted_date":null}
{"created":"2014-12-01T15:08:51+0000"}
{"modified":"2014-12-01T15:08:51+0000"}
{"sold_out":"0"}
{"current_price":25}
{"prices":[{  
  "value":"25.00",
  "until_end_of":null,
  "product_id":"547c8483-d81c-4723-b83d-2fb5c0a80002"
 }]
					

A list of products associated with the event, usually (but not always tickets). Products where the "primary" property is false are optional extras. Where a product has more than one price then all prices are provided in a prices property and the current price can be found in a current_price property.

Where an event is being held over multiple days, EventHQ allows users to associate tickets to specific days. These are then shown in the products.event_days property.

GET /api/events/index

Receive a list of all events

limit
					

Number of results to return per page
(default: 20)

page
					

Page to show
(default: 1)

sort
					

Field on which to order the results
(default: event start date descending, i.e. the next event is first)

direction
					

Direction in which to order the results
(default: desc)

q
					

Optional search parameter. Performs a partial search on event name and location using an OR.

f
					

Optional filters which can be applied to the event listing. Select from one or more of the following:

live
					

If present in the URL and set to "1" then return only events where registration is currently open and which has at least one primary ticket available for selection by an attendee. If present in the URL and set to anything else then return only events where registration is either yet to open or has closed.

year
					

Filter events by the year in which the event opened. For example, pass in 2014 to see all events held in 2014

event_starts
					

Filter events by the event start date. Pass in either a predefined trigger ("this_month", "this_quarter", "this_year") or an operator and date. Available operators are < and > and dates should be formatted as yyyy-mm-dd. Examples of this filter are:

event_starts:this_month
event_starts >:2015-01-01
event_starts <:2015-01-01
					

Note that when passing an "<" or ">" operator, the format is event_starts{space}{operator}:{date}

event_ends
					

Filter events by the event end date. Pass in either a predefined trigger ("this_month", "this_quarter", "this_year") or an operator and date. Available operators are < and > and dates should be formatted as yyyy-mm-dd. Examples of this filter are:

event_ends:this_month
event_ends >:2015-01-01
event_ends <:2015-01-01
					

Note that when passing an "<" or ">" operator, the format is event_ends{space}{operator}:{date}

tag
					

Return only events associated with the specified tag_id. You can specify the tag key multiple times in one API call to build a call which will return events which match any of the tag ids provided (see examples below).

tag_not
					

Return only events which are not associated with the specified tag_id. You can specify the tag_not key multiple times in one API call to build a call which will return events which do not match any of the tag ids provided (see examples below).

test
					

Return all events in test mode if this param is present and set to "1" else if present and set to anything else return all events not in test mode.

Example API calls

Get all events

GET /api/events/index/token:{your-token-here}
			

Get page 2 of a paginated list of events ordered by event start date in ascending order

GET /api/events/index/token:{your-token-here}/page:2/order:event_starts/direction:asc
			

Get only live events

GET /api/events/index/token:{your-token-here}/f:live:1
			

Get only live events which start after the 1st January 2015

GET /api/events/index/token:{your-token-here}/f:live:1|event_starts >:2015-01-01
			

Get only live events which match one of the specified tag IDs

GET /api/events/index/token:{your-token-here}/f:live:1|tag:52498daf-ee31-fa1e-b87e-6d41c0a80002|tag:52498daf-20b0-4cbe-b87e-6d41c0a80002
			

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
	"message":"success",
	"events":
	[
		{
			"id":"2179",
			"url":"https:\/\/{your-subdomain}.eventhq.co.uk\/api\/v1\/events\/view\/event:surveying-trees-december-2015",
			"register_url": "https:\/\/{your-subdomain}.eventhq.co.uk\/bookings\/start\/event:surveying-trees-december-2015",
			"name":"Surveying Trees December 2015",
			"slug":"surveying-trees-december-2015",
			"location":"Richmond Park, Surrey",
			"summary":"This one-day course aimed at consultants will allow participants to build on knowledge gained on other courses, and will 					provide an understanding of trees and the techniques needed to survey them effectively. \r\n",
			"registration_opens":"2014-12-08T00:00:00+0100",
			"registration_closes":"2015-11-22T00:00:00+0100",
			"event_starts":"2015-12-02T00:00:00+0100",
			"event_ends":"2015-12-02T00:00:00+0100",
			"tags":["Surrey","Trees"],
			"attendee_count":"2",
			"test":false,
			"sold_out":false
		},
		{
			"id":"2187",
			"url":"https:\/\/{your-subdomain}.eventhq.co.uk\/api\/v1\/events\/view\/event:arboriculture-and-bats-how-to-use-a-fiberscope-october-2015",
			"register_url": "https:\/\/{your-subdomain}.eventhq.co.uk\/bookings\/start\/event:arboriculture-and-bats-how-to-use-a-fiberscope-october-2015",
			"name":"Arboriculture and Bats: How To Use A Fiberscope October 2015",
			"slug":"arboriculture-and-bats-how-to-use-a-fiberscope-october-2015",
			"location":"Richmond Park, Surrey",
			"summary":"This course follows on from the basic course; and will explore methods that can be used to look for evidence of bats with and without a bat licence and learn the appropriate use of fibrescopes.\r\n",
			"registration_opens":"2014-12-08T00:00:00+0100",
			"registration_closes":"2015-10-08T00:00:00+0100",
			"event_starts":"2015-10-28T00:00:00+0100",
			"event_ends":"2015-10-28T00:00:00+0100",
			"tags":[],
			"attendee_count":"200",
			"test":false,
			"sold_out":false
		}
	]
}
			

GET /api/events/count

Get a count of all events within your account. Accepts the same params and filters as the /api/events/index endpoint above except limit and page which are ignored if present.

Example API calls

Get a count of all events

GET /api/events/count/token:{your-token-here}
			

Get a count of all live events which start after the 1st January 2015

GET /api/events/count/token:{your-token-here}/f:live:1|event_starts >:2015-01-01
			

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
	"message":"success",
	"count":14
}
			

GET /api/events/view

Get details on a single Event

Example API calls

Get a detailed view of a single event

GET /api/events/view/token:{your-token-here}/event:surveying-trees-december-2015
			

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
	"message":"success"
	,"event":{
		"id":"2179",
		"register_url":"https:\/\/{your-subdomain}.eventhq.co.uk\/bookings\/start\/event:surveying-trees-december-2015",
		"name":"Surveying Trees December 2015",
		"slug":"surveying-trees-december-2015",
		"location":"Richmond Park, Surrey",
		"summary":"This one-day course aimed at consultants will allow participants to build on knowledge gained on other courses, and will provide an understanding of trees and the techniques needed to survey them effectively. \r\n",
		"registration_opens":"2014-12-08T00:00:00+0000",
		"registration_closes":"2015-11-22T00:00:00+0000",
		"event_starts":"2015-12-02T00:00:00+0000",
		"event_ends":"2015-12-02T00:00:00+0000",
		"tags":[],
		"products":[
		{
			"id":"547c8483-d81c-4723-b83d-2fb5c0a80002",
			"event_id":"2179",
			"event_days":[],
			"primary":false,
			"name":"Individual Membership",
			"description":"Individual Membership is &pound;30. Members receive a &pound;5 discount off of training courses (hence the cost of &pound;25)",
			"total_available":null,
			"admin_only":false,
			"max_order_per_attendee":"1",
			"vat_rate":null,
			"position":"1",
			"total_used":null,
			"published":true,
			"deleted":false,
			"deleted_date":null,
			"created":"2014-12-01T15:08:51+0000",
			"modified":"2014-12-01T15:08:51+0000",
			"sold_out":"0",
			"current_price":25,
			"prices":[
				{
					"value":"25.00",
					"until_end_of":null,
					"product_id":"547c8483-d81c-4723-b83d-2fb5c0a80002"
				}
			]
		},
		{
			"id":"547c8444-ff34-4870-b7bc-2fa0c0a80002",
			"event_id":"2179",
			"event_days:[],
			"primary":true,
			"name":"Member",
			"description":"",
			"total_available":null,
			"admin_only":false,
			"max_order_per_attendee":"1",
			"vat_rate":null,
			"position":"1",
			"total_used":"1",
			"published":true,
			"deleted":false,
			"deleted_date":null,
			"created":"2014-12-01T15:07:48+0000",
			"modified":"2014-12-01T15:07:48+0000",
			"sold_out":"0",
			"current_price":160,
			"prices":[
				{
					"value":"160.00",
					"until_end_of":null,
					"product_id":"547c8444-ff34-4870-b7bc-2fa0c0a80002"
				}
			]
		}
	}
]
			

Still need help? Contact Us Contact Us