NAV Navbar
python
  • Introduction
  • Versioning
  • Example Implementations
  • Authentication
  • Pagination
  • Timezones + UTC
  • Images
  • HTML Text
  • Guides
  • Spaces
  • SpaceGuideAssociations
  • Sessions
  • ScheduleTracks
  • Locations
  • CustomLists
  • CustomListItems
  • CustomListItemRelations
  • Links
  • Link Categories
  • Quick Info
  • Inboxes
  • Messages
  • 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.
    204 No Content. Standard response when a DELETE operation is successful
    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.
    405 Method not allowed. Certain Objects only have limited methods allowed.
    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",
                "attendees_estimate": 1500,
                "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>",
                "attendees_estimate": null,
                "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.
    attendees_estimate int Estimated attendance of the Guide. Must be filled to publish.
    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.

    Publishing a Guide

    To publish an existing Guide object, issue a POST request like:

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

    A successful request to this endpoint will return a status code of 202 ACCEPTED

    To be successfully published, the guide must currently be on a paid plan and cannot be archived. Note that the act of publishing a Guide does not guarantee that it will appear in your space. Please see the documentation on Spaces and SpaceGuideAssociations for more information.

    Spaces

    A Space is a branded "container" for a customer's guides. A Space lives within a single custom MobileApp and/or one or more Guidebook flagship apps.

    Listing Spaces

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

    The above command returns JSON structured like this:

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 1,
                "name": "My Space",
                "description": "For all my conferences"
            },
            {
                "id": 2,
                "name": "My Other Space",
                "description": "For all my other conferences"
            }
        ]
    }
    

    HTTP Request

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

    Space Properties

    Property Type Description
    id int id of the Space object.
    name str Name of the Space.
    description str A description of the Space.

    SpaceGuideAssociations

    A SpaceGuideAssociation is used to represent the relationship between a guide and a Space. A guide will only be searchable in a given space if there is a SpaceGuideAssociation that links the two together.

    Creating a SpaceGuideAssociation

    import requests
    
    sga_url = 'https://builder.guidebook.com/open-api/v1/space-guide-associations/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "space": 1
    }
    response = requests.post(sga_url, headers={'Authorization': 'JWT ' + api_key}).json()
    

    The above commands return JSON structured like this:

    {
        "id": 1,
        "guide": 1,
        "space": 1
    }
    

    This endpoint will create a SpaceGuideAssociation between the specified Guide and Space.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1/space-guide-associations/

    SpaceGuideAssociation Properties

    Property Type Description
    id int id of the SpaceGuideAssociation object.
    guide int id of the related Guide object.
    space int id of the related Space object.

    Listing SpaceGuideAssociations

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

    The above command returns JSON structured like this:

    {
      "count": 2,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 1,
          "guide": 1,
          "space": 1
        },
        {
          "id": 2,
          "guide": 1,
          "space": 2
        }
      ]
    }
    

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

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1/space-guide-associations/

    Model Fields

    Same as the fields listed in the "SpaceGuideAssociation Properties" section above.

    Deleting a SpaceGuideAssociation

    import requests
    
    sga_url = 'https://builder.guidebook.com/open-api/v1/space-guide-associations/delete-by-space-guide-pair/?guide=<id>&space=<id>'
    api_key = 'API_KEY'
    
    response = requests.delete(sga_url, headers={'Authorization': 'JWT ' + api_key}).json()
    

    This endpoint will delete the SpaceGuideAssociation that is associated with the specified Guide and Space.

    HTTP Request

    DELETE https://builder.guidebook.com/open-api/v1/space-guide-associations/delete-by-space-guide-pair/?guide=1&space=1

    A successful request to this endpoint will return a status code of 204 NO CONTENT

    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/

    Links

    The Link resource is an object that is displayed at the bottom section of either a Session object or CustomListItem in the Guidebook mobile app. These objects represent special in-app links that will navigate the app user to the corresponding object in the mobile app. A common use case of this feature would be a speaker linking to all the panels that the speaker is participating in.

    Link objects will always contain a source and a target. In the example with speakers, the source would be the speaker CustomListItem and the target object would be a Session we want to link to.

    import requests
    
    link_url =  'https://builder.guidebook.com/open-api/v1/links/'
    api_key = 'API_KEY'
    post_data =
    {
        "_description": "testing overridden description",
        "target_object_id": 1,
        "source_object_id": 31,
        "source_content_type": "schedule.session",
        "guide": 7,
        "target_content_type": "custom_list.customlistitem"
    }
    response = request.post(link_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    
    

    The above commands return JSON structured like this:

    {
        "id": 33,
        "guide": 7,
        "source_content_type": "schedule.session",
        "target_content_type": "custom_list.customlistitem",
        "source_object_id": 31,
        "target_object_id": 1,
        "created_at": "2018-06-27T15:30:11.015128+0000",
        "rank": 0,
        "title": "Test List Item 1",
        "description": {
            "en-US": "testing overridden description"
        },
        "category_detail": {
            "id": 33,
            "name": "Items",
            "_name": "Items",
            "created_at": "2018-06-27T15:30:11.007205+0000",
            "rank": 2,
            "guide": 7
        },
        "category": 33,
        "_title": null,
        "_description": "testing overridden description"
    }
    
    

    This endpoint will create a Link for your Guide.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your Link belongs to. See section on Guides for more info.
    source_content_type yes string The content type of the source object. The options are: "schedule.session", "custom_list.customlistitem"
    source_object_id yes integer The id number of the source object. Not updatable after creation.
    target_content_type yes string The content type of the target object. The options are: "schedule.session", "custom_list.customlistitem"
    target_object_id yes integer The id number of the target object. Not updatable after creation.
    rank no integer The order the Link will appear in the Links section on the app. Links are displayed in ascending rank value. If no rank value is supplied on creation, a default rank is used.
    _title no string Use this field to override the default title of the Link. The default behavior is to derive the title from the target object
    _description no string Use this field to override the default description of the Link. The default behavior is to derive the description from the target object
    category no integer LinkCategory ID this Link will be displayed in. Most of the logic regarding LinkCategories are automatically handled for you so you do not need to supply an category ID. Use this field to update the category if needed.
    import requests
    
    link_url =  'https://builder.guidebook.com/open-api/v1/links/'
    api_key = 'API_KEY'
    
    # This will return all `Links` you have access to
    response = request.get(link_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 3,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 39,
                "guide": 12,
                "source_content_type": "schedule.session",
                "target_content_type": "schedule.session",
                "source_object_id": 37,
                "target_object_id": 38,
                "created_at": "2018-06-27T15:19:05.300403+0000",
                "rank": 0,
                "title": "session B",
                "description": {
                    "start_time": "2018-06-27 15:19:05.283843+00:00",
                    "end_time": "2018-06-27 16:19:05.283850+00:00"
                },
                "category_detail": {
                    "id": 39,
                    "name": "Sessions",
                    "_name": "Sessions",
                    "created_at": "2018-06-27T15:19:05.294694+0000",
                    "rank": 1,
                    "guide": 12
                },
                "category": 39,
                "_title": null,
                "_description": null
            },
            {
                "id": 40,
                "guide": 12,
                "source_content_type": "schedule.session",
                "target_content_type": "schedule.session",
                "source_object_id": 38,
                "target_object_id": 37,
                "created_at": "2018-06-27T15:19:05.310453+0000",
                "rank": 0,
                "title": "session A",
                "description": {
                    "start_time": "2018-06-27 15:19:05.281825+00:00",
                    "end_time": "2018-06-27 16:19:05.281833+00:00"
                },
                "category_detail": {
                    "id": 40,
                    "name": "Sessions",
                    "_name": "Sessions",
                    "created_at": "2018-06-27T15:19:05.304460+0000",
                    "rank": 1,
                    "guide": 12
                },
                "category": 40,
                "_title": null,
                "_description": null
            },
            {
                "id": 41,
                "guide": 12,
                "source_content_type": "schedule.session",
                "target_content_type": "schedule.session",
                "source_object_id": 37,
                "target_object_id": 39,
                "created_at": "2018-06-27T15:19:05.319159+0000",
                "rank": 0,
                "title": "session C",
                "description": {
                    "start_time": "2018-06-27 15:19:05.285326+00:00",
                    "end_time": "2018-06-27 16:19:05.285333+00:00"
                },
                "category_detail": {
                    "id": 39,
                    "name": "Sessions",
                    "_name": "Sessions",
                    "created_at": "2018-06-27T15:19:05.294694+0000",
                    "rank": 1,
                    "guide": 12
                },
                "category": 39,
                "_title": null,
                "_description": null
            }
        ]
    }
    

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

    HTTP Request

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

    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 Link.
    created_at datetime Time when this Link was created - UTC.
    title string Title that will be displayed in the app. To change this, please use the _title field.
    description string/dictionary Description that will be displayed in the app. To change this, please use the _description field.
    category_detail dictionary Extra metadata on the LinkCategory of this Link

    Filtering data by Guide id

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

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

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

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

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

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

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

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

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

    Link Categories

    The LinkCategory object is used to group together Links for display. LinkCategory objects are automatically managed as part of the creation of Link objects. Create operations are therefore not allowed on this object. You will only able to list, update, and delete LinkCategory objects via the API.

    Listing LinkCategories

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

    The above command returns JSON structured like this:

    {
        "count": 5,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 7,
                "name": "Sessions",
                "_name": "Sessions",
                "links": [
                    {
                        "id": 9,
                        "guide": 5,
                        "source_content_type": "schedule.session",
                        "target_content_type": "schedule.session",
                        "source_object_id": 7,
                        "target_object_id": 9,
                        "created_at": "2018-06-27T15:56:28.678935+0000",
                        "rank": 0,
                        "title": "session C",
                        "description": {
                            "start_time": "2018-06-27 15:56:28.641592+00:00",
                            "end_time": "2018-06-27 16:56:28.641600+00:00"
                        },
                        "category_detail": {
                            "id": 7,
                            "name": "Sessions",
                            "_name": "Sessions",
                            "created_at": "2018-06-27T15:56:28.651231+0000",
                            "rank": 1,
                            "guide": 5
                        },
                        "_title": null,
                        "_description": null
                    },
                    {
                        "id": 7,
                        "guide": 5,
                        "source_content_type": "schedule.session",
                        "target_content_type": "schedule.session",
                        "source_object_id": 7,
                        "target_object_id": 8,
                        "created_at": "2018-06-27T15:56:28.659284+0000",
                        "rank": 0,
                        "title": "session B",
                        "description": {
                            "start_time": "2018-06-27 15:56:28.639726+00:00",
                            "end_time": "2018-06-27 16:56:28.639733+00:00"
                        },
                        "category_detail": {
                            "id": 7,
                            "name": "Sessions",
                            "_name": "Sessions",
                            "created_at": "2018-06-27T15:56:28.651231+0000",
                            "rank": 1,
                            "guide": 5
                        },
                        "_title": null,
                        "_description": null
                    }
                ],
                "created_at": "2018-06-27T15:56:28.651231+0000",
                "rank": 1,
                "guide": 5
            },
            {
                "id": 8,
                "name": "Sessions",
                "_name": "Sessions",
                "links": [
                    {
                        "id": 8,
                        "guide": 5,
                        "source_content_type": "schedule.session",
                        "target_content_type": "schedule.session",
                        "source_object_id": 8,
                        "target_object_id": 7,
                        "created_at": "2018-06-27T15:56:28.669642+0000",
                        "rank": 0,
                        "title": "session A",
                        "description": {
                            "start_time": "2018-06-27 15:56:28.637319+00:00",
                            "end_time": "2018-06-27 16:56:28.637328+00:00"
                        },
                        "category_detail": {
                            "id": 8,
                            "name": "Sessions",
                            "_name": "Sessions",
                            "created_at": "2018-06-27T15:56:28.663602+0000",
                            "rank": 1,
                            "guide": 5
                        },
                        "_title": null,
                        "_description": null
                    }
                ],
                "created_at": "2018-06-27T15:56:28.663602+0000",
                "rank": 1,
                "guide": 5
            },
            {
                "id": 9,
                "name": "Sessions",
                "_name": "Sessions",
                "links": [
                    {
                        "id": 10,
                        "guide": 5,
                        "source_content_type": "schedule.session",
                        "target_content_type": "schedule.session",
                        "source_object_id": 9,
                        "target_object_id": 7,
                        "created_at": "2018-06-27T15:56:28.692462+0000",
                        "rank": 0,
                        "title": "session A",
                        "description": {
                            "start_time": "2018-06-27 15:56:28.637319+00:00",
                            "end_time": "2018-06-27 16:56:28.637328+00:00"
                        },
                        "category_detail": {
                            "id": 9,
                            "name": "Sessions",
                            "_name": "Sessions",
                            "created_at": "2018-06-27T15:56:28.685621+0000",
                            "rank": 1,
                            "guide": 5
                        },
                        "_title": null,
                        "_description": null
                    }
                ],
                "created_at": "2018-06-27T15:56:28.685621+0000",
                "rank": 1,
                "guide": 5
            },
            {
                "id": 10,
                "name": "Sessions",
                "_name": "Sessions",
                "links": [
                    {
                        "id": 11,
                        "guide": 6,
                        "source_content_type": "schedule.session",
                        "target_content_type": "schedule.session",
                        "source_object_id": 10,
                        "target_object_id": 11,
                        "created_at": "2018-06-27T15:56:28.703571+0000",
                        "rank": 0,
                        "title": "session E",
                        "description": {
                            "start_time": "2018-06-27 15:56:28.645808+00:00",
                            "end_time": "2018-06-27 16:56:28.645820+00:00"
                        },
                        "category_detail": {
                            "id": 10,
                            "name": "Sessions",
                            "_name": "Sessions",
                            "created_at": "2018-06-27T15:56:28.697603+0000",
                            "rank": 1,
                            "guide": 6
                        },
                        "_title": null,
                        "_description": null
                    }
                ],
                "created_at": "2018-06-27T15:56:28.697603+0000",
                "rank": 1,
                "guide": 6
            },
            {
                "id": 11,
                "name": "Sessions",
                "_name": "Sessions",
                "links": [
                    {
                        "id": 12,
                        "guide": 6,
                        "source_content_type": "schedule.session",
                        "target_content_type": "schedule.session",
                        "source_object_id": 11,
                        "target_object_id": 10,
                        "created_at": "2018-06-27T15:56:28.714641+0000",
                        "rank": 0,
                        "title": "session D",
                        "description": {
                            "start_time": "2018-06-27 15:56:28.643482+00:00",
                            "end_time": "2018-06-27 16:56:28.643489+00:00"
                        },
                        "category_detail": {
                            "id": 11,
                            "name": "Sessions",
                            "_name": "Sessions",
                            "created_at": "2018-06-27T15:56:28.707867+0000",
                            "rank": 1,
                            "guide": 6
                        },
                        "_title": null,
                        "_description": null
                    }
                ],
                "created_at": "2018-06-27T15:56:28.707867+0000",
                "rank": 1,
                "guide": 6
            }
        ]
    }
    

    This endpoint can be used to read data on LinkCategories.

    HTTP Request

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

    Model Fields

    Parameter Type Description
    id integer An unique identifier for your LinkCategory.
    created_at datetime Time when this LinkCategory was created - UTC.
    name string Title that will be displayed in the app. To change this, please use the _name field.
    _name string Used to override default title.
    links list List of the Link objects displayed in this category
    rank no integer

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

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

    Retrieving a LinkCategory

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

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

    Updating a LinkCategory

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

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

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

    Deleting a LinkCategory

    Deleting the last Link in a LinkCategory will auto delete the LinkCategory so you usually will not to perform this action. To delete a particular LinkCategory, issue a DELETE request to the url that points to the specific LinkCategory you'd like deleted:

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

    Quick Info

    The QuickInfo resource is an object that is displayed at the top section of a Guide, a Session or a CustomListItem. These objects contain small pieces of information that may be useful to the Guide,Session or CustomListItem they are located on. For example, the WIFI password of a room where a Session is located could easily be displayed by one of these objects.

    QuickInfo objects will always contain a target. In the example with WIFI, the target object would be the Session the WIFI password applies to. The title could then be WIFI, and content would be the actual password.

    Creating QuickInfo

    import requests
    
    quick_info_url =  'https://builder.guidebook.com/open-api/v1/quick-info/'
    api_key = 'API_KEY'
    post_data =
    {
        "target_object_id": 1,
        "guide": 7,
        "target_content_type": "custom_list.customlistitem",
        "title": "Test Title 1",
        "content": "Test Content 1"
    }
    response = request.post(quick_info_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    
    

    The above commands return JSON structured like this:

    {
        "id": 33,
        "guide": 7,
        "target_content_type": "custom_list.customlistitem",
        "target_object_id": 1,
        "created_at": "2018-06-27T15:30:11.015128+0000",
        "rank": 0,
        "title": "Test Title 1",
        "content": "Test Content 1"
    }
    
    

    This endpoint will create a QuickInfo for your Guide.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your QuickInfo belongs to. See section on Guides for more info.
    target_content_type yes string The content type of the target object. The options are: "guide.guide", schedule.session", "custom_list.customlistitem"
    target_object_id yes integer The id number of the target object. Not updatable after creation.
    title no string The title of the QuickInfo. If not provided, this defaults to "Title".
    content no string The content of the QuickInfo. If not provided, this defaults to "Content".
    rank no integer The order the QuickInfo will appear in the QuickInfo section on the app. If no rank value is supplied on creation, a default is used.

    Listing QuickInfo

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

    The above command returns JSON structured like this:

    {
        "count": 3,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 39,
                "guide": 12,
                "target_content_type": "schedule.session",
                "target_object_id": 38,
                "created_at": "2018-06-27T15:19:05.300403+0000",
                "rank": 0,
                "title": "Test Title 1",
                "content": "Test Content 1"
            },
            {
                "id": 40,
                "guide": 12,
                "target_content_type": "schedule.session",
                "target_object_id": 37,
                "created_at": "2018-06-27T15:19:05.310453+0000",
                "rank": 0,
                "title": "Test Title 2",
                "content": "Test Content 2"
            },
            {
                "id": 41,
                "guide": 12,
                "target_content_type": "schedule.session",
                "target_object_id": 39,
                "created_at": "2018-06-27T15:19:05.319159+0000",
                "rank": 0,
                "title": "Test Title 3",
                "content": "Test Content 3"
            }
        ]
    }
    

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

    HTTP Request

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

    Model Fields

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

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

    Filtering data by Guide id

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

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

    Retrieving a QuickInfo

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

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

    Updating a QuickInfo

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

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

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

    Deleting a QuickInfo

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

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

    Inboxes

    Inboxes are used to store Messages to your Attendees. At this current point in time, only GET operations are allowed for the Inbox object.

    Listing Inboxes

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

    The above command returns JSON structured like this:

    {
      "count": 3,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 172,
          "guide": 395,
          "name": "test box 1"
        },
        {
          "id": 173,
          "guide": 395,
          "name": "test box 2"
        },
        {
          "id": 174,
          "guide": 395,
          "name": "test box 3"
        }
      ]
    }
    

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

    HTTP Request

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

    Model Fields

    Parameter Type Description
    id integer An unique identifier for your Inbox.
    guide integer The specific Guide your Inbox belongs to. See section on Guides for more info.
    name string A string to identify your Inbox with.

    Filtering data by Guide id

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

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

    Retrieving an Inbox

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

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

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

    Messages

    Creating a Message

    import requests
    
    messages_list_url =  'https://builder.guidebook.com/open-api/v1/messages/'
    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": 35,
      "guide": 415,
      "inbox": 204,
      "title": "Title of Message",
      "message": "Message created from the Open API",
      "scheduled_send_time": "2018-09-13T03:54:09.238987+0000"
    }
    
    

    This endpoint will create a Message that is in an Inbox that is in your Guide. You can schedule the timing of when this Message will go live to your attendees.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your Message belongs to. See section on Guides for more info.
    inbox yes integer The specific Inbox your Message belongs to. See section on Inboxes for more info.
    title yes string A short title for your Message. This is the subject line that will be displayed. Limited to 80 characters.
    message no string Optional long message if you have more info to share. Limited to 1024 characters.
    scheduled_send_time no datetime Optional timestamp in UTC of when you want this Message to be sent to attendees. If left blank, it will default to the current time and the message is sent immediately.

    Listing Messages

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

    The above command returns JSON structured like this:

    {
      "count": 3,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 38,
          "guide": 427,
          "inbox": 219,
          "title": "Message 1",
          "message": "Hello",
          "scheduled_send_time": "2018-09-13T04:31:41.137633+0000"
        },
        {
          "id": 39,
          "guide": 427,
          "inbox": 219,
          "title": "Message 2",
          "message": "Hello Again",
          "scheduled_send_time": "2018-09-13T04:31:41.139402+0000"
        },
        {
          "id": 40,
          "guide": 427,
          "inbox": 219,
          "title": "Message 3",
          "message": "Good Bye",
          "scheduled_send_time": "2018-09-13T04:31:41.141097+0000"
        }
      ]
    }
    

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

    HTTP Request

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

    Model Fields

    The fields returned in the GET responses include an additionally field:

    Parameter Type Description
    id integer An unique identifier for your Message.

    Filtering data by Guide id and other fields

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

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

    Retrieving an Message

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

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

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

    Updating Message info

    You can update the title and message fields of your Message object. However, you will lose edit functionality once the scheduled_send_time is passed. Once your Message is sent out to Attendees, this action can not be undone.

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

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

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

    Deleting an Message

    To delete a particular Message, issue a DELETE request to the url that points to the specific Message you'd like deleted. Be very careful about deleting Messages that have been sent. The delete operation only removes the Message on the Guidebook side, users will retain the Messages they have downloaded on their devices.

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

    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,
        "last_email_send": null
    }
    
    

    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,
                "last_email_send": null
            },
            {
                "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,
                "last_email_send": null
            },
            {
                "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,
                "last_email_send": null
            },
            {
                "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,
                "last_email_send": null
            }
        ]
    }
    

    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.
    last_email_send datetime Time when an invite email was sent to this Attendee - UTC. Note that this field can be null if no emails have been sent.
    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.

    Sending Invite Emails to Attendees

    import requests
    
    attendees_email_url =  'https://builder.guidebook.com/open-api/v1/guides/47/send-attendee-invite-email/'
    api_key = 'API_KEY'
    
    post_data =
    {
        "attendees": [1,2,3,4,5]
    }
    response = request.post(attendees_email_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
        "successful_emails": [1,2,3]
    }
    

    Once your attendees are created in Builder, you can send them an invite email to download your guide or mobile app. A dedicated endpoint for this is located at.

    POST https://builder.guidebook.com/open-api/v1/guides/<GUIDE_ID>/send-attendee-invite-email/

    The example here will attempt to send invite emails to Attendees 1 through 5 on Guide 47. If you supply Attendee Ids that do not match the Guide, you will receive an error response. Additionally, this response is limited to a list of 500 Ids per request. If emails are successfully sent to the the Attendees, they will appear in the success response under the successful_emails key. Emails are rate limited to once per 24 hours. This limit is enforce based on the last_email_send field for each Attendee. In the code sample here, Attendees 4 & 5 had already been sent invite emails in the past 24 hours so they were not sent emails and therefore not in the successful_emails response list.

    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.