Read, create, change or delete guests from code, as the Guests screen does
Create guests from a booking form, keep a CRM in step with the roster, or add your own data to what the Guests screen receives, using the routes behind Benecaster → Guests and the hooks they fire.
The routes live under /wp-json/benecaster-guest-manager/v1. They are admin only (manage_options, through benecaster_rest_permission_admin(), with the X-WP-Nonce header) and exist only while Guest Manager is on for at least one show. No route takes a show: guests are the site’s, not a show’s, so the roster and its counts span every show.
GET /guests?search=&page=&per_page=→200 { items, total, page, per_page, pages }, A–Z by name,per_page20 by default and at most 100.searchmatches the name or the organization, literally, ignoring case. Asearchthat is a whole email address answers the guest who has that email alone (total1), or nobody, instead of matching names and organizations; part of an address is an ordinary search. Each item is{ id, name, title, organization, photo_url, episode_count, latest_appearance }, withorganization''when not set.episode_countcounts the published episodes on any show the guest is linked to, andlatest_appearanceis the newest of them,{ episode_id, title, date }withdatein the site’s date format, ornull.photo_urlis the thumbnail,''with no photo. Roster rows never carry the email.GET /guests/{id}→200 { id, name, title, organization, bio, photo_id, photo_url, website, social, publications, email, profile_url },sociala list of{ platform, url }.publicationslists the guest’s publications in order, each{ title, url, year, type, affiliate, outlinks_id, go_url }:urlthe plain address or'';yearfour digits or'';typebook,article,paperorother;outlinks_idthe Outlinks site-wide link or0;go_urlits/go/address while tracked and Outlinks runs, else''. Every route that returns a profile carries it, approvals’guestincluded.emailis the guest’s private email,''when not set: it is shown on no public page, feed or export.profile_urlis the guest’s public page.404 benecaster_guest_manager_not_foundfor an id that is not a guest.publicationsonPOSTandPUT, PATCHis the whole list. Refused with400,data.fieldpublicationsanddata.index(as sent):benecaster_guest_manager_publication_title_required,…_publication_title_too_long(300 characters),…_invalid_url,…_invalid_year,…_invalid_publication_type,…_invalid_publications(not a list),…_track_failed(Outlinks could not track a changed link). On save, while Outlinks runs, a tracked row whose link changed is tracked again throughbenecaster_outlinks_site_link(), and a row whose Outlinks link is gone becomes untracked.GET /track-link→{ available };POST /track-link { url }→{ outlinks_id, go_url, destination_url }(409 benecaster_guest_manager_outlinks_offwhile Outlinks is off;400 …_invalid_url; Outlinks’ own errors withdata.fieldurl). It saves nothing on the guest.POST /guestswith{ name, title?, organization?, bio?, photo_id?, website?, social?, publications?, email? }→201with the guest as above.PUT, PATCH /guests/{id}changes only the keys sent →200with the guest. An email is saved trimmed and lowercased, and no two guests can have the same one;''removes it.DELETE /guests/{id}→200 { deleted: true, id }. Deletes the guest for good (no trash) and every link from an episode to them; the photo stays in the media library.GET /guests/{id}/appearances→200 { items }, the guest editor’s Appearances list: every episode the guest is linked to on every show, any status but trash and auto-draft, newest first by publish date, drafts last. Each item is{ episode_id, title, status, when, show_id, show_title, guest_manager_on, editor_url }.titleis(no title)for an untitled episode;whenis a published episode’s date in the site’s date format, otherwise its status label (Draft, Scheduled, Pending review, Private);guest_manager_onisfalsefor an episode on a show with Guest Manager off, where the episode’s page and feed show none of its guests (such episodes are listed and marked, not hidden);editor_urlopens the episode in the episode editor on its own show.404 benecaster_guest_manager_not_foundfor an id that is not a guest. Read-only, so no hook fires.- Refusals, all
400withdata.field:benecaster_guest_manager_name_required(no name, or empty after cleaning),benecaster_guest_manager_name_too_long(over 200 characters),benecaster_guest_manager_invalid_url(awebsite, or asocialentry’surl, that is nothttp/https; forsocial,data.indexis the entry’s position),benecaster_guest_manager_invalid_social(socialnot a list),benecaster_guest_manager_invalid_photo(photo_idnot an image attachment;0removes the photo),benecaster_guest_manager_invalid_email(anemailthat is not a whole address),benecaster_guest_manager_email_taken(another guest already has that email, in any letter case;data.guest_idanddata.guest_namename that guest). Asocialentry with neither platform nor URL is dropped, not refused. biois cleaned withwp_kses_post();name,title,organizationand a platform are one line of plain text.
The hooks fire for writes made through these routes, which the Guests screen uses, and when a guest’s Guest portal changes are approved (see Approve or decline guests’ Guest portal changes from code, and change the approval emails). A guest changed another way (WP-CLI, wp_update_post()) fires none of them.
benecaster_guest_manager_before_save_guest( int $guest_id, array $fields ), before a create ($guest_idis0) or an update, once the request has validated.$fieldsholds only the keys sent, cleaned:name,title,organization,bio,website,social(a list of{ platform, url }),publications,photo_id,email.benecaster_guest_manager_after_save_guest( int $guest_id, array $fields, bool $created ), once the write succeeded. A failed write fires thebeforeaction alone.benecaster_guest_manager_before_delete_guest( int $guest_id ), while the guest and their episode links still exist, andbenecaster_guest_manager_after_delete_guest( int $guest_id ), once both are gone; not fired when the delete failed.benecaster_guest_manager_rest_guest( array $data, array $guest, string $context ): arrayfilters each guest a route returns:summaryfor a roster row,profilefor the editor’s view.$guestis the stored guest it was built from. A return that is not an array is ignored. Whatever you add is sent to the browser, to administrators only.
A refused request fires no hook.
Code
<?php
// Mirror every guest edit into a CRM, and drop the record when the guest is deleted.
add_action( 'benecaster_guest_manager_after_save_guest', function ( int $guest_id, array $fields, bool $created ): void {
my_crm_upsert_contact( 'guest-' . $guest_id, $fields );
}, 10, 3 );
add_action( 'benecaster_guest_manager_after_delete_guest', function ( int $guest_id ): void {
my_crm_delete_contact( 'guest-' . $guest_id );
} );
// Create a guest from a booking form, then give them a photo already in the media library.
$request = new WP_REST_Request( 'POST', '/benecaster-guest-manager/v1/guests' );
$request->set_body_params( [
'name' => 'Alice Smith',
'title' => 'Founder',
'organization' => 'Acme Labs',
'website' => 'https://alice.example',
'social' => [ [ 'platform' => 'LinkedIn', 'url' => 'https://linkedin.example/in/alice' ] ],
] );
$guest = rest_do_request( $request )->get_data();
$update = new WP_REST_Request( 'PATCH', '/benecaster-guest-manager/v1/guests/' . $guest['id'] );
$update->set_body_params( [ 'photo_id' => 381 ] );
rest_do_request( $update );
Hooks Used
Need this built rather than just documented? See our services →