Skip to main content

REST API Guide

Events Manager has a REST API for events, locations, tickets, bookings, categories and tags. It is part of the free plugin and runs on the WordPress REST API, so it needs no setup beyond a user to authenticate as. Events Manager Pro adds routes of its own for coupons, transactions, booking forms, attendance and RSVP.

This page gets you to a working request and explains the parts that differ from the WordPress core API. For every endpoint, parameter and response field, use the generated endpoint reference.

Before you start

You need a WordPress user with the capabilities for what you want to do, pretty permalinks enabled (so /wp-json/ resolves), and HTTPS on any site reachable from the internet.

Base URL and namespaces​

All routes sit under your site's REST root, which is /wp-json/ on a standard install.

NamespacePluginBase URL
events-manager/v1Events Managerhttps://example.com/wp-json/events-manager/v1
events-manager-pro/v1Events Manager Pro Prohttps://example.com/wp-json/events-manager-pro/v1

The core resources are:

RouteMethodsWhat it is
/eventsGET, POSTList or create events
/events/{id}GET, PATCH, DELETEOne event
/events/{id}/availabilityGETSpaces left, per event and per ticket
/events/{id}/ticketsGET, POSTAn event's tickets
/tickets/{id}GET, PATCH, DELETEOne ticket
/locations, /locations/{id}GET, POST, PATCH, DELETELocations
/locations/countries, /regions, /states, /townsGETThe places your locations are in, for building filters
/bookingsGET, POSTList or create bookings
/bookings/{id}GET, PATCH, DELETEOne booking
/bookings/{id}/statusPOSTApprove, reject or cancel a booking
/categories, /tags and /{id}GET, POST, PATCH, DELETEEvent categories and tags
/mediaPOSTUpload an image to use as a featured image

Updates use PATCH, and you send only the fields you want to change.

Authentication​

Every route requires a logged-in user, including the ones that read public events. A request with no credentials gets a 401 response. There are three ways to authenticate.

Application passwords​

This is the method to use for scripts and server-to-server integrations. Application passwords are a WordPress core feature.

  1. Log in as the user the integration should act as, and go to Users then Profile.

  2. Under Application Passwords, type a name for the integration and click Add New Application Password.

  3. Copy the password shown. WordPress displays it once.

  4. Send it with the username as HTTP Basic authentication on every request.

curl --user "apiuser:xxxx xxxx xxxx xxxx xxxx xxxx" \
https://example.com/wp-json/events-manager/v1/events

WordPress only offers application passwords over HTTPS, or on a site whose environment type is local. Create a dedicated user with the lowest role that covers the job, so that revoking the integration doesn't affect a person's account.

OAuth (Bearer tokens)​

Events Manager includes an OAuth 2.0 server, built for connecting AI assistants. An access token it issues is sent as Authorization: Bearer <token> and works on the events-manager/v1 and events-manager-pro/v1 namespaces as well as the MCP endpoint. It is rejected with 403 on every other REST route. Setting up a client and the approval screen are covered in AI and MCP.

JavaScript running in wp-admin or on the front end for a logged-in visitor can use the visitor's session. Send a REST nonce in the X-WP-Nonce header:

Pass a nonce to your script
wp_localize_script( 'my-script', 'myEvents', array(
'root' => esc_url_raw( rest_url( 'events-manager/v1/' ) ),
'nonce' => wp_create_nonce( 'wp_rest' ),
) );
my-script.js
const response = await fetch( myEvents.root + 'events?scope=future', {
headers: { 'X-WP-Nonce': myEvents.nonce },
} );
const { items, pagination } = await response.json();

Without the nonce, WordPress treats a cookie-authenticated request as logged out.

List events​

curl --user "apiuser:xxxx xxxx xxxx xxxx xxxx xxxx" \
"https://example.com/wp-json/events-manager/v1/events?scope=future&category=music&per_page=5"

The response has two keys, items and pagination:

{
"items": [
{
"name": "Harbor Lights Jazz Night",
"id": 42,
"type": "single",
"post_id": 118,
"slug": "harbor-lights-jazz-night",
"status": "publish",
"content": "...",
"bookings": { "enabled": true }
}
],
"pagination": { "total": 12, "total_pages": 3, "page": 1, "per_page": 5 }
}

