NAV Navbar
python
  • Introduction
  • Versioning
  • Example Implementations
  • Authentication
  • Pagination
  • Timezones + UTC
  • Images
  • HTML Text
  • Guides
  • Sessions
  • ScheduleTracks
  • Locations
  • CustomLists
  • CustomListItems
  • CustomListItemRelations
  • Attendees
  • AttendeeGroups
  • PersonalizedSchedules
  • Webhooks
  • Introduction

    Guidebook offers a REST API to manage a subset of the resources available in the Guidebook Builder CMS. Our Open API uses resource-oriented urls, standard HTTP response codes, and HTTP verbs to segment different types of requests. The REST API is intended for content managment. If you are interested in integrating with metrics data via our Export API, see the section on Webhooks.

    Here are, for example, some typical response codes you might encounter:

    Code Description
    200 OK. Request received and processed successfully.
    201 Created. The request has been fulfilled and has resulted in one or more new resources being created.
    400 Bad request. The request is malformed and has not been accepted.
    401 Unauthorized. Your API Key was rejected.
    403 Forbidden. You do not have permission to perform that action.
    404 Not found. The requested URL is not found on the server.
    429 Too many requests. You have hit the Open API too quickly.
    500, 502, 503, 504 Server error. Something is wrong on Guidebook's end. Please try again later.

    Versioning

    New versions of the Guidebook Open API will be released when Guidebook makes backwards incompatible changes to how resources are manipulated or represented. New versions of the Guidebook Open API will include new urls for accessing resources; for example in v1 ("version 1") Session objects are accessed at https://builder.guidebook.com/open-api/v1/sessions/, but in v2 Session objects might be accessed at a url like https://builder.guidebook.com/open-api/v2/sessions/.

    Guidebook reserves the right, however, to make backwards-compatible changes to the Open API without releasing a new Open API version. Here are some examples of backwards-compatible changes:

    Example Implementations

    Our public github repo contains several source code samples of how to integrate Guidebook with other services. These are provided as an additional resource to assist developers in learning about the possiblities enabled with our API. Client's are welcome to use these examples as a starting point to create their own custom integrations.

    Eventbrite Integration

    Our Eventbrite Integration is the open sourced code of how the default Eventbrite integration in Guidebook Builder runs. The standard integration imports Attendees from Eventbrite and groups them by Ticket Type. If you would like to run your own custom Eventbrite integration, you can use this code as a starting point.

    Icalendar Integration

    Icalendar is a popular format for representing schedules. The Icalendar Integration example we provide shows how you can import session data into Guidebook from an ical source. Icalendar feeds can be incredibly complicated and if your ical feed incorporates non standard properties (X-prefixed properties), you can customize our ical integration to fit your needs.

    Authentication

    Example request that includes authentication:

    import requests
    
    api_url = 'https://builder.guidebook.com/open-api/v1/sessions/'
    api_key = 'API_KEY'
    api_response = requests.get(api_url, headers={'Authorization': 'JWT ' + api_key})
    

    You must replace the value assigned to api_key with your personal API key.

    Note that the sample python code sample in this documentation uses the python requests package. Installation instructions for requests can be found here; alternatively, for the more eager, you can run pip install requests.

    To access Guidebook's Open API, you'll need to include an API Key with your requests. You can manage your API Keys in the API Page of the Guidebook Builder CMS. Your API Keys grant significant access to resources related to your account, so keep them secret! Do not share your API Keys with anyone, and do not place API Keys in publicly accessible areas like GitHub or client-side code.

    All requests to the Guidebook Open API need to have an API Key included in a header that looks something like:

    Authorization: JWT API_KEY

    Pagination

    {
      "count": 85,
      "next": "https://builder.guidebook.com/open-api/v1/pagination-example/?page=2",
      "previous": null,
      "results": [
          {
            "property_1": "value-a",
            "property_2": "value-b"
          },
          {
            "property_1": "value-c",
            "property_2": "value-d"
          },
    
          ... etc.
      ]
    }
    

    If a resource supports listing itself, a data structure will be returned with several key attributes related to pagination:

    Attribute Name Type Description
    count integer Total number of available resources
    next string URL to retrieve the next page of resources
    previous string URL to retrieve the previous page of resources
    results array Representation of the resources in this page

    next will be null if no additional resources are available (you have reached the last page).

    Timezones + UTC

    Communicating With the Open API

    Internally, Guidebook's servers store all inputted datetime values in the Universal Time Zone (UTC). As such, when the Guidebook Open API reports a datetime, it returns a datetime value in UTC. For example, Session.start_time, Session.end_time, and Guide.created_at all report themselves in UTC. To minimize confusion and error, we recommend that your applications send datetimes to the Guidebook Open API in UTC. For example, 2017-09-26T09:35:00.000000-0700 ("September 26th 2017 9:35AM US/Pacific") would be sent as 2017-09-26T16:35:00.000000+0000 ("September 26th 2017 4:35PM UTC").

    Display in Guidebook's Mobile Apps

    When datetimes (like Session.start_time and Session.end_time) are displayed to users in Guidebook's Android + iOS mobile apps, they are converted from UTC to the timezone of the Guide object they belong to. As of now, Guide timezone management is available in the Guidebook Builder CMS (and not via the Open API).

    Images

    Some resources (like Sessions and CustomListItems) can be associated to images that will be displayed in Guidebook apps. To upload images, you can submit a multipart request. A code example accompanies this section that uploads an image to a Session using the python requests package.

    Example request that changes the name and image of an existing Session

    import requests
    
    api_url = 'https://builder.guidebook.com/open-api/v1/sessions/71/'
    api_key = 'API_KEY'
    headers = {'Authorization': 'JWT ' + api_key}
    image_file = open('your_image_file.png', 'rb')
    requests.patch(api_url, {'name': 'updated session name'}, files={'image': image_file}, headers=headers)
    

    HTML Text

    Guidebook allows HTML in a few specific fields (usually description fields). HTML that is in html-supported fields will render as HTML in the mobile apps. HTML tags in non html-supported fields will be rendered as plaintext.

    Allowed Tags

    Tag Type Tags
    headings h1, h2, h3, h4, h5, h6, h7, h8
    prose a, p, div, blockquote
    formatted pre
    inline span, b, u, i, strong, em, tt, code, ins, del, sup, sub, kbd, samp, q, var
    lists ol, ul, li, dl, dt, dd
    tables table, thead, tbody, tfoot, tr, td, th
    breaks br, hr
    other ruby, rt, rp

    Allowed Attributes

    Tag Allowed Attributes for Tag
    a href
    img src
    div itemscope, itemtype
    all tags abbr, accept, accept-charset, accesskey, action, align, alt, axis, border, cellpadding, cellspacing, char, charoff, charset, checked, cite, clear, cols, colspan, color, compact, coords, datetime, dir, disabled, enctype, for, frame, headers, height, hreflang, hspace, ismap, label, lang, longdesc, maxlength, media, method, multiple, name, nohref, noshade, nowrap, prompt, readonly, rel, rev, rows, rowspan, rules, scope, selected, shape, size, span, start, summary, tabindex, target, title, type, usemap, valign, value, vspace, width, itemprop

    Guides

    Many of the resources exposed by the Guidebook Open API relate to a class of objects called Guide. Guide objects are typically containers for the set of data related to an event like a conference. For example, if you were hosting a conference called, "Programmer Summit 2017" you would likely have one Guide object that contained the schedule for the conference, a list of speakers for that conference, and a list of users who you expect to attend the conference.

    As of now, Guide objects themselves are primarily managed via the Guidebook Builder CMS (and not via the Open API). Resources exposed by the Open API, however, will contain references to the id of Guide objects they belong to. For example, every Session object returned in the Open API will report the id of the one Guide that Session belongs to (e.g. "guide": 1). In general, resources cannot be transferred or otherwise shared amongst more than one Guide -- once a Session is created under a given Guide object, it lives under that Guide permanently and cannot be moved to a different Guide.

    Listing Guides

    import requests
    
    guides_url = 'https://builder.guidebook.com/open-api/v1/guides/'
    api_key = 'API_KEY'
    response = requests.get(guides_url, headers={'Authorization': 'JWT ' + api_key}).json()
    

    The above command returns JSON structured like this:

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 21,
                "created_at": "2017-09-18T21:28:35.429989+0000",
                "name": "Programmer Summit 2017",
                "description_html": "TEST DESCRIPTION",
                "start_date": "2017-05-22T21:00:00.000000+0000",
                "end_date": "2017-05-27T21:00:00.000000+0000",
                "timezone": "UTC",
                "created_at": "2018-05-28T21:53:31.010760+0000"
            },
            {
                "id": 22,
                "created_at": "2017-09-18T21:28:35.436433+0000",
                "name": "Programmer Summit 2018",
                "description_html": "<b>TEST DESCRIPTION 2018</b>",
                "start_date": null,
                "end_date": null,
                "timezone": "US/Pacific",
                "created_at": "2018-05-28T21:53:31.010760+0000"
            }
        ]
    }
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/guides/

    Guide Properties

    Property Type Description
    id int id of the Guide object.
    created_at datetime Time when Guide was created -- in UTC.
    name str Name of the Guide.
    start_date datetime The start date of the Guide. For consistency, all timestamps are converted to the UTC timezone. Leave blank for ongoing Guides.
    end_date datetime The end date of the Guide. Leave blank for ongoing Guides.
    description_html string A description of the Guide. This field supports basic HTML. See section on html text.
    timezone timezone Session times in this Guide will be converted to this timezone. Check this list for valid timezone strings.

    Retrieving a Guide

    In the following examples, we will assume that the id of the Guide we'd like to modify is 21. To retrieve an individual Guide object issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/guides/21/

    Updating a Guide

    To modify an existing Guide object, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1/guides/21/

    You will only need to include the specific fields you are updating and not a full request body.

    Creating/Deleting a Guide

    We do not allow the Create or Delete operations for the Guide object via the Open API. To perform these actions, please login to your account on the Guidebook Builder CMS.

    Sessions

    Sessions can be added to a Guide to build up a schedule for your event. For example, the, "Programmer Conference 2017" event might have a Session for the talk, "Python in a Scientific Environment", and a Session about, "Off by One Errors."

    Creating Session

    import requests
    
    session_url =  'https://builder.guidebook.com/open-api/v1/sessions/'
    api_key = 'API_KEY'
    post_data =
    {
        "start_time": "2017-09-18T16:00:00",
        "end_time": "2017-09-18T17:00:00",
        "guide": 1,
        "description_html": "<p>This is a description field that supports basic HTML</p>",
        "name": "Test Session Created via the Open API"
    }
    
    response_1 = request.post(session_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    # example with `ScheduleTracks`
    post_data =
    {
        "start_time": "2017-09-18T16:00:00",
        "end_time": "2017-09-18T17:00:00",
        "guide": 1,
        "description_html": "<p>This is a description field that supports basic HTML</p>",
        "name": "Test Session Created via the Open API",
        "schedule_tracks": [3, 42, 47, 101]
    }
    
    response_2 = request.post(session_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    # example with `Locations`
    
    post_data =
    {
        "start_time": "2017-09-18T16:00:00",
        "end_time": "2017-09-18T17:00:00",
        "guide": 1,
        "description_html": "<p>This is a description field that supports basic HTML</p>",
        "name": "Test Session Created via the Open API",
        "locations": [3, 42, 47, 101]
    }
    
    response_3 = request.post(session_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    

    The above commands return JSON structured like this:

    {
        "id": 106,
        "created_at": "2017-09-18T22:13:25.766623+0000",
        "start_time": "2017-09-18T16:00:00.000000+0000",
        "end_time": "2017-09-18T17:00:00.000000+0000",
        "all_day": false,
        "name": "Test Session Created via the Open API",
        "description_html": "<p>This is a description field that supports basic HTML</p>",
        "import_id": null,
        "allow_rating": true,
        "add_to_schedule": true,
        "guide": 1,
        "locations": [],
        "schedule_tracks": [],
        "image": null
    }
    
    # example with `ScheduleTracks`
    {
        "id": 106,
        "created_at": "2017-09-18T22:13:25.766623+0000",
        "start_time": "2017-09-18T16:00:00.000000+0000",
        "end_time": "2017-09-18T17:00:00.000000+0000",
        "all_day": false,
        "name": "Test Session Created via the Open API",
        "description_html": "<p>This is a description field that supports basic HTML</p>",
        "import_id": null,
        "allow_rating": true,
        "add_to_schedule": true,
        "guide": 1,
        "locations": [],
        "schedule_tracks": [3, 42, 47, 101],
        "image": null
    }
    
    
    # example with `Locations`
    {
        "id": 106,
        "created_at": "2017-09-18T22:13:25.766623+0000",
        "start_time": "2017-09-18T16:00:00.000000+0000",
        "end_time": "2017-09-18T17:00:00.000000+0000",
        "all_day": false,
        "name": "Test Session Created via the Open API",
        "description_html": "<p>This is a description field that supports basic HTML</p>",
        "import_id": null,
        "allow_rating": true,
        "add_to_schedule": true,
        "guide": 1,
        "locations": [3, 42, 47, 101],
        "schedule_tracks": [],
        "image": null
    }
    
    

    This endpoint will create a Session for your Guide.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1/sessions/

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your Session belongs to. See section on Guides for more info.
    name yes string The title of your Session.
    description_html yes string A text description of the Session. This field has a 20,000 character limit. This field supports basic HTML. See section on html text.
    start_time yes datetime The start time of the event. For consistency, all timestamps are converted to the UTC timezone.
    end_time no datetime The end time of the event. Leave blank for all day events. For consistency, all timestamps are converted to the UTC timezone.
    all_day no boolean A boolean value indicating if a Session runs for the entire day.
    allow_rating no boolean A boolean value indicating if end-users can rate this Session.
    add_to_schedule no boolean A boolean value indicating if end-users can add this Session to their personal schedule.
    import_id no string A string field you can use to input your own identifier. This is for when you have your own IDs for Sessions in your data store.
    locations no array of integers Array of IDs of Locations this Session should belong to. See section on Locations.
    schedule_tracks no array of integers Array of IDs of ScheduleTracks this Session should belong to. See section on ScheduleTracks.
    image no image image will appear above the Session name, date, times, location, and description in Guidebook apps. The ideal size is 640px wide, 240 px tall. See section on images.

    Listing Sessions

    import requests
    
    session_url =  'https://builder.guidebook.com/open-api/v1/sessions/'
    api_key = 'API_KEY'
    
    # This will return all `Sessions` you have access to
    response = request.get(session_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 4,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 21,
                "created_at": "2017-09-18T21:28:35.429989+0000",
                "start_time": "2017-09-18T21:28:35.428248+0000",
                "end_time": "2017-09-18T22:28:35.428257+0000",
                "all_day": false,
                "name": "Test Session 1",
                "description_html": null,
                "import_id": null,
                "allow_rating": true,
                "add_to_schedule": true,
                "guide": 42,
                "locations": [],
                "schedule_tracks": [],
                "image": null
            },
            {
                "id": 22,
                "created_at": "2017-09-18T21:28:35.432366+0000",
                "start_time": "2017-09-18T21:28:35.431034+0000",
                "end_time": "2017-09-18T22:28:35.431042+0000",
                "all_day": false,
                "name": "Test Session 2",
                "description_html": null,
                "import_id": null,
                "allow_rating": true,
                "add_to_schedule": true,
                "guide": 42,
                "locations": [],
                "schedule_tracks": [],
                "image": null
            },
            {
                "id": 23,
                "created_at": "2017-09-18T21:28:35.434402+0000",
                "start_time": "2017-09-18T21:28:35.433197+0000",
                "end_time": "2017-09-18T22:28:35.433205+0000",
                "all_day": false,
                "name": "Test Session 3",
                "description_html": null,
                "import_id": null,
                "allow_rating": true,
                "add_to_schedule": true,
                "guide": 42,
                "locations": [],
                "schedule_tracks": [],
                "image": null
            },
            {
                "id": 24,
                "created_at": "2017-09-18T21:28:35.436433+0000",
                "start_time": "2017-09-18T21:28:35.435265+0000",
                "end_time": "2017-09-18T22:28:35.435273+0000",
                "all_day": false,
                "name": "Test Session 4, Different Guide",
                "description_html": null,
                "import_id": null,
                "allow_rating": true,
                "add_to_schedule": true,
                "guide": 43,
                "locations": [],
                "schedule_tracks": [],
                "image": null
            }
        ]
    }
    
    

    This endpoint can also be used to read data on Sessions.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/sessions/

    Model Fields

    Same as the fields used in creation with the addition of the following read-only fields:

    Parameter Type Description
    id integer An unique identifier for your Session.
    created_at datetime Time when this Session was created - UTC.

    Filtering data by Guide id and other fields

    Including a query parameter guide allows you to filter for all Sessions related to a Guide you have access to (Guide 47 in this example):

    GET https://builder.guidebook.com/open-api/v1/sessions/?guide=47

    You are also able to filter by the fields schedule_tracks and id if you want to fetch a list of Sessions fitting specific criteria. See example below for how to filter on to these fields and combining multiple filters:

    GET https://builder.guidebook.com/open-api/v1/sessions/?guide=47&schedule_tracks=3

    GET https://builder.guidebook.com/open-api/v1/sessions/?guide=47&id=8673

    Sorting Returned Data

    When fetching a list of your Sessions, you're also able to control the order of the returned data if this is important for your needs. The fields that you can sort by are id, start_time, and end_time. The following example will sort all Sessions from Guide 47 by start_time in chronological order:

    GET https://builder.guidebook.com/open-api/v1/sessions/?guide=47&ordering=start_time

    Prepending - in front of an ordering field reverses it. The following example with sort by end_time in reverse chronological order and then do a secondary sort by start_time:

    GET https://builder.guidebook.com/open-api/v1/sessions/?guide=47&ordering=-end_time,start_time

    Retrieving a Session

    In the following examples, we will assume that the id of the Session we'd like to modify is 71. To retrieve an individual Session object issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/sessions/71/

    Updating a Session

    To modify an existing Session object, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1/sessions/71/

    You will only need to include the specific fields you are updating and not a full request body.

    Deleting a Session

    To delete a particular Session, issue a DELETE request to the url that points to the specific Session you'd like deleted:

    DELETE https://builder.guidebook.com/open-api/v1/sessions/71/

    ScheduleTracks

    ScheduleTracks allow you to build a filtered view of your schedule. A ScheduleTrack contains a subset of the Sessions in your Guide. For the event, "Programmer Conference 2017" you might, for example, have a ScheduleTrack for Sessions about Python, and a ScheduleTrack for Sessions about Java.

    Creating a ScheduleTrack

    import requests
    
    schedule_tracks_url =  'https://builder.guidebook.com/open-api/v1/schedule-tracks/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "name": "Test Schedule Track Created via the Open API",
        "color": "#000080"
    }
    response = request.post(schedule_tracks_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
        "id": 234,
        "guide": 1,
        "name": "Test Schedule Track Created via the Open API",
        "color": "#000080",
        "created_at": "2017-09-21T21:28:35.432366+0000"
    }
    
    
    

    This endpoint will create a ScheduleTrack for your guide.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1/schedule-tracks/

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific guide your ScheduleTrack belongs to. See section on Guides for more info.
    name yes string The title of your ScheduleTrack.
    color no string Hex value of the color you want this track to be. Used for highlighting sessions in the app. Example: "#000080" for blue.

    Listing ScheduleTracks

    import requests
    
    schedule_tracks_url =  'https://builder.guidebook.com/open-api/v1/schedule-tracks/'
    api_key = 'API_KEY'
    
    # This will return all `ScheduleTracks` you have access to
    response = request.get(schedule_tracks_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 4,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 210,
                "guide": 308,
                "name": "Test Track 1",
                "color": null,
                "created_at": "2017-09-10T21:28:35.432366+0000"
            },
            {
                "id": 211,
                "guide": 308,
                "name": "Test Track 2",
                "color": null
            },
            {
                "id": 212,
                "guide": 308,
                "name": "Test Track 3",
                "color": null,
                "created_at": "2017-09-11T21:28:35.432366+0000"
            },
            {
                "id": 213,
                "guide": 309,
                "name": "Test Track 4, Different Guide",
                "color": null,
                "created_at": "2017-09-12T21:28:35.432366+0000"
            }
        ]
    }
    
    

    This endpoint can also be used to read data on ScheduleTracks.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/schedule-tracks/

    Model Fields

    Same as the fields used in creation with the addition of the following read-only fields:

    Parameter Type Description
    id integer An unique identifier for your ScheduleTrack.
    created_at datetime Time when this ScheduleTrack was created - UTC.

    Filtering By Guide id

    Including a query parameter guide allows you to filter for all ScheduleTracks related to a Guide you have access to (Guide 47 in the following example):

    GET https://builder.guidebook.com/open-api/v1/schedule-tracks/?guide=47

    Retrieving a ScheduleTrack

    In the following examples, we will assume that the id of the ScheduleTrack we'd like to modify is 71. To retrieve an individual ScheduleTrack object issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/schedule-tracks/71/

    Updating a ScheduleTrack

    To modify an existing ScheduleTracks object, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1/schedule-tracks/71/

    You will only need to include the specific fields you are updating and not a full request body.

    Deleting a ScheduleTrack

    To delete a particular ScheduleTrack, issue a DELETE request to the url that points to the specific ScheduleTrack you'd like deleted:

    DELETE https://builder.guidebook.com/open-api/v1/schedule-tracks/71/

    Locations

    Location objects can be added to Sessions and CustomListItems to give users additional context about where an event or point of interest is located.

    Creating Locations

    
    url = 'https://builder.guidebook.com/open-api/v1/locations/'
    api_key = 'API_KEY'
    post_data =
    {
      "guide": 1,
      "name": "Stadium",
      "description": null,
      "location_type": 3,
      "latitude": 37.3327,
      "longitude": -121.901236,
      "import_id": null
    }
    response = requests.post(url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    

    The above command returns JSON structured like this:

    {
      "id": 89,
      "guide": 1,
      "name": "Stadium",
      "description": null,
      "location_type": 3,
      "latitude": 37.3327,
      "longitude": -121.901236,
      "import_id": null,
      "address": null,
      "created_at": "2017-09-25T20:18:28.052157+0000"
    }
    

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1/locations/

    Model Fields

    Property Required Type Description
    guide yes integer id of the Guide this Location belongs to.
    name yes string Name of this Location.
    import_id no string A string field you can used to input your own identifier. This is for when you have your own IDs for Locations in your data store.
    location_type yes integer Either 1, 2 or 3. 1 is the special Main Venue location. 2 is a Placeholder location. 3 is a "Google Maps Location"
    latitude sometimes float Latitude of this Location - only required if this Location is of type ("Google Maps Location") or ("Main Venue" Location).
    longitude sometimes float Longitude of this Location - only required if this Location is of type ("Google Maps Location") or ("Main Venue" Location).
    address sometimes json Address of the Main Venue. JSON dictionary with the keys ['address', city', 'country', 'state', 'street', 'zipcode']

    Listing Locations

    import requests
    
    url = 'https://builder.guidebook.com/open-api/v1/locations/'
    api_key = 'API_KEY'
    response = requests.get(guides_url, headers={'Authorization': 'JWT ' + api_key}).json()
    

    The above command returns JSON structured like this:

    {
      "count": 3,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 2,
          "guide": 1,
          "name": "Conference Hall A",
          "description": null,
          "location_type": 2,
          "latitude": null,
          "longitude": null,
          "import_id": null,
          "address": null,
          "created_at": "2017-08-31T20:18:28.018529+0000"
        },
        {
          "id": 3,
          "guide": 1,
          "name": "Lobby",
          "description": null,
          "location_type": 2,
          "latitude": null,
          "longitude": null,
          "import_id": null,
          "address": null,
          "created_at": "2017-08-31T20:18:28.038556+0000"
        },
        {
          "id": 4,
          "guide": 1,
          "name": "Meeting Place",
          "description": null,
          "location_type": 3,
          "latitude": 37.7749,
          "longitude": -122.4194,
          "import_id": null,
          "address": null,
          "created_at": "2017-08-31T20:18:28.052157+0000"
        }
      ]
    }
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/locations/

    Model Fields

    Same as the fields used in creation with the addition of the following read-only fields:

    Parameter Type Description
    id integer An unique identifier for your Location.
    created_at datetime Time when this Location was created - UTC.

    Filtering Locations

    To filter the returned Locations by their location_type include the query parameter location_type. The following request, for examples, filters for Locations with location_type 2. Additionally, you can also filter by guide to limit to locations belonging to a specific guide.

    GET https://builder.guidebook.com/open-api/v1/locations/?location_type=2

    GET https://builder.guidebook.com/open-api/v1/locations/?location_type=2&guide=42

    Manipulating Individual Locations

    Update the name of a Location

    
    url = 'https://builder.guidebook.com/open-api/v1/locations/89/'
    api_key = 'API_KEY'
    patch_data =
    {
      "name": "San Jose Sharks Stadium"
    }
    response = requests.patch(url, data=patch_data, headers={'Authorization': 'JWT ' + api_key}).json()
    

    PATCH requests (to update) and GET requests (to retrieve) an individual Location will return a JSON structure like this:

    {
      "id": 89,
      "guide": 1,
      "name": "San Jose Sharks Stadium",
      "description": null,
      "location_type": 3,
      "latitude": 37.3327,
      "longitude": -121.901236,
      "import_id": null,
      "address": null,
      "created_at": "2017-09-25T20:18:28.052157+0000"
    }
    

    To access and manipulate an individual Location object, use a url that ends with the id of a Location object:

    https://builder.guidebook.com/open-api/v1/locations/<location_id>/

    Retrieving a Location

    In the following examples, we will assume that the id of the Locations we'd like to modify is 89. To retrieve an individual Location object, issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/locations/89/

    Updating a Location

    To modify an existing Location object, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1/locations/89/

    You will only need to include the specific fields you are updating and not a full request body.

    Deleting a Location

    To delete a particular Location, issue a DELETE request to the url that points to the specific Location you'd like deleted:

    DELETE https://builder.guidebook.com/open-api/v1/locations/89/

    The Main Venue Location

    The Main Venue is a special Location object for the Guide and represents the main location for your Guide. There is only one Main Venue location allowed per guide and any attempts to create more than one Main Venue will result in validation errors. This Location requires a JSON dictionary of the address and the longitude and latitude values of this address.

    # First fetch the ID of the Main Venue object
    api_key = 'API_KEY'
    
    url = 'https://builder.guidebook.com/open-api/v1/locations/?location_type=1&guide_id=21'
    response = requests.get(url, headers={'Authorization': 'JWT ' + api_key}).json()
    main_venue_id = response.json()['results'][0]['id']
    
    update_url = 'https://builder.guidebook.com/open-api/v1/locations/{}/'.format(main_venue_id)
    patch_data =
    {
        "name": "Moscone Center",
        "longitude": -122.401558,
        "latitude": 37.784172,
        "address": {
            "address": "Moscone Center",
            "city": "San Francisco",
            "state": "CA",
            "street": "747 Howard Street",
            "zipcode": "94103",
            "country": "U.S.A."
        }
    }response = requests.patch(url, data=patch_data, headers={'Authorization': 'JWT ' + api_key}).json()
    

    PATCH requests to update the Main Venue will return a JSON structure like this:

    {
        "id": 5,
        "guide": 3,
        "name": "Moscone Center",
        "description": null,
        "location_type": 1,
        "latitude": 37.784172,
        "longitude": -122.401558,
        "import_id": null,
        "created_at": "2018-05-29T02:21:48.336713+0000",
        "address": {
            "city": "San Francisco",
            "country": "U.S.A.",
            "zipcode": "94103",
            "state": "CA",
            "street": "747 Howard Street",
            "address": "Moscone Center"
        }
    }```
    
    

    CustomLists

    Creating a CustomList

    import requests
    
    custom_lists_url =  'https://builder.guidebook.com/open-api/v1/custom-lists/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "name": "Test Custom List Created via the Open API"
    }
    response = request.post(custom_lists_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
        "id": 1,
        "import_id": null,
        "guide": 1,
        "name": "Test Custom List Created via the Open API",
        "disable_todo": false,
        "allow_rating": false,
        "created_at": "2017-09-27T07:38:58.471042+0000"
    }
    
    

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1/custom-lists/

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your CustomList belongs to. See section on Guides for more info.
    name yes string The title of your CustomList. i.e (Exhibitors, Speakers, Places to Visit, etc).
    disable_todo no boolean A booelan value that will hide the "Add to To-do" button for all items on this list.
    allow_rating no boolean A boolean value indicating if end-users can rate items in this CustomList.
    import_id no string A string field you can use to input your own identifier. This is for when you have your own IDs for your Lists in your data store.

    Listing CustomLists

    This endpoint will list all CustomLists that are owned by your Account. Typically, this endpoint is called with a guide_id filter such that it returns a list of CustomLists associated to a lone Guide object that is owned by you.

    import requests
    
    custom_lists_url =  'https://builder.guidebook.com/open-api/v1/custom-lists/'
    api_key = 'API_KEY'
    
    # This will return all custom lists you have access to
    response = request.get(custom_lists_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 4,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 1,
                "import_id": null,
                "guide": 1,
                "name": "Test Custom List 1",
                "disable_todo": false,
                "allow_rating": true,
                "created_at": "2017-09-27T07:31:48.637192+0000"
            },
            {
                "id": 2,
                "import_id": null,
                "guide": 1,
                "name": "Test Custom List 2",
                "disable_todo": false,
                "allow_rating": true,
                "created_at": "2017-09-27T07:31:48.639373+0000"
            },
            {
                "id": 3,
                "import_id": null,
                "guide": 1,
                "name": "Test Custom List 3",
                "disable_todo": false,
                "allow_rating": true,
                "created_at": "2017-09-27T07:31:48.641850+0000"
            },
            {
                "id": 4,
                "import_id": null,
                "guide": 2,
                "name": "Test Custom List 4, Different Guide",
                "disable_todo": false,
                "allow_rating": true,
                "created_at": "2017-09-27T07:31:48.643872+0000"
            }
        ]
    }
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/custom-lists/

    Model Fields

    Same as the fields used in creation with the addition of the following read-only fields

    Parameter Type Description
    id integer An unique identifier for your CustomList.
    created_at datetime Time when this CustomList was created - UTC.

    Filtering By Guide id

    Including a query parameter guide allows you to filter for all CustomLists related to a Guide you have access to (Guide 47 in the following example):

    GET https://builder.guidebook.com/open-api/v1/custom-lists/?guide=47

    Retrieving a CustomList

    In the following examples, we will assume that the id of the CustomList we'd like to modify is 71. To retrieve an individual CustomList object issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/custom-lists/71/

    Updating a CustomList

    To modify an existing CustomList object, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1/custom-lists/71/

    You will only need to include the specific fields you are updating and not a full request body.

    Deleting a CustomList

    To delete a particular CustomList, issue a DELETE request to the url that points to the specific CustomList you'd like deleted:

    DELETE https://builder.guidebook.com/open-api/v1/custom-lists/71/

    CustomListItems

    Creating a CustomListItem

    import requests
    
    custom_list_item_url =  'https://builder.guidebook.com/open-api/v1/custom-list-items/'
    api_key = 'API_KEY'
    post_data =
    {
        "import_id": "exhibitor_42",
        "guide": 1,
        "description_html": "<p>This is a description field that supports basic HTML</p>",
        "name": "Test Custom List Item Created via the Open API"
    }
    response = request.post(custom_list_item_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    
    

    The above commands return JSON structured like this:

    {
        "id": 1,
        "import_id": "exhibitor_42",
        "name": "Test Custom List Item Created via the Open API",
        "description_html": "<p>This is a description field that supports basic HTML</p>",
        "subtitle": null,
        "allow_rating": false,
        "guide": 1,
        "custom_lists": [],
        "locations": [],
        "created_at": "2017-09-27T08:19:08.544919+0000",
        "image": null,
        "thumbnail": null
    }
    
    
    

    This endpoint will create a CustomListItem for your Guide.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1/custom-list-items/

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your CustomListItem belongs to. See section on Guides for more info.
    name yes string The title of your CustomListItem.
    description_html yes string A text description of the CustomListItem. This field has a 20,000 character limit. This field supports basic HTML. See section on html text.
    subtitle no string A short tagline thats displayed below the name of the name field.
    allow_rating no boolean A boolean value indicating if end-users can rate this CustomListItem.
    import_id no string A string field you can use to input your own identifier. This is for when you have your own IDs for CustomListItems in your data store.
    locations no array of integers Array of IDs of Locations this Session should belong to. See section on Locations.
    image no image image will appear with the CustomListItem in Guidebook apps. The ideal size is 640px wide, 240 px tall. See section on images.
    thumbnail no thumbnail thumbnail will appear with the CustomListItem in Guidebook apps. The ideal size is 240px wide, 240 px tall. See section on images.

    Listing CustomListItems

    import requests
    
    custom_list_item_url =  'https://builder.guidebook.com/open-api/v1/custom-list-items/'
    api_key = 'API_KEY'
    
    # This will return all `CustomListItems` you have access to
    response = request.get(custom_list_item_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 4,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 1,
                "import_id": null,
                "name": "Test List Item 1",
                "description_html": null,
                "subtitle": null,
                "allow_rating": true,
                "guide": 5,
                "custom_lists": [
                    6
                ],
                "locations": [],
                "created_at": "2017-09-27T08:11:40.183229+0000",
                "image": null,
                "thumbnail": null
            },
            {
                "id": 2,
                "import_id": null,
                "name": "Test List Item 2",
                "description_html": null,
                "subtitle": null,
                "allow_rating": true,
                "guide": 5,
                "custom_lists": [
                    6
                ],
                "locations": [],
                "created_at": "2017-09-27T08:11:40.189964+0000",
                "image": null,
                "thumbnail": null
            },
            {
                "id": 3,
                "import_id": null,
                "name": "Test List Item 3",
                "description_html": null,
                "subtitle": null,
                "allow_rating": true,
                "guide": 5,
                "custom_lists": [
                    6
                ],
                "locations": [],
                "created_at": "2017-09-27T08:11:40.195613+0000",
                "image": null,
                "thumbnail": null
            },
            {
                "id": 4,
                "import_id": null,
                "name": "Test List Item 4, Different Guide",
                "description_html": null,
                "subtitle": null,
                "allow_rating": true,
                "guide": 6,
                "custom_lists": [
                    7
                ],
                "locations": [],
                "created_at": "2017-09-27T08:11:40.200571+0000",
                "image": null,
                "thumbnail": null
            }
        ]
    }
    
    

    This endpoint can also be used to read data on CustomListItems.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/custom-list-items/

    Model Fields

    Same as the fields used in creation with the addition of the following read-only fields

    Parameter Type Description
    id integer An unique identifier for your CustomListItem.
    created_at datetime Time when this CustomListItem was created - UTC.
    custom_list list of integers A list of the CustomList IDs that this CustomListItem is related to.

    Filtering data by Guide id and other fields

    Including a query parameter guide allows you to filter for all CustomListItems related to a Guide you have access to (Guide 47 in this example):

    GET https://builder.guidebook.com/open-api/v1/custom-list-items/?guide=47

    You are also able to filter by the fields custom_lists and id if you want to fetch a list of CustomListItems fitting specific criteria. See example below for how to filter on to these fields and combining multiple filters:

    GET https://builder.guidebook.com/open-api/v1/custom-list-items/?guide=47&custom_lists=12

    GET https://builder.guidebook.com/open-api/v1/custom-list-items/?guide=47&id=44859

    Sorting Returned Data

    When fetching a list of your CustomListItems, you're also able to control the order of the returned data if this is important for your needs. The only field you can currently sort by is id. The following example will sort all CustomListItems from Guide 47 by id in numerical order:

    GET https://builder.guidebook.com/open-api/v1/custom-list-items/?guide=47&ordering=id

    Prepending - in front of an ordering field reverses it. The following example with sort in reverse:

    GET https://builder.guidebook.com/open-api/v1/custom-list-items/?guide=47&ordering=-id

    Retrieving a CustomListItem

    In the following examples, we will assume that the id of the CustomListItem we'd like to modify is 71. To retrieve an individual CustomListItem object issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/custom-list-items/71/

    Updating a CustomListItem

    To modify an existing CustomListItems object, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1/custom-list-items/71/

    You will only need to include the specific fields you are updating and not a full request body.

    Deleting a CustomListItem

    To delete a particular CustomListItem, issue a DELETE request to the url that points to the specific CustomListItem you'd like deleted:

    DELETE https://builder.guidebook.com/open-api/v1/custom-list-items/71/

    CustomListItemRelations

    The CustomListItemRelation resource is the "through" object that links a CustomListItem to a CustomList. For example, to add a CustomListItem named "Peter Lada" to a CustomList named "Programmer Conference 2017 Speakers", a new CustomListItemRelation object would be created with the id of the "Peter Lada" CustomListItem and the id of the "Programmer Conference 2017 Speakers" CustomList. When more than one CustomListItem exists inside of a CustomList, display order can be controlled by the rank field on CustomListItemRelation.

    Creating CustomListItemRelations

    import requests
    
    url = 'https://builder.guidebook.com/open-api/v1/custom-list-item-relations/'
    api_key = 'API_KEY'
    post_data =
    {
      "custom_list": 59,
      "custom_list_item": 369,
      "rank": 15.1
    }
    response = requests.post(url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    

    The above command returns JSON structured like this:

    {
      "id": 156,
      "custom_list": 59,
      "custom_list_item": 369,
      "rank": 15.1,
      "created_at": "2017-09-22T20:18:38.174876+0000"
    }
    

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1/custom-list-item-relations/

    Note that if you do not include a rank value in your POST data, rank defaults to to a large negative value that decreases with time.

    Model Fields

    Property Required Type Description
    custom_list_item yes integer id of the CustomListItem being associated to the CustomList identified by custom_list.
    custom_list yes integer id of the CustomList that custom_list_item is being associated to. Note that a given (custom_list_item, custom_list) tuple cannot be repeated on different CustomListItemRelation objects ("you can only associate a given CustomListItem to a given CustomList" once").
    rank no float Controls the display order of CustomListItems within a CustomList - CustomListItems are displayed in ascending order by rank. Note that a given (custom_list, rank) tuple cannot be repeated on different CustomLIstItemRelation objects ("rank is unique amongst all the CustomListItemRelations associated to a given CustomList").

    Listing CustomListItemRelations

    import requests
    
    url = 'https://builder.guidebook.com/open-api/v1/custom-list-item-relations/'
    api_key = 'API_KEY'
    response = requests.get(guides_url, headers={'Authorization': 'JWT ' + api_key}).json()
    

    The above command returns JSON structured like this:

    {
      "count": 3,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 1,
          "custom_list": 1,
          "custom_list_item": 1,
          "rank": 3.25,
          "created_at": "2017-08-31T20:18:38.174876+0000"
        },
        {
          "id": 5,
          "custom_list": 1,
          "custom_list_item": 5,
          "rank": 3.3,
          "created_at": "2017-08-31T20:19:33.342154+0000"
        },
        {
          "id": 6,
          "custom_list": 1,
          "custom_list_item": 6,
          "rank": 4.1,
          "created_at": "2017-08-31T20:19:45.994749+0000"
        }
      ]
    }
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/custom-list-item-relations/

    Model Fields

    Same as the fields used in creation with the addition of the following read-only fields:

    Parameter Type Description
    id integer An unique identifier for your CustomListItemRelation.
    created_at datetime Time when this CustomListItemRelation was created - UTC.

    Filtering CustomListItemRelations

    To filter the returned CustomListItemRelations by the related CustomListItem you can include the query parameter custom_list_item. The following request, for examples, filters for CustomListItemRelations related to custom_list_item 5.

    GET https://builder.guidebook.com/open-api/v1/custom-list-item-relations/?custom_list_item=5

    To filter the returned CustomListItemRelations by the related CustomList you can include the query parameter custom_list. The following request, for examples, filters for CustomListItemRelations related to custom_list 1.

    GET https://builder.guidebook.com/open-api/v1/custom-list-item-relations/?custom_list=1

    You can combine the above two filters to do something like, "find the CustomListItemRelation that associates custom_list_item 5 with custom_list 1:"

    GET https://builder.guidebook.com/open-api/v1/custom-list-item-relations/?custom_list_item=5&custom_list=1

    Manipulating Individual CustomListItemRelations

    Update the rank of a CustomListItemRelation

    import requests
    
    url = 'https://builder.guidebook.com/open-api/v1/custom-list-item-relations/156/'
    api_key = 'API_KEY'
    patch_data =
    {
      "rank": 46.3
    }
    response = requests.patch(url, data=patch_data, headers={'Authorization': 'JWT ' + api_key}).json()
    

    PATCH requests (to update) and GET requests (to retrieve) an individual CustomListItemRelation will return a JSON structure like this:

    {
      "id": 156,
      "custom_list": 59,
      "custom_list_item": 369,
      "rank": 46.3,
      "created_at": "2017-09-22T20:18:38.174876+0000"
    }
    

    To access and manipulate an individual CustomListItemRelation object, use a url that ends with the id of a CustomListItemRelation object:

    https://builder.guidebook.com/open-api/v1/custom-list-item-relations/<custom_list_item_relation_id>/

    Retrieving a CustomListItemRelation

    In the following examples, we will assume that the id of the CustomListItemRelation we'd like to modify is 156. To retrieve an individual CustomListItemRelation object issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/custom-list-item-relations/156/

    Updating a CustomListItemRelation

    The only field that can be updated on CustomListItemRelation is rank. Attempts to modify, for example, the custom_list or custom_list_item fields on a CustomListItemRelation object will be ignored. To update the rank of a CustomListItemRelation, issue a PATCH request where the request body includes the new rank you'd like the CustomListItemRelation to have.

    PATCH https://builder.guidebook.com/open-api/v1/custom-list-item-relations/156/

    Deleting a CustomListItemRelation

    To delete a particular CustomListItemRelation, issue a DELETE request to the url that points to the specific CustomListItemRelation you'd like deleted:

    DELETE https://builder.guidebook.com/open-api/v1/custom-list-item-relations/156/

    Attendees

    Creating an Attendee

    import requests
    
    attendees_list_url =  'https://builder.guidebook.com/open-api/v1/attendees/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "email": "open_api@example.com",
        "first_name": "Open API",
        "last_name": "Example User"
    }
    response = request.post(attendees_list_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
        "id": 1,
        "guide_id": 1,
        "import_id": null,
        "account_id": 2,
        "first_name": "Open API",
        "last_name": "Example User",
        "email": "open_api@example.com",
        "avatar": null,
        "cover": null,
        "app_profile": {
            "website": "",
            "position": "",
            "company": "",
            "contact_email": ""
        },
        "revoked": false,
        "status": 0
    }
    
    

    This endpoint will create an Attendee that is owned by your Account. An Attendee is an object that formally defines a relation between a Guide and a Guidebook App end-user. When importing your Attendees, we will attempt to match to existing users in the Guidebook database. If no user is found via email matching, we will create a placeholder Account that the end-user can later claim by logging in. Email invite functionality is not available via the Open API. To send out email invites to your Attendees, please login to Builder and use the UI to send out email invites.

    The Attendee create operation is a special endpoint that we've made idempotent to facilitate client use cases. If an Attendee object already exists, we will return the Attendee object and the POST data supplied will be ignored and not treated as an update operation.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1/attendees/

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your Attendee belongs to. See section on Guides for more info.
    import_id no string A string field you can use to input your own identifier. This is for when you have your own IDs for Attendees in your data store.
    email yes string Email address of the Attendee. We will search existing Guidebook users and attempt to associate with an existing account.
    first_name no string First name of the Attendee. Only used if no existing Guidebook Account was found via email matching. Otherwise, this field is ignored.
    last_name no string Last name of the Attendee. Only used if no existing Guidebook Account was found via email matching. Otherwise, this field is ignored.

    Listing Attendees

    import requests
    
    attendees_url =  'https://builder.guidebook.com/open-api/v1/attendees/'
    api_key = 'API_KEY'
    
    # This will return all attendees you have access to
    response = request.get(attendees_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 4,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 2,
                "guide_id": 2,
                "account_id": 4,
                "import_id": null,
                "first_name": "",
                "last_name": "",
                "email": "a@example.com",
                "avatar": null,
                "cover": null,
                "app_profile": {
                    "website": "",
                    "position": "",
                    "company": "",
                    "contact_email": ""
                },
                "revoked": false,
                "status": 1
            },
            {
                "id": 3,
                "guide_id": 2,
                "account_id": 5,
                "import_id": null,
                "first_name": "",
                "last_name": "",
                "email": "b@example.com",
                "avatar": null,
                "cover": null,
                "app_profile": {
                    "website": "",
                    "position": "",
                    "company": "",
                    "contact_email": ""
                },
                "revoked": false,
                "status": 1
            },
            {
                "id": 4,
                "guide_id": 2,
                "account_id": 6,
                "import_id": null,
                "first_name": "",
                "last_name": "",
                "email": "c@example.com",
                "avatar": null,
                "cover": null,
                "app_profile": {
                    "website": "",
                    "position": "",
                    "company": "",
                    "contact_email": ""
                },
                "revoked": false,
                "status": 1
            },
            {
                "id": 5,
                "guide_id": 3,
                "account_id": 7,
                "import_id": null,
                "first_name": "",
                "last_name": "",
                "email": "d@example.com",
                "avatar": null,
                "cover": null,
                "app_profile": {
                    "website": "",
                    "position": "",
                    "company": "",
                    "contact_email": ""
                },
                "revoked": false,
                "status": 1
            }
        ]
    }
    

    This endpoint can also be used to read data on Attendees. Typically, this endpoint is called with a guide_id filter such that it returns a list of Attendees associated to a lone Guide object that is owned by you.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/attendees/

    Model Fields

    The fields returned in the GET responses are far more detailed and include the following fields:

    Parameter Type Description
    id integer An unique identifier for your Attendee.
    created_at datetime Time when this Attendee was created - UTC.
    guide_id integer The specific Guide your Attendee belongs to. See section on Guides for more info.
    account_id integer The unique ID for the Account object that this attendee is linked to.
    first_name string First name of the Attendee.
    last_name string Last name of the Attendee.
    email string Email address of the Attendee.
    avatar string URL to the avatar image for this Attendee.
    cover string URL to the cover (background) image for the Attendee.
    app_profile dictionary of strings Contains profile information filed out by the Attendee. Possible keys include company, position, contact_email, website. Note that these keys can change at anytime!
    revoked boolean Indicates if this Attendee still has access to this guide. This field is only relevant if your Guide is using the invite-only security option.
    status integer Integer status code. 0 - Attendee Created, 1 - New Account Created, Email Invite Sent, 2 - Existing Account matched, Email Invite Sent, 3 - Email Invite Accepted/Attendee Logged In.

    Filtering data by Guide id and other fields

    Including a query parameter guide allows you to filter for all Attendees related to a Guide you have access to (Guide 47 in the following example):

    GET https://builder.guidebook.com/open-api/v1/attendees/?guide=47

    You are also able to filter by the fields revoked and status if you want to fetch a list of Attendees fitting specific criteria. See examples below for how to filter on to these fields and combining multiple filters:

    GET https://builder.guidebook.com/open-api/v1/attendees/?guide=47&status=3

    GET https://builder.guidebook.com/open-api/v1/attendees/?guide=47&revoked=True

    Sorting Returned Data

    When fetching a list of your Attendees, you're also able to control the order of the returned data if this is important for your needs. The fields that you can sort by are email, first_name, last_name, revoked, and status. The following example will sort all Attendees from Guide 47 by email in alphabetical order:

    GET https://builder.guidebook.com/open-api/v1/attendees/?guide=47&ordering=email

    Prepending - in front of an ordering field reverses it. The following example with sort by last name in reverse alphabetical order and then do a secondary sort in alphabetical order by first name:

    GET https://builder.guidebook.com/open-api/v1/attendees/?guide=47&ordering=-last_name,first_name

    Retrieving an Attendee

    To retrieve an individual Attendee object issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/attendees/71/

    The above request will fetch data for the Attendee with the id 71.

    Updating Attendee info

    The Attendee object defines the relationship between an individual and a given Guide. Fields such as status can not be manipulated via the Open API. Additionally we do not allow you to manipulate the profile information of the individual accounts. These are controlled by the end-user themselves.

    There are two fields we allow you to update - revoked and import_id. Updating the revoked field will toggle access to an invite-only guide. If you have a public guide, this field will have no effect. The import_idfield acts as a link between the Attendee in Builder and the unique identifier of the related account in your system. In practice, this field should be populated during creation. However, if that is untenable, you can update that field at a later point in time via the Open API.

    Deleting an Attendee

    The Attendee object is a crucial component that's used in our metrics tracking system. In order to preserve the accuracy of metrics reports, we do NOT allow Attendee objects to be deleted once they been created. If you want to "revoke" a person's access to a specific guide, you would issue a PATCH request and set revoked=True.

    We do allow various Open API operations for objects that are related to an Attendee and a Guide. i.e Personalized Schedules for a given Attendee.

    Retrieving an Attendee In a Web View

    Starting in version 6.5.0 of the Guidebook mobile app (or in your branded app), you can now retrieve information about the current logged in user when they're viewing a Web View module. The id and the import_id of the current logged in Attendee is surfaced via javascript. After a guide Web View document has finished loading, the mobile app will call a javascript function named onGuidebookLoad, if it has been defined. In that function, or anytime after that function has been called, you can access the import-id and attendee-id on the global object Guidebook.

    HTML Example

    <!DOCTYPE html>
    <html>
    
    <head>
    <h3>Test for Attendee Webview</h3>
    <h3 id="error"></h3>
    </head>
    <body>
    
    <h4> Test for Attendee ID </h4>
    <p id="attendee-id">No attendee id</p>
    <p id="import-id">No import id</p>
    
    
    <script>
    function onGuidebookLoad(){
        if(Guidebook.attendee_id != null) {
            document.getElementById("attendee-id").innerHTML = "Attendee id: " + Guidebook.attendee_id;
        }
        if(Guidebook.import_id != null) {
            document.getElementById("import-id").innerHTML = "Import id: " + Guidebook.import_id;
        }
    }
    
    </script>
    
    </body>
    </html>
    

    To test the example, add a Web View feature to your guide in Builder, then upload the example HTML snippet. Login to the app on your mobile device, download the guide, then open the Web View you just created.

    AttendeeGroups

    AttendeeGroups allow you to collect 1 or more Attendee objects into a group.

    Creating an AttendeeGroup

    import requests
    
    attendee_groups_list_url =  'https://builder.guidebook.com/open-api/v1/attendee-groups/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "name": "Test AttendeeGroup created via the Open API"
    }
    
    response = request.post(attendee_groups_list_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
        "id": 1,
      "guide": 1,
      "name": "Test AttendeeGroup created via the Open API",
        "created_at": "2017-11-18T22:13:25.766623+0000"
    }
    
    
    

    This endpoint will create an AttendeeGroup that belongs to the given Guide. AttendeeGroups allow you to collect 1 or more Attendee objects into a group.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1/attendee-groups/

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your AttendeeGroup belongs to. See section on Guides for more info.
    name yes string A string to identify your AttendeeGroup with.

    Listing AttendeeGroups

    import requests
    
    attendee_groups_list_url =  'https://builder.guidebook.com/open-api/v1/attendee-groups/'
    api_key = 'API_KEY'
    
    # This will return all AttendeeGroups you have access to
    response = request.get(attendee_groups_list_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 3,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 1,
                "guide": 1,
          "name": "AttendeeGroup Example 1",
                "created_at": "2017-09-18T21:28:35.429989+0000"
            },
            {
          "id": 2,
                "guide": 1,
          "name": "AttendeeGroup Example 2",
                "created_at": "2017-10-18T21:28:35.429989+0000"
            },
        {
          "id": 3,
                "guide": 1,
          "name": "AttendeeGroup Example 3",
                "created_at": "2017-11-18T21:28:35.429989+0000"
            }
        ]
    }
    
    

    This endpoint can also be used to read AttendeeGroup data. Typically, this endpoint is called with a guide filter such that it returns a list of Attendees associated to a lone Guide object that is owned by you.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/attendee-groups/

    Model Fields

    Same as the fields used in creation with the addition of the following read-only fields:

    Parameter Type Description
    id integer An unique identifier for your AttendeeGroup.
    created_at datetime Time when this AttendeeGroup was created - UTC.

    Filtering data by Guide id and other fields

    Including a query parameter guide allows you to filter for all AttendeeGroups related to a Guide you have access to (Guide 47 in the following example):

    GET https://builder.guidebook.com/open-api/v1/attendee-groups/?guide=47

    Retrieving an AttendeeGroup

    To retrieve an individual AttendeeGroup object issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/attendee-groups/71/

    The above request will fetch data for the AttendeeGroup with the id 71.

    Retrieving the Attendees in an AttendeeGroup

    To retrieve all the current Attendees in an AttendeeGroup objects, issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/attendee-groups/71/attendees/

    The above request (which can be paged through) will return representations of the Attendee objects currently in the AttendeeGroup.

    Adding Attendees to an AttendeeGroup

    To add Attendees to an AttendeeGroup, issue a POST request like:

    POST https://builder.guidebook.com/open-api/v1/attendee-groups/71/add-attendees/

    The body of the POST request should be a dictionary like...{"attendees": [<attendee_id_1>, <attendee_id_2>, <attendee_id_n>]}.

    Removing Attendees from an AttendeeGroup

    To remove Attendess from an AttendeeGroup, issue a POST request like:

    POST https://builder.guidebook.com/open-api/v1/attendee-groups/71/remove-attendees/

    The body of the POST request should be a dictionary like...{"attendees": [<attendee_id_1>, <attendee_id_2>, <attendee_id_n>]}.

    Updating an AttendeeGroup

    To modify an existing AttendeeGroup object, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1/attendee-groups/71/

    You will only need to include the specific fields you are updating and not a full request body. Note than only the name field is updatable at this time.

    Deleting an AttendeeGroup

    To delete a particular AttendeeGroup, issue a DELETE request to the url that points to the specific AttendeeGroup you'd like deleted:

    DELETE https://builder.guidebook.com/open-api/v1/attendee-groups/71/

    PersonalizedSchedules

    Creating a PersonalizedSchedule

    import requests
    
    personalized_schedule_url =  'https://builder.guidebook.com/open-api/v1/personalized-schedules/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "name": "Test Personalized Schedule Created via the Open API",
        "attendees": [
            1,
            5
        ],
        "sessions": [
            13,
            42,
            47,
            101,
            118
        ]
    }
    response = request.post(personalized_schedule_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
        "id": 1,
        "guide": 18,
        "name": "Test Personalized Schedule Created via the Open API",
        "attendees": [
            1,
            5
        ],
        "sessions": [
            13,
            42,
            47,
            101,
            118
        ]
    }
    
    

    This endpoint will create a PersonalizedSchedule for your guide. PersonalizedSchedules have an email invite component that is not exposed via the Open API. To publish these schedules to the end-users and send out email notifications, please sign in to Builder and use the UI there to publish and send out emails.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1/personalized-schedules/

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific guide your PersonalizedSchedule belongs to. See section on Guides for more info.
    name yes string The title of your PersonalizedSchedule.
    attendees yes array of integers Array of IDs of Attendees this PersonalizedSchedule will be assigned to. See section on Attendees.
    sessions yes array of integers Array of IDs of Sessions this PersonalizedSchedule will contain. See section on Sessions.

    Listing PersonalizedSchedule

    import requests
    
    personalized_schedule_url =  'https://builder.guidebook.com/open-api/v1/personalized-schedules/'
    api_key = 'API_KEY'
    
    # This will return all `PersonalizedSchedule` you have access to
    response = request.get(personalized_schedule_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 1,
                "guide": 18,
                "name": "Example Schedule for Sales Team",
                "attendees": [
                    6,
                    7,
                    8
                ],
                "sessions": [
                    1,
                    2,
                    3
                ]
            },
            {
                "id": 2,
                "guide": 19,
                "name": "Example Schedule for Marketing Team",
                "attendees": [
                    9,
                    10,
                    11
                ],
                "sessions": [
                    4,
                    5,
                    6
                ]
            }
        ]
    }
    

    This endpoint can also be used to read data on PersonalizedSchedule.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/personalized-schedules/

    Model Fields

    Same as the fields used in creation with the addition of the following read-only fields

    Parameter Type Description
    id integer An unique identifier for your PersonalizedSchedule.
    created_at datetime Time when this PersonalizedSchedule was created - UTC.

    Filtering By Guide id

    Including a query parameter guide allows you to filter for all PersonalizedSchedule related to a Guide you have access to (Guide 47 in the following example):

    GET https://builder.guidebook.com/open-api/v1/personalized-schedules/?guide=47

    Retrieving a PersonalizedSchedule

    In the following examples, we will assume that the id of the PersonalizedSchedule we'd like to modify is 71. To retrieve an individual PersonalizedSchedule object issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1/personalized-schedules/71/

    Updating a PersonalizedSchedule

    To modify an existing PersonalizedSchedule object, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1/personalized-schedules/71/

    The only fields you will be able to update are sessions and attendees. Note that due to the complexity of PersonalizedSchedules, you'll need to sign into Builder UI and review the updates and publish updates to the app. Publishing these updates is not available via the Open API at this moment.

    Deleting a PersonalizedSchedule

    To delete a particular PersonalizedSchedule, issue a DELETE request to the url that points to the specific PersonalizedSchedule you'd like deleted:

    DELETE https://builder.guidebook.com/open-api/v1/personalized-schedules/71/

    Webhooks

    Whenever a metrics event fires. A POST request is made to your URL with data similar to the example below

    {
        "weid": "12345-e11fb47d-bb63-46f8-912c-9ba18c351970",
        "extra_metadata": null,
        "properties": {
            "first_name": "Example User",
            "last_name": "Last Name",
            "user_id": "11913",
            "guide_id": "61737",
            "company": "Guidebook",
            "session_id": "13745343",
            "email": "example_user@example.com",
            "guide_name": "Test Guide 1",
            "time": "2018-01-18T21:25:55.988868+0000",
            "position": "API Tester",
            "session_name": "Keynote Session: How to use the Open API",
        },
        "event": "MobileApp-UserRegisteredScheduleSession"
    }
    

    Guidebook offers a Webhook API to allow customers to monitor and process metrics events in their guide. Customers can get started by setting up their own Webhook URLs that will consume events. Once their Webhook URL is live, they can go into Guidebook Builder and supply the Webhook URL and configure the metrics events they want that URL to be notified of.

    Whenever a metrics event that you are monitoring occurs, we will immediately make a POST request to your Webhook with details of the metrics event.

    Event Dictionaries

    There are a variety of possible events that can fire. Each one will contain the following:

    Key Type Description
    weid string Unique id for this event. You can use the Open API to refetch this event data via weid if needed.
    event string The name of the event that happened.
    properties dictionary All the extra details of the event that fired. They keys will vary depending on type of event
    extra_metadata dictionary Usually null. This is a field for integrations that require extra configuration options.

    The properties dictionary will vary depending on the type of event that fired. Here is an outline of the possible keys for each event.

    Common properities available in most events

    Key Description
    time UTC Timestamp of when this event happened.
    guide_id The guide id this metrics event happened on.
    guide_name The guide name.
    user_id The id of the user who performed the action.
    first_name The first name of the user who performed the action.
    last_name The last name of the user who performed the action,
    company The company that the user filled out on their profile. Can be null.
    position The company that the user filled out on their profile. Can be null.
    email The email of the user.

    MobileApp-UserRegisteredScheduleSession

    Key Description
    session_id The id of the session the user registered for.
    session_name The name of the session the user registered for.

    MobileApp-UserMadeToDoItem

    Key Description
    custom_list_item_id The id of the custom list item the user added to their todo.
    custom_list_item_name The name of the custom list item the user added to their todo.

    MobileApp-UserPostedPhoto

    Key Description
    photo_id The id of the photo the user uploaded.

    MobileApp-UserTaggedOtherUser

    Key Description
    tagged_user_id The id of the user tagged.
    tagged_user_first_name The first name of the user tagged.
    tagged_user_last_name The last name of the user tagged.
    tagged_user_company The company that the tagged user filled out on their profile. Can be null.
    tagged_user_position The position that the tagged user filled out on their profile. Can be null.
    tagged_user_email The email for the tagged user.

    MobileApp-UserConnectionAccepted

    Key Description
    requesting_user_id The id of the user who requested the connection.
    requesting_user_first_name The first name of the requesting user.
    requesting_user_last_name The last name of the requesting user.
    requesting_user_company The company that the requesting user filled out on their profile. Can be null.
    requesting_user_position The position that the requesting user filled out on their profile. Can be null.
    requesting_user_email The email for the requesting user.

    MobileApp-UserCheckedIn

    Standard fields. No additional fields.

    Security

    When implementing your Webhook URL, please make sure to confirm that the POST data being sent to your Webhook is coming from Guidebook!! Each Webhook you set up on Guidebook will have an unique security token. This token will be visible on your Webhooks setup screen.

    This token will be included in ALL webhook POST requests from guidebook in the header. The header will be GB_WEBHOOK_SECURITY_TOKEN. Please verify that the token matches before processing the event data.

    Webhook Examples

    Guidebook's Salesforce integration was built on top of our Webhook API. For some example code on how you can customize your own Salesforce integration with our Webhook API, you can visit our github repo.