Installation Need to Buy a Support License for the JSON API add-on? The Event Espresso JSON API add-on installs like any other WordPress plugin (). Once installed, just configure the settings, to your needs, in the WP Admin > Event Espresso > API Settings page of your Event Espresso powered WordPress website. Testing the JSON API To make sure the JSON API is working properly on your website, you add this to the end of your Event Espresso powered website’s URL: /espresso-api/v1/events/public.pretty_json Example: yoursite.com/espresso-api/v1/events/public.pretty_json Actual example from our testdrive website: If everything is configured properly, you will see something like this: JSON API Output Example API Codex The Event Espresso JSON API gives developers a complete API platform for directly accessing data event and attendee data securely and efficiently from outside your web server. All a developer needs to know about is the API Endpoint URL for your site. Example: AuthenticationPrivate Information To make most requests to the API, you will need to send a session key with each request in the URL. Eg: mysite.com/espresso-api/v1/events/qwer1234 (where “qwer1234” is the session key). To acquire a session key, send an HTTP POST/GET to {wordpress-site}/espresso-api/v1/authenticate with GET or POST parameters: “username” and “password” (which are a wordpress user’s username and password.) Eg: GET mysite.com/espresso-api/v1/authenticate?username=admin&password=3v3nt (NOTE: using GET on this endpoint is not recommended for production, as it is less secure than sending a POST) POST mysite.com/espresso-api/v1/authenticate with body: username:admin password:3v3nt On success, the response will look like: {"status":"OK","status_code":200,"body":{"session_key":"fwseljoxy5"}} On failure, the response will look like: {"status":"Bad username and password combination.","status_code":401} Public Information Event Espresso site admins can allow for some information to bepublicly available, thus not requiring authentication to access it. To enable this feature, they must select to “Allow Public API Access” on the Event Espresso API Settings page. To query for public information, there is no need to authenticate and retrieve a session key. Instead, simply use the string ‘public’ in place of a session key in all requests. Eg, mysite.com/espresso-api/v1/events/public. Please see the section titled “Permissions” for information on what information is publicly available when this feature is enabled. Response/Request Formats (xml, json,pretty_json) this API supports both JSON (default) and XML formats. To get a response back in XML, simply append “.xml” to any of the session key (eg, “mysite.com/espresso-api/v1/events/{session_key}.xml?id__lt=10” or “mysite.com/espresso-api/v1/events/14/{session_key}.xml?). If you would like to have your JSON returned in a more readable, but less efficient, format, simply set the format to ‘pretty_json’ (eg,“mystei.com/espresso-api/v1/events/{session_key}.pretty_json?id__in=1,23,342) Request Methods (GET, POST, PUT, DELETE) According to RESTful principles, the HTTP request method sent to an endpoint dictates functionality in this API. Eg: sending the request method of DELETE on a request will be interpreted very differently by the API server than the same request using the PUT request method. In the following documentation, each endpoint is preceded by the HTTP request method that invokes that functionality. (Eg the title “GET /events” explains the functionality of sending a request to “/events” using the GET request method). If you are unable to send PUT or DELETE request methods, we have provided a workaround: in the body of your request, provide a parameter called ‘request_method’ and set its value to the desired request method. Eg, if you want to send a PUT request but are unable, send a POST request with the request parameters ‘request_method’:’PUT’ (and the usual ‘body’ parameterwith the json or xml to indicate what you want to update). Or if you want to send a DELETE request to /events/{id}/{sessionId}, send the following GET request /events/{id}/{sessionid}?request_method=DELETE. GETting with Query Parameters On all GET requests (eg, an HTTP GET request to mysite.com/espresso-api/v1/events,) you may add GET querystring variables to filter your results, eg mysite.com/espresso-api/v1/events?Datetime.event_start2012-04-23%2000:00:00. But, what if you want all events before April 23rd 2012? you’d like to use mysite.com/espresso-api/v1/events?Datetime.event_start<2012-04-23%2000:00:00, but that’s invalid HTTP querystring syntax. If you want to alter a query like that simply append ‘__lt’ to the querystring parameter and it will be interpreted as < (or “less than”). ie mysitecom/espresso-api/v1/events?Datetime.event_start__lt=2012-04-23%2000:00:00. The following operators are available: MySQL Operator String to Append to Query Parameter Example < __lt eg:mysite.com/espresso-api/v1/events?Datetime.event_start__lt=2012-04-23%2012:23:56 <= __lte eg: mysite.com/espresso-api/v1/events?Datetime.event_start__lte=2012-04-23%2012:23:56 > __gt eg: mysite.com/espresso-api/v1/events?Datetime.event_start__gte=2012-04-23%2012:23:56 >= __gte eg: mysite.com/espresso-api/v1/events?Datetime.event_start__gt=2012-04-23%2012:23:56 LIKE __like eg: mystie.com/esresso-api/v1/attendees?fname__like=%25Tim%25 (note that ‘%’ urlencoded is %25) IN __in eg: mysite.com/espresso-api/v1/registrations__in=234,432,345 You may also query based on most related models, as long as they are part of the response of the endpoint you’re currenlty querying. For example, Price is a related model of Event, and is always included on any query to Events. So if you want to find all events with a price of 12.00, you could do a query like mysite.com/espresso-api/v1/events/{session_key}?Price.amount=12.00. Further Examples: Example Request Description generated SQL for WHERE statementGET mysite.com/espresso-api/v1/events/{session_key}?name__like=%25party%25&description__like=%25all%20fun%25 Get all events where the name has a substring of ‘party’, and where the event description has the substring ‘all fun’ WHERE event_name LIKE ‘%party%’ AND event_desc LIKE ‘%all fun%’ GET mysite.com/espresso-api/v1/events/{session_key}?/events/{session_key}?Datetime.event_start__lt=2012-02-06%2012:23:56 get all events which start before february 6th 2012 WHERE Datetime.event_start < ‘2012-02-06%2012:23:56’ GET mysite.com/espresso-api/v1/registrations/{session_key}?Event.id__lt=5 get all registrations whose associated Event.id is less than 5 WHERE wp_events_detail < 5 POSTing (creating) with Temp Ids When POSTing info to a resource to create a new one (eg, posting registration info to espresso-api/v1/registrations/{sessionId}) your soon-to-be-created resource will not yet have an ID. Insetad, you must provide a temporary ID. Temporary IDs are strings starting with “temp-” andfollowing by any unique string (eg, “temp-my-new-reg”, “temp-123”, “temp-a”, etc). Why use Temporary Ids (instead of just ignoring the ID field)? Temporary Ids are handy when creating multiple related resources, and thus allow you to refer to the soon-to-be-created resources. Eg, creating 2 registrations on a single new transaction. Each registration would have their own unique Temp Id, (eg “temp-reg1” AND “temp-reg2″”) and each would have their nested Transaction’s id set to a single Temp Id (eg “temp-transaction-for-both-regs”). Example request: { "Registrations":[ { "id":"temp-reg1", "status":"not_approved", "date_of_registration":"2012-12-10 16:12:31", "final_price":10, "code":"1-50c67a6f172e1", "url_link":null, "is_primary":true, "is_group_registration":true, "is_going":true, "is_checked_in":false, "Transaction":{"id":"temp-transaction-for-both-regs" } }, { "id":"temp-reg2", "status":"not_approved", "date_of_registration":"2012-12-10 16:12:31", "final_price":10, "code":"1-50c67a6f172e1", "url_link":null, "is_primary":false, "is_group_registration":false, "is_going":true, "is_checked_in":false, "Transaction":{ "id":"temp-transaction-for-both-regs" } } ] } Query Limits By default, all queries will return a maximum of 50 primary items (‘primary items’ meaning the item requested, not related items. So on a request to mysite.com/espresso-api/v1/events/public that would be ‘events’, not the related datetimes, venues, or categories, etc.). If you wish to change this limit, provide another query parameter called ‘limit’. Eg, mysite.com/espresso-api/v1/events/{sessionkey}?limit=75 ormysite.com/espresso-api/v1/attendees/{sessionkey}?id__gt=50&limit=50 (the will request the first 75 items, the second will get the first 50 items with an ID higher than 50, which might be a convenient way of doing pagination). The query limit parameter used on regular endpoints for GETs is different from the query limit on cached results. Please see the section on ‘caching’. There is currently no ‘offset’ parameter for query limits on regular endpoints (ie, mysite.com/espresso-api/v1/events/{sessionkey}?limit=150,50 will NOT work). This feature is planned in future versions of the API. Endpoints The API data structure is independent of the Event Espresso MySQL database structure (ie, the data is organized differently. Eg, in the Event Espresso 3.1 database, there is no concept of ‘registration’ or ‘transaction’, these are simply part of an attendee record.) Here is an which shows how the data is organized and generally which resources contain what information. Events Currently, youmay get events and filter them GET /events gets all events, and their related datetimes, prices, promocodes, categories, and venues. For efficiency, the related registrations are not returned on this endpoint. For those, see GET /events/{id}registrations. Also, by default only active events are returned (ie, mysite.com/espresso-api/v1/events/{session_key} will return the exact same results as mysite.com/espresso-api/v1/events/{session_key}?status_in=active,draft,secondary/waitlist), but you can of course override this by supplying a different value for the “status” parameter. The following will all be part of the response, and may be used in querying id: the event’s DB id, eg 12 name: name of the event, eg “mike party” description: description of the event, eg “all you can ease pizza!” Datetimes: list of tuples like GET /datetimes Venues: list of tuples of the venues, GET /venues metadata: list of tuples,eg “metadata”:{“id”:23,”{meta_key}”,”{meta_value}”, “date_added”:”2012-03-2323:33:44”} status: string. one of 'active', 'inactive', 'pending', 'draft', 'secondary/waitlist', 'ongoing', 'denied', 'deleted' limit: integer group_registrations_allowed: boolean group_registrants_max: integer active: boolean member_only: boolean Categories: lsit of tuple like /categories Promocodes: list of tuples like /promocodes virtual_url: string virtual_phone: string phone: string Example Request (gets all events submitted before march 24th 2012 by user with id 1) mysite.com/espresso-api/v1/events/{session_key}?submitted__lte=2012-03-24%2012:23:56&user_id=1 Example Response { "status":"OK", "status_code":200, "body":{ "Events":[ { "id":"1", "name":"Jump Til You Drop", "description":"This is a test. <!--more-->\r\n\r\n[ESPRESSO_VENUE]", "status":"active", "limit":"500", "group_registrations_allowed":true, "group_registrations_max":"10","active":true, "member_only":false, "virtual_url":"", "call_in_number":"", "phone":"", "metadata":{ "default_payment_status":"", "venue_id":"0", "additional_attendee_reg_info":"3", "add_attendee_question_groups":{ "1":"1", "11":"11" }, "date_submitted":"June 18, 2012", "event_hashtag":"", "event_format":"", "event_livestreamed":"", "":"" }, "Datetimes":[ { "id":"120", "is_primary":true, "event_start":"2012-10-31 08:00:00", "event_end":"2012-10-31 17:00:00", "registration_start":"2012-07-01 00:01:00", "registration_end":"2012-10-31 23:59:00", "limit":"0","tickets_left":"500" } ], "Venues":[ ], "Categories":[ { "id":"1", "name":"Test category", "identifier":"test-cat", "description":"My category content", "user":"1" } ], "Promocodes":[ ], "Prices":[ { "id":"155.0", "name":"Admission T-shirt", "amount":"2.00", "description":null, "limit":"500", "remaining":999999, "start_date":null, "end_date":null, "Pricetype":{ "id":1, "name":"Base Price", "is_member":false, "is_discount":false,"is_tax":false, "is_percent":false, "is_global":true, "order":0 } }, { "id":"155.2", "name":"Members Admission", "amount":"2.00", "description":null, "limit":"500", "remaining":99999, "start_date":null, "end_date":null, "Pricetype":{ "id":4, "name":"Member Price", "is_member":true, "is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } }, { "id":"154.0", "name":"General Admission","amount":"0.01", "description":null, "limit":"500", "remaining":999999, "start_date":null, "end_date":null, "Pricetype":{ "id":1, "name":"Base Price", "is_member":false, "is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } }, { "id":"154.2", "name":"Members Admission", "amount":"0.01", "description":null, "limit":"500", "remaining":99999, "start_date":null, "end_date":null, "Pricetype":{ "id":4,"name":"Member Price", "is_member":true, "is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } } ] } ] } } GET /events/{id} retrieves a single event and its related , where {id} is the id of the event you want to retrieve. Accepts no querystring variables. Example Request: mysite.com/espresso-api/v1/events/123/{session_key} Example Response: { "status":"OK", "status_code":200, "body":{ "Event":{ "id":"1", "name":"Jump Til You Drop", "description":"This is a test. <!--more-->\r\n\r\n[ESPRESSO_VENUE]", "status":"active", "limit":"500", "group_registrations_allowed":true, "group_registrations_max":"10", "active":true, "member_only":false,"virtual_url":"", "call_in_number":"", "phone":"", "metadata":{ "default_payment_status":"", "venue_id":"0", "additional_attendee_reg_info":"3", "add_attendee_question_groups":{ "1":"1", "11":"11" }, "date_submitted":"June 18, 2012", "event_hashtag":"", "event_format":"", "event_livestreamed":"", "":"" }, "Datetimes":[ { "id":"120", "is_primary":true, "event_start":"2012-10-31 08:00:00", "event_end":"2012-10-31 17:00:00", "registration_start":"2012-07-01 00:01:00", "registration_end":"2012-10-31 23:59:00", "limit":"0", "tickets_left":"500" } ], "Venues":[ ], "Categories":[{ "id":"1", "name":"Test category", "identifier":"test-cat", "description":"My category content", "user":"1" } ], "Promocodes":[ ], "Prices":[ { "id":"155.0", "name":"Admission T-shirt", "amount":"2.00", "description":null, "limit":"500", "remaining":999999, "start_date":null, "end_date":null, "Pricetype":{ "id":1, "name":"Base Price", "is_member":false, "is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } }, { "id":"155.2", "name":"MembersAdmission", "amount":"2.00", "description":null, "limit":"500", "remaining":99999, "start_date":null, "end_date":null, "Pricetype":{ "id":4, "name":"Member Price", "is_member":true, "is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } }, { "id":"154.0", "name":"General Admission", "amount":"0.01", "description":null, "limit":"500", "remaining":999999, "start_date":null, "end_date":null, "Pricetype":{ "id":1, "name":"Base Price", "is_member":false,"is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } }, { "id":"154.2", "name":"Members Admission", "amount":"0.01", "description":null, "limit":"500", "remaining":99999, "start_date":null, "end_date":null, "Pricetype":{ "id":4, "name":"Member Price", "is_member":true, "is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } } ] } } } GET /events/{id}/registrations returns all registrations for event with {id}. Output is identical to GET/registrations?Event.id={id} Registrations GET /registrations gets all registrations, and their related attendee, transaction, event, price (and pricetype), and datetime. id id of registration (float NOT int) Event: tuple like topleve GET /event Attendee: tuple like toplevel GET /attendees Transaction: tuple like topleve GET transaction Datetime: tuple like toplevel GET /datetimes Price: tuple like GET /prices status: ‘approved’,’cancelled’,’not_approved’,’pending’ date_of_registration: datetime like ‘2012-03-23 23:12:53” final_price: string like “20.34” code: string url_link: string is_primary: boolean is_group_registration: string true or false is_going: boolean is_checked_in: boolean Example Request: mysite.com/espresso-api/v1/registrations/{session_key}?Attendee.firstname__like=%25Smith%25&is_checked_in=1 //note that '%' urlencoded is %25 Example Response { "status":"OK", "status_code":200, "body":{ "Registrations":[ {"id":"9273", "status":"approved", "date_of_registration":"2012-10-22 21:14:04", "final_price":"0.01", "code":"1-50860b7c7d415", "url_link":null, "is_primary":true, "is_group_registration":false, "is_going":true, "is_checked_in":false, "Event":{ "id":"1", "name":"Jump Til You Drop", "description":"This is a test. <!--more-->\r\n\r\n[ESPRESSO_VENUE]", "status":"active", "limit":"500", "group_registrations_allowed":true, "group_registrations_max":"10", "active":true, "member_only":false, "virtual_url":"", "call_in_number":"", "phone":"", "metadata":{ "default_payment_status":"", "venue_id":"0","additional_attendee_reg_info":"3", "add_attendee_question_groups":{ "1":"1", "11":"11" }, "date_submitted":"June 18, 2012", "event_hashtag":"", "event_format":"", "event_livestreamed":"", "":"" } }, "Attendee":{ "id":"9273", "firstname":"aaa", "lastname":"aaa", "address":"", "address2":"", "city":"", "state":"", "country":"", "zip":"", "email":"", "phone":"" }, "Transaction":{ "id":"9273", "timestamp":"2012-10-22 21:14:04", "total":"536.66", "paid":"0.00", "status":"pending","details":null, "tax_data":null, "session_data":null }, "Datetime":{ "id":"120", "is_primary":true, "event_start":"2012-10-31 08:00:00", "event_end":"2012-10-31 17:00:00", "registration_start":"2012-07-01 00:01:00", "registration_end":"2012-10-31 23:59:00", "limit":"0", "tickets_left":"500" }, "Price":{ "id":"154.0", "name":"General Admission", "amount":"0.01", "description":null, "limit":"500", "remaining":999999, "start_date":null, "end_date":null, "Pricetype":{ "id":1, "name":"Base Price", "is_member":false, "is_discount":false,"is_tax":false, "is_percent":false, "is_global":true, "order":0 } } }, { "id":"9274", "status":"approved", "date_of_registration":"2012-10-22 21:14:04", "final_price":"0.01", "code":"1-50860b7c7d415", "url_link":null, "is_primary":true, "is_group_registration":false, "is_going":true, "is_checked_in":false, "Event":{ "id":"1", "name":"Jump Til You Drop", "description":"This is a test. <!--more-->\r\n\r\n[ESPRESSO_VENUE]", "status":"active", "limit":"500", "group_registrations_allowed":true, "group_registrations_max":"10", "active":true, "member_only":false, "virtual_url":"","call_in_number":"", "phone":"", "metadata":{ "default_payment_status":"", "venue_id":"0", "additional_attendee_reg_info":"3", "add_attendee_question_groups":{ "1":"1", "11":"11" }, "date_submitted":"June 18, 2012", "event_hashtag":"", "event_format":"", "event_livestreamed":"", "":"" } }, "Attendee":{ "id":"9274", "firstname":"aaa", "lastname":"aaa", "address":"", "address2":"", "city":"", "state":"", "country":"", "zip":"", "email":"", "phone":"" }, "Transaction":{"id":"9274", "timestamp":"2012-10-22 21:14:04", "total":"536.66", "paid":"0.00", "status":"pending", "details":null, "tax_data":null, "session_data":null, }, "Datetime":{ "id":"120", "is_primary":true, "event_start":"2012-10-31 08:00:00", "event_end":"2012-10-31 17:00:00", "registration_start":"2012-07-01 00:01:00", "registration_end":"2012-10-31 23:59:00", "limit":"0", "tickets_left":"500" }, "Price":{ "id":"154.0", "name":"General Admission", "amount":"0.01", "description":null, "limit":"500", "remaining":999999, "start_date":null, "end_date":null,"Pricetype":{ "id":1, "name":"Base Price", "is_member":false, "is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } } } ] } } GET /registrations/{id} gets a single registration and its related attendee, transaction, event, datetime, and price (and pricetype), where {id} is the registration_id. It does not accept query string variables Example Request mysite.com/espresso-api/v1/registrations/9273/{session_key}? Example Response { "status":"OK", "status_code":200, "body":{ "Registration":{ "id":1.1, "status":"approved", "date_of_registration":"2012-12-10 16:12:31", "final_price":10, "code":"1-50c67a6f172e1", "url_link":null, "is_primary":true,"is_group_registration":true, "is_going":true, "is_checked_in":true, "Event":{ "id":1, "code":"1-50c679c10fcf0", "name":"testevent1", "description":"", "status":"active", "limit":999999, "group_registrations_allowed":true, "group_registrations_max":3, "active":true, "member_only":false, "virtual_url":"", "call_in_number":"", "phone":"", "metadata":{ "default_payment_status":"", "venue_id":"", "additional_attendee_reg_info":3, "add_attendee_question_groups":{ "1":"1" }, "date_submitted":"December 11, 2012", "event_hashtag":"", "event_format":"", "event_livestreamed":"", "":"" }}, "Attendee":{ "id":1, "firstname":"wef", "lastname":"few", "address":"", "address2":"", "city":"", "state":"", "country":"", "zip":"", "email":"michael@eventespresso.com", "phone":"" }, "Transaction":{ "id":1, "timestamp":"2012-12-10 16:12:31", "total":10, "amount_paid":0, "status":"pending", "details":null, "tax_data":null, "session_data":null, "payment_gateway":"Check" }, "Datetime":{ "id":21, "is_primary":true, "event_start":"2012-12-11 09:00:00", "event_end":"2012-12-10 17:00:00", "registration_start":"2012-12-09 00:01:00", "registration_end":"2016-12-21 23:59:00", "limit":999999,"tickets_left":999983 }, "Price":{ "id":0, "name":"Unknown", "amount":10, "description":null, "limit":9999999, "remaining":999999, "start_date":null, "end_date":null, "Pricetype":{ "id":1, "name":"Base Price", "is_member":false, "is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } } } } } GET/POST/PUT /registrations/{id}/checkin Marks the registration with {id} as checked-in. If that registration is already checked in, checks in another registration which has the same attendee and event. Returns the list of registrations that were checked in. Accepts the following query string parameters: ignorePayment: boolean quantity: (integer), using a quantityof 3 is equivalent to issuing the same checkin request 3 times. Example Request GET/POST/PUT mysite.com/espresso-api/v1/registrations/9273/checkin{session_key} Example Response Returns the updated registrations just like GET /registrations (not a single registration, for reasons mentioned above) Note: if the payment has not been verified, the registration will not be marked as checked-in, and the following response will be sent: {"status":"Checkin denied. Payment not complete and 'ignorePayment' flag not set.","status_code":500} GET/POST/PUT /registrations/{id}/checkout Marks the registration with {id} as checked-out. If that registration is already checked out, checks out another registration which has the same attendee and event. Returns the list of registrations that were checked out. Accepts the following query string parameters: quantity: (integer), using a quantity of 3 is equivalent to issuing the same checkout request 3 times. Example Request GET/POST/PUTmysite.com/espresso-api/v1/registrations/9273/checkout/{session_key} Example Response Returns a list of updated registrations just like GET /registrations (not a single registration, for reasons mentioned above) POST/PUT /registrations Creates or updates the listed registrations. The request should be sent in an almost identical format as what’s received from GET /registrations When submitting this request to create/update the listed registrations, currently ALL fields received on GET /registrations must also be submitted. (There are plans to have some fields set to default values, and to not require all fields on updates, but those are not yet implemented). Example Request POST /registrations //with POST form data/post parameter 'body' containing all the json/xml received in the 'body' section of the response from GET /registrations (ie, don't include 'status' or 'status_code') body:{"Registrations":[ { "id":"temp-new-one", "status":"not_approved", "date_of_registration":"2012-12-10 16:12:31", "final_price":10, "code":"1-50c67a6f172e1", "url_link":null, "is_primary":true, "is_group_registration":false, "is_going":true, "is_checked_in":true, "Event":{ "id":1, "code":"1-50c679c10fcf0", "name":"testevent1", "description":"", "status":"active", "limit":999999, "group_registrations_allowed":true, "group_registrations_max":3, "active":true, "member_only":false, "virtual_url":"", "call_in_number":"", "phone":"", "metadata":{ "default_payment_status":"", "venue_id":"", "additional_attendee_reg_info":3, "add_attendee_question_groups":{ "1":"1" }, "date_submitted":"December 11,2012", "event_hashtag":"", "event_format":"", "event_livestreamed":"", "":"" } }, "Attendee":{ "id":"temp-new-one2", "firstname":"fromapi", "lastname":"fromapiman", "address":"", "address2":"", "city":"", "state":"", "country":"", "zip":"", "email":"michael@eventespresso.com", "phone":"" }, "Transaction":{ "id":"temp-new-one3", "timestamp":"2012-12-10 16:12:31", "total":10, "amount_paid":0, "status":"pending", "details":null, "tax_data":null, "session_data":null, "payment_gateway":"Check" }, "Datetime":{ "id":20, "is_primary":true, "event_start":"2012-12-11 09:00:00", "event_end":"2012-12-10 17:00:00", "registration_start":"2012-12-09 00:01:00", "registration_end":"2016-12-21 23:59:00", "limit":999999, "tickets_left":999984 }, "Price":{ "id":12, "name":"GeneralAdmission", "amount":10, "description":null, "limit":9999999, "remaining":999999, "start_date":null, "end_date":null, "Pricetype":{ "id":1, "name":"Base Price", "is_member":false, "is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } } } ] } The above request will create a new Registration, new Attendee, and new Transaction. It will also associate the new Registration with Price with ID 12, with the Event with ID 1, and the Datetime with ID 20. It will also simultaneously update each of those related models: the Price, Event and Datetime (in case you’d rather not update those related models, in teh future you will only need to provide their IDs, but not all their attributes). Note that in order to create a registration (or any other related model) you simply provide a ‘temporary id’ titled ‘temp-{whatever}’, (the above registration’s temporary id is ‘temp-new-one’, theattendee’s is ‘temp-new-one2’. Please see the above section on ‘POSTing using Temporary IDs’ for more info). If you instead wanted to simply update a registration with ID {id}, then you’d provide it as the ID instead of the above temporary id. When the request is completed, the newly-created registrations (and their associated Attendee, Transaction, Event, Price and Datetime) will be returned in exactly the same format as GET /registrations. PUT /registrations/{id} Updates the registration (and associated Attendee, Transaction, Event, Datetime, and Price) with id {id}. The request’s body should be in the same format as GET /registrations/{id} (except without the ‘status’ and ‘status_code’), and the updated registration (and related models) will be returned. Example Request { "Registration":{ "id":1.1, "status":"not_approved", "date_of_registration":"2012-12-10 16:12:31", "final_price":10, "code":"1-50c67a6f172e1", "url_link":null,"is_primary":true, "is_group_registration":false, "is_going":true, "is_checked_in":true, "Event":{ "id":1, "code":"1-50c679c10fcf0", "name":"testevent1", "description":"", "status":"active", "limit":999999, "group_registrations_allowed":true, "group_registrations_max":3, "active":true, "member_only":false, "virtual_url":"", "call_in_number":"", "phone":"", "metadata":{ "default_payment_status":"", "venue_id":"", "additional_attendee_reg_info":3, "add_attendee_question_groups":{ "1":"1" }, "date_submitted":"December 11, 2012", "event_hashtag":"", "event_format":"", "event_livestreamed":"", "":"" } }, "Attendee":{ "id":1,"firstname":"wef", "lastname":"few", "address":"", "address2":"", "city":"", "state":"", "country":"", "zip":"", "email":"michael@eventespresso.com", "phone":"" }, "Transaction":{ "id":1, "timestamp":"2012-12-10 16:12:31", "total":10, "amount_paid":0, "status":"pending", "details":null, "tax_data":null, "session_data":null, "payment_gateway":"Check" }, "Datetime":{ "id":20, "is_primary":true, "event_start":"2012-12-11 09:00:00", "event_end":"2012-12-10 17:00:00", "registration_start":"2012-12-09 00:01:00", "registration_end":"2016-12-21 23:59:00", "limit":999999, "tickets_left":999984 }, "Price":{ "id":0, "name":"Unknown", "amount":10,"description":null, "limit":9999999, "remaining":999999, "start_date":null, "end_date":null, "Pricetype":{ "id":1, "name":"Base Price", "is_member":false, "is_discount":false, "is_tax":false, "is_percent":false, "is_global":true, "order":0 } } } } The above request will update registration with id 1.1, and update all it’s fields to the supplied values. Note: it will also update the related Attendee, Transaction, Event, Datetime and Price (in future you will only need to provide the ID). Currently, if you don’t want to update the related models, don’t provide them at all. For example, the following request updates only registration information (and leave related models untouched). { "Registration":{ "id":1.1, "status":"not_approved", "date_of_registration":"2012-12-10 16:12:31","final_price":10, "code":"1-50c67a6f172e1", "url_link":null, "is_primary":true, "is_group_registration":false, "is_going":true, "is_checked_in":true } } Attendees GET /attendees Gets all attendees and their related registrations and events id int firstname: string lastname: string address: string address2: string city: string state: string country: string zip: string email: string phone: string comments: string (in Event Espresso 3.1, this will always be blank) notes: string (in Event Espresso 3.1, this will always be blank) Registrations: list of tuples, like toplevel results of GET /registrations Events: list of tuples, like toplevel results of GET /events Unfinished Endpoints These are endpoints that are not yet finished. However, you may want to know their response format when querying a related object, as they will eb part of teh response. For example, although the endpoint espresso-api/v1/prices/{session_key} is notyet accessible, prices are returned with every request to espresso-api/v1/events/{session_key}, and so you’d probably like to know what attributes to expect in responses and which are available for querying. Prices GET /prices all prices. id: float (not int!). eg: 1.1, 1.2, 1.3, OR 1, 1234, etc. Event: event like GET /events Pricetype: tuple like GET /pricetypes amount: string, eg: “10.2” name: string description: string limit: int remaining: int start_date: date end_date: date Note: if a price is returned as a related object of the one you queried (eg, you queried “events”, and got a related “price”) then we avoid infinite recursion by not returning an “Event” object nested inside the “price” object. Price Types GET /pricetypes In 3.1, there are 4 immutable price types: “Base Price”,”Surcharge Amount”,”Surcharge Percent”, and “Member Price”, which are stored in the code and not the databaseid: int name: string is_member: boolean is_discount: boolean is_tax: boolean is_percent: boolean is_global: boolean order: boolean Categories GET /categories gets all categories id: int name: string identifier :string description: string user: int (creator) Promo codes GET /promocodes Gets all promo (discount) codes id: int coupon_code: string amount: string (like "10.23") use_percentage: boolean description: string apply_to_each_attendee: boolean quantity_available: int expiration_date: date user: int (creator's wordpress id) Date times GET /datetimes gets all date/times. in 3.1, this is a combination of times in events_details and events_start_end tables id: int Event: tuple like GET /events is_primary: boolean event_start: datetime event_end: datetime registration_start: datetime registration_end: datetime limit: int tickets_left: int Venues GET /venues Gets all venuesid: int name: string identifier: string address: string address2: string city: string state: string zip: string country: string metas: key-values like “metas”:{“{meta_key}”:{meta_value},....} user: int Transactions GET /transactions gets all transactions (in 3.1, this is a subset of columns from the /attendees table) id: string (NOT int) timestamp: datetime total: decimal like 20.35 amount_paid: decimal status: one of “complete”,”open”,”pending” details: tuples like {“{meta_key}”:{value}} tax_data: tuples like {“{meta_key}”:{value}} session_data: tuples like {“{meta_key}”:{value}} Registrations: tuple like GET /registrations payment_gateway: string (indicating how the transaction was paid) Caching and Counting If you want to optimize your api client, you can utilize Event Espresso’s internal caching on any query. This is useful is you need to run a large query (eg, mysite.com/espresso-api/v1/registrations/{sessionkey}?limit=1000) which could potentially overburdenthe server, you want to get a count of items, or you want to implement pagination. To do so, issue your query with an added query parameter of ‘cache_result’ (eg: mysite.com/espresso-api/v1/events/{session_key}?id__gt=10&limit=500&cache_result=true). You will receive a response with a body containing the count of how many objects would be returned, an a cached_result_key like the following: "count":16,"cached_result_key":"mafvjm903a59ms9schb2yglmysouw4sv72orjyao" Instead of sending the entire response, we’ve just sent you a count of how many objects would be returned, and internally cached the result. To access that cache, send a query to {wordpress_site}/espresso-api/v1/cachedresults/{cached_result_key}/{session_key} This will return a response exactly like your original query would have had you not added the ‘cache_result’ query parameter. Also, when querying the cache you may add a special ‘limit’ query parameter to limit how much of the response is sent. Eg:{wordpress_site}/espresso-api/v1/cachedresults/{cached_result_key}/{session_key}?limit=10 which will only return the first 10 objects. Just like the MYSQL ‘limit’ clause, you can also add a second value to ‘limit’ to use an offset and limit. Eg ‘?limit=30,15’ will return 15 objects starting at the 30th one. Permissions The following users have permission to access the following resources. Public users can never update or create any resources, but they do have permissions to view certain resources, when “Public API Access” is enabled (Note: some of these roles are in the Event Espresso Permissions and Permission Pro plugins) Version 2.1.x+ permissions Integration with the Roles & Permission plugins (basic and pro) was significantly improved in this version. Basically, users should have access to the exact same resources via the API as they do via the normal web interface. E.g., if an Event Manager has permission to edit only events they create from wp-admin and only permission to viewonly active events on the website’s frontend event-list page, then in the JSON API when they submit a request to mysite.com/espresso-api/v1/events/{session_key}?editable_only=true then they should only see their events, and a request to mysite.com/espresso-api/v1/events/{session_key}?editable_only=false then they should see all active events (see below for a description of the “editable_only” query parameter added in version 2.1.0). Also, the Roles & Permissions “Minimum Page Permissions” setting also applies users’ permissions in the JSON API. E.g., if you set the “Minimum Page Permission” for “Event/Attendee Listings Page” to “Master Admin”, then Event Managers and Regional Managers won’t be able to see either the Event Espresso Event Listing Page, or access mysite.com/espresso-api/v1/events/{session_key}. Resource R&P associated “Minimum Page Permission” Public Event Managers Regional Manager Event Master Admins & WP Admins View Edit View Edit View Edit View Edit eventsEvent/Attendee Listings Page active only none all active or owned owned all active, owned, or in region owned or in region all all venues Venue Manager Page all none all all all all all all categories Categories Page all none all all all all all all datetimes Event/Attendee Listings Page all none all for owned events all for events owned & in region all all prices Event/Attendee Listings Page all non-member prices none all for events owned all for events owned & in region all all pricetypes Event/Attendee Listings Page all non-member prices none all all all all all all registrations Event/Attendee Listings Page none none for events owned for events owned for events owned & in region for events owned & in region all all attendees Event/Attendee Listings Page none none for registrations for events owned for registrations for events owned for registrations for events owned & in region for registrations for events owned & in region all all transactions Event/Attendee Listings Page nonenone for registrations for events owned for registrations for events owned for registrations for events owned & in region for registrations for events owned & in region all all answers Event/Attendee Listings Page none none for registrations for events owned for registrations for events owned for registrations for events owned & in region for registrations for events owned & in region all all promocodes Discounts Page none none all all all all all all As of the JSON API plugin version 2.1, the query parameter ‘editable_only’ is available, accepting either ‘true’ or ‘false’ as values. It can be added to any GET request in order to filter out any results the current user CANNOT edit. For example, if you wanted to only see all the events the current user can edit, you could send a request like mysite.com/espresso-api/v1/events/{session_key}?editable_only=true. Also, there is a setting titled “Show API Users Data They Can’t Edit” in the JSON API Settings page (when the Roles&Permissionsadd-on is also active) which sets the default for this query parameter. Version 2.0.x permissions (This version only provided limited support of Roles an Permissions. E.g., Event Managers could use the API to view events they normally didn’t have permission to see.) Resource Public Event Managers Regional Manager Event Master Admins Admin events only active and public events yes yes yes yes venues yes yes yes yes yes categories yes yes yes yes yes datetimes yes yes yes yes yes venues yes yes yes yes yes prices yes yes yes yes yes pricetypes yes yes yes yes yes registrations no yes yes yes yes attendees no yes yes yes yes transactions no yes yes yes yes answers no yes yes yes yes promocodes no yes yes yes yes Status Codes Along with each response, there is both a ‘status’ and a ‘status_code’. These status codes should more-or-less correspond to normal . They are as follows: Status Code Status Details 200 OK Your request was successfully processed. If you requested an object, it shouldhave been returned in the ‘body’ attribute. If you did a PUT, POST, or DELETE, it should have succeeded, and the updated/created/deleted object should have been returned in the ‘body’ parameter 400 {various messages} something about your request was illegal. You probably did a GET with an illegal query parameter 403 You are not authorized to access that endpoint Your session has probably expired and you need to re-authenticate/login. It’s also possible that you simply do not have sufficient permissions to access that specific endpoint. Eg: if you’re logged in as a event manager and only have event ID 123 assigned to you, then you can’t update event 987 and will get this same response. 404 Request is ok, but there is no object of specified type with id: {id} You made a request (like GET, PUT, or DELETE) on a specific resource (eg, /events/13), but that resource didn’t exist. Your request would have worked if the resource existed 412 {various messages} Your request was syntacticallycorrect and all, but some precondition failed before your request could be fully processed as you wanted. Example: you tried to check a registrant into an event using /registrations/13/checkin, but they hadn’t paid yet. Capice? 500 {various messages} Some internal error occured. Your request was fine but our server software just died for some reason. If the response is specifically “Endpoint not yet implemented” then we just haven’t finished working on that endpoint. Hassle Event Espresso to get it implemented. Code Examples Here are some examples of code that uses the API. Summary and Link Description PHP code that fetches all upcoming events and displays them. Can be run from any domain. PHP and HTML code that fetches all upcoming events and displays them in a calendar. Can be run from any domain. PHP code that fetches all past evens and displays them. Can be run from any domain. PHP code that fetches all upcoming events, caches them, and displays them. Using caching can speed upyour app, but requires a few more lines of code. Can be run from any domain. PHP code that fetches all past events, caches them, and displays them. Using caching can speed up your app, but requires a few more lines of code. Can be run from any domain. Future Developments POST /events (create new event) /events/{id}/questions POST /events/{id}/attendees GET/questions/{id}/answer …etc Need to Buy a Support License for the JSON API add-on?