The example is shortened. Each event also carries its dates and times, location, categories, tags and image.

The filters are a subset of the event search attributes used by shortcodes: search, scope, status, active_status, cancelled, active, category, tag, location, location_id, town, state, country, region, near, near_unit, near_distance, event_type, event_archetype, orderby, order, blog, private, private_only and timeslots.

By default a list contains published events only, and private events only if the user can read them. Add context=edit to include unpublished events. That takes effect only for a user with the edit_others_events capability.

The same request from PHP on another site:

List events with wp_remote_get()
$response = wp_remote_get(
add_query_arg( array( 'scope' => 'future', 'per_page' => 5 ), 'https://example.com/wp-json/events-manager/v1/events' ),
array(
'headers' => array(
'Authorization' => 'Basic ' . base64_encode( MY_EM_API_USER . ':' . MY_EM_API_PASSWORD ),
),
'timeout' => 15,
)
);
if ( is_wp_error( $response ) || wp_remote_retrieve_response_code( $response ) !== 200 ) {
return;
}
$data = json_decode( wp_remote_retrieve_body( $response ), true );
foreach ( $data['items'] as $event ) {
echo esc_html( $event['name'] ) . '<br />';
}

Define the two constants in wp-config.php. Don't put credentials in a theme or plugin file that is committed or shared.

Create an event​

Send a JSON body to POST /events. Two fields are required: event_name and event_start_date.

curl --user "apiuser:xxxx xxxx xxxx xxxx xxxx xxxx" \
--header "Content-Type: application/json" \
--request POST \
--data '{
"event_name": "Sunrise Beach Yoga",
"event_start_date": "2027-06-12",
"event_start_time": "07:00",
"event_end_time": "08:00",
"content": "<p>Bring a mat and water.</p>",
"post_status": "publish"
}' \
https://example.com/wp-json/events-manager/v1/events

With wp_remote_post():

Create an event with wp_remote_post()
$response = wp_remote_post( 'https://example.com/wp-json/events-manager/v1/events', array(
'headers' => array(
'Authorization' => 'Basic ' . base64_encode( MY_EM_API_USER . ':' . MY_EM_API_PASSWORD ),
'Content-Type' => 'application/json',
),
'body' => wp_json_encode( array(
'event_name' => 'Sunrise Beach Yoga',
'event_start_date' => '2027-06-12',
'event_start_time' => '07:00',
'event_end_time' => '08:00',
'content' => '<p>Bring a mat and water.</p>',
'post_status' => 'publish',
) ),
'timeout' => 15,
) );
if ( wp_remote_retrieve_response_code( $response ) === 201 ) {
$event = json_decode( wp_remote_retrieve_body( $response ), true );
$event_id = $event['id'];
}

A successful create returns 201 and the saved event. Things to know:

  • Field names match the event editor's form fields (event_name, event_start_date, event_timezone and so on), so the body is the same shape whether it comes from the form, the REST API or an AI tool. The reference lists them all, including tickets and recurrence rules.
  • event_end_date defaults to the start date. event_timezone defaults to the site's timezone. Set event_all_day to true for an all-day event.
  • post_status can be publish, pending, draft or private. A user without the publish_events capability can't publish, and the event is saved as pending.
  • If a featured_image can't be fetched, the event is still created and the response includes a warnings entry describing the problem.
  • To change the event later, send only the changed fields to PATCH /events/{id}.

How ids work​

Events and timeslots​

An event's id in the API is its Events Manager event id, not its WordPress post id. The post id is returned separately as post_id. It is a number for an ordinary event. An event with timeslots is addressed as event_id:timeslot_id, which is a string:

IdRefers to
42Event 42
42:7Timeslot 7 of event 42

Use the id exactly as the API returned it, in the URL and in request bodies. GET /events/42:7/availability returns the spaces left in that timeslot, and a booking for it sends "event_id": "42:7". Add timeslots=1 to an event list to get timeslots as separate items.

A booking's event_id field uses the same form, so a booking for a timeslot points back to the timeslot it was made for.

Bookings​

A booking has a numeric id and a 32-character uuid. Either works wherever a booking id goes in a URL:

