Skip to main content

Read, create, change or delete guests from code, as the Guests screen does

Premium Intermediate Guest Manager

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_page 20 by default and at most 100. search matches the name or the organization, literally, ignoring case. A search that is a whole email address answers the guest who has that email alone (total 1), 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 }, with organization '' when not set. episode_count counts the published episodes on any show the guest is linked to, and latest_appearance is the newest of them, { episode_id, title, date } with date in the site’s date format, or null. photo_url is 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 }, social a list of { platform, url }. publications lists the guest’s publications in order, each { title, url, year, type, affiliate, outlinks_id, go_url }: url the plain address or ''; year four digits or ''; type book, article, paper or other; outlinks_id the Outlinks site-wide link or 0; go_url its /go/ address while tracked and Outlinks runs, else ''. Every route that returns a profile carries it, approvals’ guest included. email is the guest’s private email, '' when not set: it is shown on no public page, feed or export. profile_url is the guest’s public page. 404 benecaster_guest_manager_not_found for an id that is not a guest.
  • publications on POST and PUT, PATCH is the whole list. Refused with 400, data.field publications and data.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 through benecaster_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_off while Outlinks is off; 400 …_invalid_url; Outlinks’ own errors with data.field url). It saves nothing on the guest.
  • POST /guests with { name, title?, organization?, bio?, photo_id?, website?, social?, publications?, email? } → 201 with the guest as above. PUT, PATCH /guests/{id} changes only the keys sent → 200 with 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 }. title is (no title) for an untitled episode; when is a published episode’s date in the site’s date format, otherwise its status label (Draft, Scheduled, Pending review, Private); guest_manager_on is false for 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_url opens the episode in the episode editor on its own show. 404 benecaster_guest_manager_not_found for an id that is not a guest. Read-only, so no hook fires.
  • Refusals, all 400 with data.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 (a website, or a social entry’s url, that is not http/https; for social, data.index is the entry’s position), benecaster_guest_manager_invalid_social (social not a list), benecaster_guest_manager_invalid_photo (photo_id not an image attachment; 0 removes the photo), benecaster_guest_manager_invalid_email (an email that is not a whole address), benecaster_guest_manager_email_taken (another guest already has that email, in any letter case; data.guest_id and data.guest_name name that guest). A social entry with neither platform nor URL is dropped, not refused.
  • bio is cleaned with wp_kses_post(); name, title, organization and 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_id is 0) or an update, once the request has validated. $fields holds 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 the before action alone.
  • benecaster_guest_manager_before_delete_guest( int $guest_id ), while the guest and their episode links still exist, and benecaster_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 ): array filters each guest a route returns: summary for a roster row, profile for the editor’s view. $guest is 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 );

View on GitHub →

Hooks Used

Need this built rather than just documented? See our services →