GET /wp-json/events-manager/v1/bookings/315
GET /wp-json/events-manager/v1/bookings/5f2c9a4e8b1d4c7fa3e6d0b9c8a7f6e5

Prefer the uuid in anything a customer can see, such as a link in an email, because it can't be guessed from another booking's number.

Create a booking​

POST /bookings needs the event and the tickets, keyed by ticket id:

{
"event_id": 42,
"em_tickets": {
"96": { "spaces": 2 }
},
"booking_comment": "Window table if possible"
}

Get the ticket ids from GET /events/42/tickets. The booking belongs to the authenticated user and goes through the same validation as the booking form, so required form fields, ticket limits and availability all apply. With Events Manager Pro, a user who can manage the event's bookings can book on behalf of someone else by sending user_name and user_email. Pro

To change a booking's status, post the numeric status to /bookings/{id}/status:

curl --user "apiuser:xxxx xxxx xxxx xxxx xxxx xxxx" \
--header "Content-Type: application/json" \
--request POST \
--data '{ "status": 1, "send_email": true }' \
https://example.com/wp-json/events-manager/v1/bookings/315/status
StatusMeaning
0Pending
1Approved
2Rejected
3Cancelled
4Awaiting Online Payment
5Awaiting Payment

send_email defaults to true, which sends the same emails as changing the status in wp-admin.

Pagination​

List routes take page and per_page. per_page defaults to 20 and is capped at 100. limit is accepted as another name for per_page.

The totals come back twice: in the pagination object of the body, and in the X-WP-Total and X-WP-TotalPages response headers that WordPress clients expect. To read everything, request pages until page equals total_pages.

Permissions​

Authentication says who is asking. What they may do follows the same capabilities as wp-admin, checked for the route and then again for the specific item.

ActionCapability needed
Read events, locations, tickets, categories, tagsAny logged-in user. Private and unpublished items need the matching read or edit capability.
Create or update eventsedit_events, and edit_others_events for another user's event
Delete eventsdelete_events or delete_others_events
Create or update locationsedit_locations, and edit_others_locations for another user's location
Delete locationsdelete_locations or delete_others_locations
Create, update or delete ticketsmanage_bookings or manage_others_bookings, for that event
Read bookingsA user sees their own bookings. manage_bookings adds bookings for their own events, and manage_others_bookings adds all bookings.
Create a bookingAny logged-in user
Update or delete a booking, change its statusmanage_bookings or manage_others_bookings, for that booking's event
Create or update categories and tagsedit_event_categories
Delete categories and tagsdelete_event_categories
Upload mediaupload_files

Fields that only a booking manager may set, such as booking_status on a new booking, are dropped from requests by users without that capability. The request still succeeds.

Errors​

Errors use the WordPress REST format: a machine-readable code, a message, and the HTTP status in data.status.

{
"code": "em_api_event_not_found",
"message": "Event not found.",
"data": { "status": 404 }
}
StatusWhenExample code
400The data failed validationem_api_event_invalid, em_api_booking_status_invalid
401No valid credentialsrest_forbidden
403Authenticated, but not allowedem_api_event_forbidden, em_api_booking_forbidden
404No item with that idem_api_event_not_found, em_api_booking_not_found
409The action conflicts with existing dataem_api_ticket_has_bookings
500The save or delete failedem_api_event_save_failed

Validation errors also carry data.errors, a list with one message per problem, the same messages the form would show. Check code in your own code and show message to people.

Troubleshooting​

Every request returns 401​

Check that the request reaches WordPress with its Authorization header. Some Apache setups running PHP as CGI or FastCGI remove it. WordPress's own .htaccess rules pass it on, so re-save Settings then Permalinks to rewrite them. Then confirm the username is the login name, not the display name, and that the application password hasn't been revoked.

The Application Passwords section is missing from the profile​

The site is not on HTTPS, or a security plugin has switched application passwords off.

A request returns 404 with "rest_no_route"​

The path or the method is wrong. Updates use PATCH, not PUT. On a site without pretty permalinks, use https://example.com/?rest_route=/events-manager/v1/events.

An event I created doesn't appear in the list​

It was probably saved as pending or draft. Lists contain published events unless you ask with context=edit as a user who can edit others' events. Request the event directly with GET /events/{id} to see its status.