NAV Navbar
python
  • Introduction
  • Versioning
  • Example Implementations
  • Authentication
  • Pagination
  • Timezones + UTC
  • Images
  • HTML Text
  • Rate Limiting
  • Guides
  • GuideCategories
  • Spaces
  • SpaceGuideAssociations
  • Sessions
  • ScheduleTracks
  • Locations
  • Maps
  • CustomLists
  • CustomListItems
  • CustomListItemRelations
  • Gated Features
  • MenuItems
  • Folders
  • PDFs
  • WebViews
  • Videos
  • Links
  • Link Categories
  • Quick Info
  • Albums
  • Photos
  • Sponsors
  • Inboxes
  • Messages
  • Forms
  • QuestionSets
  • Questions
  • FormAnswerSets
  • Attendees
  • AttendeeGroups
  • Guidebook ID
  • PersonalizedSchedules
  • Webhooks
  • Guidebook Web
  • BuilderIcons
  • 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. Clients 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.

    Zenefits Integration

    Our Zenefits Integration example shows how you can import custom list item data into Guidebook from a Zenefits HR account. Zenefits holds a lot of information about a company and its employees, and you can customize this integration to import information relevant to your custom list and Guide.

    Google Drive Integration

    Our Google Drive Integration example shows how you can sync PDFs between Google Drive and Guidebook in real time. This integration watches a specified folder in Google Drive to track changes and create, update, or delete the related PDFs in Guidebook linked to custom list items.

    Authentication

    Example request that includes authentication:

    import requests
    
    api_url = 'https://builder.guidebook.com/open-api/v1.1/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. You can check out this support article to learn more about generating an API key.

    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.1/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

    Rate Limiting

    Guidebook enforces a global rate limit across all Open API endpoints. An account is allowed 2000 requests per day. If exceeded, any further requests will return a 429 response.

    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.1/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",
                "owner": 412,
                "timezone": "UTC",
                "created_at": "2018-05-28T21:53:31.010760+0000",
                "short_name": "summit2017",
                "category": []
            },
            {
                "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,
                "owner": 412,
                "timezone": "US/Pacific",
                "created_at": "2018-05-28T21:53:31.010760+0000",
                "short_name": "summit2018",
                "category": []
            }
        ]
    }
    

    HTTP Request

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

    Guide Properties

    Property Type Description
    id int id of the Guide object.
    created_at datetime Time when Guide was created -- in UTC.
    owner int id of the Account User or Organization that owns the Guide object.
    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.
    home_screen_menuitem int The id of the MenuItem you want on the homescreen of your Guide.
    privacy int Used for updating privacy options. 1 = Public Guide, 2 = Passphrase Guide, 3 = Invite Only Guide
    redeem_code str Optional paramater used when updating privacy options. If you choose privacy option 2, you'll need to supply the desired passphrase in this field. Note tha we only allow redeem_codes to be updated once per hour.
    short_name str The name used to construct the URL where people view your guide.
    category array of integers Array of IDs of GuideCategories this Guide is a part of. See section on GuideCategories.

    Filtering Guides by owner id.

    Including a query parameter owner allows you to filter for all Guides owned by a specific Account (Account 47 in this example):

    GET https://builder.guidebook.com/open-api/v1.1/guides/?owner=47

    Filtering Guides by category id.

    Including a query parameter category__id allows you to filter for all Guides belonging to a specific GuideCategory (GuideCategory 23 in this example):

    GET https://builder.guidebook.com/open-api/v1.1/guides/?category__id=23

    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.1/guides/21/

    Updating a Guide

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

    PATCH https://builder.guidebook.com/open-api/v1.1/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.1/guides/21/publish/

    A successful request to this endpoint will return a status code of 202 ACCEPTED. This endpoint has a rate limit of 2 requests per minute.

    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.

    Publishing PersonalizedSchedules for a Guide

    To publish all PersonalizedSchedules on a Guide object, issue a POST request like:

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

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

    To successfully publish personalized schedules for a guide, the guide must be on a Premium service level and must already be published.

    GuideCategories

    Creating a GuideCategory

    import requests
    
    guide_categories_url =  'https://builder.guidebook.com/open-api/v1.1/guide-categories/'
    api_key = 'API_KEY'
    post_data =
    {
        "name": "My Category",
        "description": "A Category for My Guides",
        "space": 3
    }
    
    response = requests.post(guide_categories_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
        "id": 1,
        "name": "My Category",
        "description": "A Category for My Guides",
        "space": 3
    }
    
    
    

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/guide-categories/

    Model Fields

    Parameter Required Type Description
    name yes string The title of your GuideCategory.
    space yes integer The id of the space that this GuideCategory belongs to. See section on Spaces.
    description no string A description of this GuideCategory.

    Listing GuideCategories

    This endpoint will list all GuideCategories that can be accessed by your Account.

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

    The above command returns JSON structured like this:

    {
        "count": 3,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 1,
                "name": "My Category",
                "description": "A Category for My Guides",
                "space": 3
            },
            {
                "id": 2,
                "name": "My Second Category",
                "description": "A Second Category for My Guides",
                "space": 3
            },
            {
                "id": 3,
                "name": "My Third Category",
                "description": "A Third Category for My Guides",
                "space": 7
            }
        ]
      }
    
    

    HTTP Request

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

    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 GuideCategory.

    Retrieving a GuideCategory

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

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

    Updating a GuideCategory

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

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

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

    Deleting a GuideCategory

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

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

    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.1/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",
                "owner": 413
            },
            {
                "id": 2,
                "name": "My Other Space",
                "description": "For all my other conferences",
                "owner": 413
            }
        ]
    }
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/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.
    owner int id of the Account User or Organization that owns the Space object.

    Filtering Space by owner id.

    Including a query parameter owner allows you to filter for all Spaces owned by a specific Account (Account 47 in this example):

    GET https://builder.guidebook.com/open-api/v1.1/spaces/?owner=47

    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.1/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.1/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

    
    sga_url = 'https://builder.guidebook.com/open-api/v1.1/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.1/space-guide-associations/

    Model Fields

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

    Deleting a SpaceGuideAssociation

    
    sga_url = 'https://builder.guidebook.com/open-api/v1.1/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.1/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.1/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,
        "rank": 0.0,
        "waitlist": false, 
        "require_login": false,
        "max_capacity": null,
        "registration_start_date": 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,
        "rank": 0.0,
        "waitlist": false, 
        "require_login": false,
        "max_capacity": null,
        "registration_start_date": 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,
        "rank": 0.0,
        "waitlist": false, 
        "require_login": false,
        "max_capacity": null,
        "registration_start_date": null
    }
    
    

    This endpoint will create a Session for your Guide.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/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 no 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.
    rank no float The order the Session will appear.
    registration_start_date no datetime The date from which users can start registering or add the current session to their personal schedule. Setting this field requires that require_login is true.
    require_login no boolean A boolean value indicating if a user needs to be logged in to add this Session to their schedule. Setting this field requires that add_to_schedule is true.
    waitlist no boolean A boolean value indicating if this Session should have a registration waitlist. This field requires that max_capacity is set.
    max_capacity no integer The number of people who can add this session. Setting this field requires that require_login is true.

    Listing Sessions

    import requests
    
    session_url =  'https://builder.guidebook.com/open-api/v1.1/sessions/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `Sessions` you have access to
    response = requests.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": 1,
                "locations": [],
                "schedule_tracks": [],
                "image": null,
                "rank": 0.0,
                "waitlist": false, 
                "require_login": false,
                "max_capacity": null,
                "registration_start_date": 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": 1,
                "locations": [],
                "schedule_tracks": [],
                "image": null,
                "rank": 0.0, 
                "require_login": false,
                "max_capacity": null,
                "registration_start_date": 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": 1,
                "locations": [],
                "schedule_tracks": [],
                "image": null,
                "rank": 0.0, 
                "require_login": false,
                "max_capacity": null,
                "registration_start_date": 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": 1,
                "locations": [],
                "schedule_tracks": [],
                "image": null,
                "rank": 0.0, 
                "require_login": false,
                "max_capacity": null,
                "registration_start_date": null
            }
        ]
    }
    
    

    The guide filter is required.

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

    The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/sessions/?guide=<guide_id>

    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.1/sessions/?guide=47

    You are also able to filter by the fields schedule_tracks, import_id, 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.1/sessions/?guide=47&schedule_tracks=3

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

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

    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.1/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.1/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.1/sessions/71/

    Updating a Session

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

    PATCH https://builder.guidebook.com/open-api/v1.1/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.1/sessions/71/

    Listing Sessions without an API Key

    If you're building a client side calendar application that needs read access to your Sessions, there are additional endpoint options available that allow you to list sessions without the need for an API Key. This option is only available for public events. Please contact Guidebook Support for additional details.

    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.1/schedule-tracks/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "name": "Test Schedule Track Created via the Open API",
        "color": "#000080"
    }
    
    response = requests.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",
        "import_id": null
    }
    
    
    

    This endpoint will create a ScheduleTrack for your guide.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/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.
    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 ScheduleTracks in your data store.

    Listing ScheduleTracks

    
    schedule_tracks_url =  'https://builder.guidebook.com/open-api/v1.1/schedule-tracks/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `ScheduleTracks` you have access to
    response = requests.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": 1,
                "name": "Test Track 1",
                "color": null,
                "import_id": null,
                "created_at": "2017-09-10T21:28:35.432366+0000"
            },
            {
                "id": 211,
                "guide": 1,
                "name": "Test Track 2",
                "color": null
            },
            {
                "id": 212,
                "guide": 1,
                "name": "Test Track 3",
                "color": null,
                "import_id": null,
                "created_at": "2017-09-11T21:28:35.432366+0000"
            },
            {
                "id": 213,
                "guide": 1,
                "name": "Test Track 4, Different Guide",
                "color": null,
                "import_id": null,
                "created_at": "2017-09-12T21:28:35.432366+0000"
            }
        ]
    }
    
    

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

    The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/schedule-tracks/?guide=<guide_id>

    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 and other fields

    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.1/schedule-tracks/?guide=47

    You are also able to filter by the fields import_id and id if you want to fetch a list of ScheduleTracks fitting specific criteria. See the examples below for how to filter on these fields:

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

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

    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.1/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.1/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.1/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.1/locations/'
    api_key = 'API_KEY'
    post_data =
    {
      "guide": 1,
      "name": "Stadium",
      "description": "None",
      "location_type": 3,
      "latitude": 37.3327,
      "longitude": -121.901236,
      "import_id": "None"
    }
    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.1/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 no float Latitude of this Location - only required if this Location is of type ("Google Maps Location").
    longitude no float Longitude of this Location - only required if this Location is of type ("Google Maps Location").
    address no 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.1/locations/?guide=1'
    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"
        }
      ]
    }
    

    The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/locations/?guide=<guide_id>

    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.1/locations/?location_type=2

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

    Manipulating Individual Locations

    Update the name of a Location

    
    url = 'https://builder.guidebook.com/open-api/v1.1/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.1/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.1/locations/89/

    Updating a Location

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

    PATCH https://builder.guidebook.com/open-api/v1.1/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.1/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. If you do not have the longitude and latitude for the venue, you can submit just the address dictionary and we will attempt to geocode the address to the closest longitude and latitude we can find.

    # First fetch the ID of the Main Venue object
    api_key = 'API_KEY'
    
    url = 'https://builder.guidebook.com/open-api/v1.1/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.1/locations/{}/'.format(main_venue_id)
    patch_data =
    {
      "latitude": 37.784172,
      "name": "Moscone Center",
      "longitude": -122.401558,
      "address": "{\"city\": \"San Francisco\", \"country\": \"U.S.A.\", \"zipcode\": \"94103\", \"state\": \"CA\", \"street\": \"747 Howard Street\", \"address\": \"Moscone Center\"}"
    }
    
    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"
        }
    }
    

    Maps

    The Maps resource is a static map image that can be added to your guide. Example Map uses include campus maps, internal floor plans, and/or booth layouts for an exhibit hall or poster session.

    Creating a Map

    import requests
    
    map_url =  'https://builder.guidebook.com/open-api/v1.1/maps/'
    api_key = 'API_KEY'
    
    post_data =
    {
        "guide": 1,
        "image": "map_image",
        "name": "MyMap",
        "description": "Event Map"
    }
    
    with open('your_map.jpg', 'rb') as map_image:
        response = requests.post(map_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    

    The above commands return JSON structured like this:

    {
        "guide": 1,
        "image": "http://s3.amazonaws.com/media.guidebook.com/upload/1/fsJcNBuRlw0MtNcIoC6MFBLicp43bp1q3L1y.jpg",
        "name": "MyMap",
        "description": "Event Map",
        "id": 7,
        "rank": 0.0
    }
    
    

    This endpoint will create a Map for your Guide.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your Map belongs to. See section on Guides for more info.
    image yes file Your image file. It must be either JPG or PNG, and between 1000x1000 and 2000x2000 pixels.
    name yes string Name of the Map.
    description no string Description that will be displayed in the app.
    rank no float The order the Map will appear.

    Listing Maps

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

    The above command returns JSON structured like this:

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 6,
                "guide": 1,
                "image": "http://s3.amazonaws.com/media.guidebook.com/upload/1/WH2CMLWJhbizmXD83qEm0GsiclZejP3QqNlf.png",
                "name": "AMap",
                "description": null,
                "rank": 0.0
            },
            {
                "id": 7,
                "guide": 1,
                "image": "http://s3.amazonaws.com/media.guidebook.com/upload/1/fsJcNBuRlw0MtNcIoC6MFBLicp43bp1q3L1y.jpg",
                "name": "MyMap",
                "description": "Event Map",
                "rank": 0.0
            }
        ]
    }
    
    

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

    The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/maps/?guide=<guide_id>

    Model Fields

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

    Parameter Type Description
    id integer A unique identifier for your Map.

    Filtering data by Guide id

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

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

    Retrieving a Map

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

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

    Updating a Map

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

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

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

    Deleting a Map

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

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

    CustomLists

    Creating a CustomList

    import requests
    
    custom_lists_url =  'https://builder.guidebook.com/open-api/v1.1/custom-lists/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "name": "Test Custom List Created via the Open API"
    }
    
    response = requests.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.1/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 filter such that it returns a list of CustomLists associated to a lone Guide object that is owned by you.

    The guide filter is required.

    
    custom_lists_url =  'https://builder.guidebook.com/open-api/v1.1/custom-lists/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all custom lists you have access to
    response = requests.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": 1,
                "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.1/custom-lists/?guide=<guide_id>

    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.1/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.1/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.1/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.1/custom-lists/71/

    CustomListItems

    Creating a CustomListItem

    import requests
    
    custom_list_item_url =  'https://builder.guidebook.com/open-api/v1.1/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 = requests.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",
        "last_updated": "2017-09-27T08:19:08.544919+0000",
        "image": null,
        "thumbnail": null,
        "contact_email": null
    }
    
    
    

    This endpoint will create a CustomListItem for your Guide.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/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 CustomListItem 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.
    contact_email no string An email for the item that users will be able to contact directly from the app or Guidebook Web.

    Listing CustomListItems

    
    custom_list_item_url =  'https://builder.guidebook.com/open-api/v1.1/custom-list-items/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `CustomListItems` you have access to
    response = requests.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": 1,
                "custom_lists": [
                    6
                ],
                "locations": [],
                "created_at": "2017-09-27T08:11:40.183229+0000",
                "last_updated": "2017-09-27T08:11:40.183229+0000",
                "image": null,
                "thumbnail": null,
                "contact_email": null
            },
            {
                "id": 2,
                "import_id": null,
                "name": "Test List Item 2",
                "description_html": null,
                "subtitle": null,
                "allow_rating": true,
                "guide": 1,
                "custom_lists": [
                    6
                ],
                "locations": [],
                "created_at": "2017-09-27T08:11:40.189964+0000",
                "last_updated": "2017-09-27T08:11:40.189964+0000",
                "image": null,
                "thumbnail": null,
                "contact_email": null
            },
            {
                "id": 3,
                "import_id": null,
                "name": "Test List Item 3",
                "description_html": null,
                "subtitle": null,
                "allow_rating": true,
                "guide": 1,
                "custom_lists": [
                    6
                ],
                "locations": [],
                "created_at": "2017-09-27T08:11:40.195613+0000",
                "last_updated": "2017-09-27T08:11:40.195613+0000",
                "image": null,
                "thumbnail": null,
                "contact_email": null
            },
            {
                "id": 4,
                "import_id": null,
                "name": "Test List Item 4, Different Guide",
                "description_html": null,
                "subtitle": null,
                "allow_rating": true,
                "guide": 1,
                "custom_lists": [
                    7
                ],
                "locations": [],
                "created_at": "2017-09-27T08:11:40.200571+0000",
                "last_updated": "2017-09-27T08:11:40.200571+0000",
                "image": null,
                "thumbnail": null,
                "contact_email": null
            }
        ]
    }
    
    

    This endpoint can also be used to read data on CustomListItems. The guide filter is required.

    HTTP Request

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

    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.
    last_updated datetime Time when this CustomListItem was last updated - 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.1/custom-list-items/?guide=47

    You are also able to filter by the fields custom_lists, import_id, 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.1/custom-list-items/?guide=47&custom_lists=12

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

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

    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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/custom-list-item-relations/?custom_list__guide=1'
    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"
        }
      ]
    }
    

    The custom_list__guide is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/custom-list-item-relations/?custom_list__guide=<guide_id>

    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.1/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.1/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.1/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.1/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.1/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.1/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.1/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.1/custom-list-item-relations/156/

    Gated Features

    The GatedFeature resource is responsible for limiting access to certain features in your Guide.

    Creating GatedFeatures

    import requests
    
    gated_feature_url =  'https://builder.guidebook.com/open-api/v1.1/gated-feature/'
    api_key = 'API_KEY'
    post_data =
    {
        "object_id": 2,
        "guide": 7,
        "content_type": "custom_list.customlist",
        "attendees": [],
        "groups": []
    }
    
    response = requests.post(gated_feature_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    
    

    The above commands return JSON structured like this:

    {
        "id": 1,
        "guide": 7,
        "content_type": "custom_list.customlist",
        "object_id": 2,
        "attendees": [],
        "groups": []
    }
    
    
    

    This endpoint will create a GatedFeature for your Guide.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/gated-features/

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your GatedFeature belongs to. See section on Guides for more info.
    content_type yes string The content type of the target object to gate. The options are: "custom_list.customlist"
    object_id yes integer The id number of the target object to gate. Not updatable after creation.
    attendees no list The list of attendees that should be able to access the gated object.
    groups no list The list of groups that should be able to access the gated object.

    Listing GatedFeatures

    
    gated_feature_url =  'https://builder.guidebook.com/open-api/v1.1/gated_features/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `GatedFeatures` you have access to
    response = requests.get(gated_feature_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,
                "content_type": "custom_list.customlist",
                "object_id": 2,
                "attendees": [
                    5
                ],
                "groups": [
                    10
                ]
            },
            {
                "id": 2,
                "guide": 1,
                "content_type": "custom_list.customlist",
                "object_id": 3,
                "attendees": [
                    5, 7
                ],
                "groups": [
                    10
                ]
            },
            {
                "id": 3,
                "guide": 1,
                "content_type": "custom_list.customlist",
                "object_id": 4,
                "attendees": [
                    23, 42
                ],
                "groups": []
            }
        ]
    }
    
    

    This endpoint can also be used to read data on GatedFeature. The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/gated-feature/?guide=<guide_id>

    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 GatedFeature.
    created_at datetime Time when this GatedFeature was created - UTC.

    Filtering data by Guide id

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

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

    Retrieving a GatedFeature

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

    GET https://builder.guidebook.com/open-api/v1.1/gated-features/71/

    Adding Attendees and Groups to a GatedFeature

    To add Attendees or Groups to a GatedFeature, issue a POST request like:

    POST https://builder.guidebook.com/open-api/v1.1/gated-features/71/add-access/

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

    Removing Attendees and Groups from a GatedFeature

    To remove Attendees or Groups from a GatedFeature, issue a POST request like:

    POST https://builder.guidebook.com/open-api/v1.1/gated-features/71/remove-access/

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

    Deleting a GatedFeature

    To delete a particular GatedFeature, issue a DELETE request to the url that points to the specific GatedFeature you'd like deleted. This will make the content object accessible to all users.

    DELETE https://builder.guidebook.com/open-api/v1.1/gated-features/71/

    MenuItems

    A MenuItem is an object that controls how a feature appears on builder and the mobile app. A MenuItem points to a specific object within a guide, such as a custom list, map, or schedule. They are used to navigate to different parts of a guide.

    You can group multiple MenuItems together by creating a Folder menu item. See the section on Folders.

    Creating a MenuItem

    import requests
    
    menu_item_url = 'https://builder.guidebook.com/open-api/v1.1/menu-items/'
    api_key = 'API_KEY'
    post_data = 
    {
        "object_id": 13,
        "guide": 7,
        "content_type": "custom_list.customlist"
    }
    
    response = requests.post(menu_item_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    

    The above commands return JSON structured like this:

    {
        "guide": 7,
        "content_type": "custom_list.customlist",
        "enabled": true,
        "object_id": 13,
        "id": 256,
        "created_at": "2019-01-18T20:22:44.804038Z",
        "folder": null,
        "rank": 0.0,
        "name": {"en-US": "Custom List"},
        "icon": "https://mediacdn.guidebook.com/upload/builderfile/c1c88374-2133-12ee-a0z1-3d957ascee78/rEiJ5EG43j0ViHVuWsXSuckPD0tlYAeYAugL.png"
    }
    
    
    

    This endpoint will create a MenuItem for the object related to the object_id and content_type that you specify.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/menu-items/

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your MenuItem belongs to. See section on Guides for more info.
    content_type yes string The content type of the object you want a MenuItem for. The allowed content types are custom_list.customlist, custom_list.customlistitem, schedule.scheduletrack, menuitem_data_pointer.mapspointer, photo.album, folder.folder, and uri_resource.webview.
    object_id sometimes integer The id number of the object you want a MenuItem for. If creating a Map menu item, this is not required.
    name no string The title of the MenuItem. If not provided, a default is used.
    rank no float The order the MenuItem will appear in the MenuItem section. If not provided, a default is used.
    folder no integer The id of the Folder you want this MenuItem to be in.
    enabled no boolean The enabled status of the MenuItem. If not provided, this defaults to True.
    builder_icon no integer The id of the BuilderIcon to use in setting the MenuItem icon.

    Listing MenuItems

    
    menu_item_url = 'https://builder.guidebook.com/open-api/v1.1/menu-items/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `MenuItem` you have access to
    response = requests.post(menu_item_url, headers={'Authorization': 'JWT ' + api_key}).json()
    
    

    The above command returns JSON structured like this:

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 159,
                "guide": 1,
                "content_type": "custom_list.customlist",
                "created_at": "2019-01-18T16:55:35.769347+0000",
                "rank": 0.0,
                "name": "Custom List Menu Item",
                "enabled": true,
                "object_id": 13,
                "folder": null,
                "icon": "https://mediacdn.guidebook.com/upload/builderfile/c1c88374-2133-12ee-a0z1-3d957ascee78/rEiJ5EG43j0ViHVuWsXSuckPD0tlYAeYAugL.png"
            },
            {
                "id": 160,
                "guide": 1,
                "content_type": "schedule.scheduletrack",
                "created_at": "2019-01-18T16:55:43.840032+0000",
                "rank": 0.0,
                "name": "Schedule Track Menu Item",
                "enabled": true,
                "object_id": 22,
                "folder": null,
                "icon": "https://mediacdn.guidebook.com/upload/builderfile/c1c88374-2133-12ee-a0z1-3d957ascee78/rEiJxEGdfd830ViHVuWs8dfds38csvDDklvd.png"
            }
        ]
    }
    
    

    This endpoint can also be used to read data on MenuItems. The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/menu-items/?guide=<guide_id>

    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 MenuItem.
    created_at datetime Time when this MenuItem was created - UTC.

    Filtering Data by Guide id

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

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

    Retrieving a MenuItem

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

    GET https://builder.guidebook.com/open-api/v1.1/menu-items/71/

    Updating a MenuItem

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

    PATCH https://builder.guidebook.com/open-api/v1.1/menu-items/71/

    You will only need to include the specific fields you are updating and not a full request body. Only name, rank, object_id, folder,and enabled are updatable after creation.

    Deleting a MenuItem

    DELETE requests are not supported for MenuItem objects. Instead, you can can issue a PATCH request to set the enabled status to False. This will hide the MenuItem from view.

    Folders

    A Folder is a container for MenuItems in your Guide. To view your Folder in your Guide, you must create a MenuItem for it. To add MenuItems to your Folder, you must update the folder field on the MenuItem object.

    Creating a Folder

    import requests
    
    folder_url =  'https://builder.guidebook.com/open-api/v1.1/folders/'
    api_key = 'API_KEY'
    
    post_data =
    {
        "guide": 7
    }
    
    response_1 = request.post(folder_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    

    The above commands return JSON structured like this:

    {
        "id": 1,
        "guide": 7,
        "menuitems": []
    }
    
    

    This endpoint will create a Folder for your Guide.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your Folder belongs to. See section on Guides for more info.

    Listing Folders

    
    folder_url =  'https://builder.guidebook.com/open-api/v1.1/folders/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `Folders` you have access to
    response = requests.get(folder_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,
                "menuitems": [
                    18
                ]
            },
            {
                "id": 2,
                "guide": 1,
                "menuitems": []
            },
            {
                "id": 3,
                "guide": 1,
                "menuitems": [
                    20,
                    7,
                    2
                ]
            }
        ]
    }
    
    

    This endpoint can also be used to read data on Folders. The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/folders/?guide=<guide_id>

    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 Folder.
    menuitems array of integers A list of ids of MenuItems in the Folder

    Filtering data by Guide id

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

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

    Retrieving a Folder

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

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

    Updating a Folder

    The Folder object does not have any updatable fields. To add a MenuItem to a Folder, see the section on MenuItems

    Deleting a Folder

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

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

    This will not delete the MenuItems inside the folder, only the Folder itself. Any MenuItems that were in the Folder will appear on the home screen. Note that their ranks will remain unchanged from being in the Folder, so they may need to be updated to be in the correct order.

    PDFs

    Some resources (like Sessions and CustomListItems) can be associated with PDFs that you upload to your guide. To create a reference to a PDF, see the section on Links. A PDF name is derived from the Link _title field, and if not provided, will default to the name on the pdf file.

    Creating a PDF

    import requests
    
    pdf_url =  'https://builder.guidebook.com/open-api/v1.1/pdf/'
    api_key = 'API_KEY'
    # Example with pdf url
    post_data =
    {
        "pdf_view_type": "url",
        "guide": 1,
        "url": "http://dropbox.com/mypdf.pdf",
        "include": false
    }
    
    response_1 = request.post(pdf_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    # Example with pdf file
    post_data =
    {
        "pdf_view_type": "pdf",
        "guide": 1,
        "pdf_file": "pdf_file",
        "include": true
    }
    
    with open('your_pdf.pdf', 'rb') as pdf_file:
        response_2 = request.post(pdf_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    

    The above commands return JSON structured like this:

    # Example with pdf url
    {
        "id": 7,
        "pdf_view_type": "url",
        "guide": 1,
        "url": "http://dropbox.com/mypdf.pdf",
        "pdf_file": null,
        "last_updated": "2018-06-27T15:30:11.015128+0000"
    }
    
    # Example with pdf file
    {
        "id": 8,
        "pdf_view_type": "pdf",
        "guide": 1,
        "url": null,
        "pdf_file": "http://s3.amazonaws.com/media.guidebook.com/upload/1/ZzpZyJOHxr8hkTAz9yC7h7zz5BWQ2URwjbtW.pdf",
        "last_updated": "2018-06-27T15:30:11.015128+0000"
    }
    
    

    This endpoint will create a PDF for your Guide.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your PDF belongs to. See section on Guides for more info.
    pdf_view_type yes string This field is used to indicate the format of your input file. The options are url and pdf.
    url no string URL of your PDF, if pdf_view_type is set to URL.
    pdf_file no file Your pdf file, if pdf_view_type is set to PDF.
    include no boolean Indicates if the file should be included in the initial guide download. Default is False. For best results, please limit the total number of documents included in the initial download to 20 MB.

    Listing PDFs

    
    pdf_url =  'https://builder.guidebook.com/open-api/v1.1/pdfs/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `PDFs` you have access to
    response = requests.get(pdf_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 7,
                "pdf_view_type": "url",
                "guide": 1,
                "url": "http://dropbox.com/mypdf.pdf",
                "pdf_file": null,
                "last_updated": "2018-06-27T15:30:11.015128+0000"
            },
            {
                "id": 8,
                "pdf_view_type": "pdf",
                "guide": 1,
                "url": null,
                "pdf_file": "http://s3.amazonaws.com/media.guidebook.com/upload/1/0Ezkq41pl591ayQEQTETToV2ml5mhTQn3V5l.pdf",
                "last_updated": "2018-06-27T15:30:11.015128+0000"
            }
        ]
    }
    
    

    This endpoint can also be used to read data on PDFs. The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/pdfs/?guide=<guide_id>

    Model Fields

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

    Parameter Type Description
    id integer A unique identifier for your PDF.
    last_updated datetime Time when this PDF was last updated - UTC.

    Filtering data by Guide id

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

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

    Retrieving a PDF

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

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

    Updating a PDF

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

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

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

    Deleting a PDF

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

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

    WebViews

    You can create a WebView in your guide that displays an html page or external url. To view your WebView in a guide, you must either create a MenuItem for it, or reference it in a Link.

    Creating a WebView

    import requests
    
    webview_url =  'https://builder.guidebook.com/open-api/v1.1/webviews/'
    api_key = 'API_KEY'
    
    # Example with webview url
    post_data =
    {
        "webview_type": "url",
        "guide": 1,
        "url": "http://www.google.com",
        "name": "My Other Webview"
    }
    
    response_1 = request.post(webview_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    # Example with webview html file
    post_data =
    {
        "webview_type": "html",
        "guide": 1,
        "html_file": "html_file",
        "name": "My Webview"
    }
    
    with open('your_file.html', 'rb') as html_file:
        response_2 = request.post(webview_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    

    The above commands return JSON structured like this:

    # Example with webview url
    {
        "id": 7,
        "webview_type": "url",
        "guide": 1,
        "url": "http://www.google.com",
        "html_file": null,
        "name": "My Other Webview"
    }
    
    # Example with webview html file
    {
        "id": 8,
        "webview_type": "html",
        "guide": 1,
        "url": null,
        "html_file": "http://s3.amazonaws.com/media.guidebook.com/upload/1/xB9v4xZMKeFpXfQsCe6LAVLkJS8WJ3UKlOcf.html",
        "name": "My Webview"
    }
    
    

    This endpoint will create a WebView for your Guide.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    name no string The name for your Webview object.
    guide yes integer The specific Guide your WebView belongs to. See section on Guides for more info.
    webview_type yes string This field is used to indicate the type of WebView you want to create. The options are url and html.
    url no string URL for your WebView, if webview_type is set to URL.
    html_file no file HTML file for your WebView, if webview_type is set to html. The maximum file name is 90 characters long, including the file extension.

    Listing WebViews

    import requests
    
    webview_url =  'https://builder.guidebook.com/open-api/v1.1/webviews/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `WebViews` you have access to
    response = requests.get(webview_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 7,
                "webview_type": "url",
                "guide": 1,
                "url": "https://www.google.com",
                "html_file": null,
                "name": "My Other Webview"
            },
            {
                "id": 8,
                "webview_type": "html",
                "guide": 1,
                "url": null,
                "html_file": "http://s3.amazonaws.com/media.guidebook.com/upload/1/xB9v4xZMKeFpXfQsCe6LAVLkJS8WJ3UKlOcf.html",
                "name": "My Webview"
            }
        ]
    }
    
    

    This endpoint can also be used to read data on WebViews. The guide filter is required'

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/webviews/?guide=<guide_id>

    Model Fields

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

    Parameter Type Description
    id integer A unique identifier for your WebView.

    Filtering data by Guide id

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

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

    Retrieving a WebView

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

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

    Updating a WebView

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

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

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

    Deleting a WebView

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

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

    Videos

    Sessions can be associated with Videos that you add to your guide. To create a reference to a Video, see the section on Links. Videos are created by providing the link to the video. Only Youtube, Vimeo, and Twitch videos are supported.

    Creating a Video

    import requests
    
    video_url =  'https://builder.guidebook.com/open-api/v1.1/videos/'
    api_key = 'API_KEY'
    
    post_data =
    {
        "guide": 1,
        "url": "https://www.youtube.com/watch?v=1111"
    }
    
    response_1 = request.post(video_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    

    The above commands return JSON structured like this:

    
    {
        "platform": "Youtube",
        "start_time": null,
        "end_time": null,
        "banner_url": "https://i.ytimg.com/vi/ZS9dYbjC6i8/maxresdefault_live.jpg",
        "title": "My First Video",
        "video_id": "1111",
        "url": "https://www.youtube.com/watch?v=1111",
        "video_type": "ondemand",
        "thumbnail_url": "https://i.ytimg.com/vi/ZS9dYbjC6i8/sddefault_live.jpg",
        "id": 7,
        "duration": 60,
        "guide": 1
    }
    
    

    This endpoint will create a Video for your Guide.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your Video belongs to. See section on Guides for more info.
    url yes string URL of your Video on Youtube, Vimeo, or Twitch.

    Listing Videos

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

    The above command returns JSON structured like this:

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "platform": "Youtube",
                "start_time": null,
                "end_time": null,
                "banner_url": "https://i.ytimg.com/vi/ZS9dYbjC6i8/maxresdefault_live.jpg",
                "title": "My First Video",
                "video_id": "1111",
                "url": "https://www.youtube.com/watch?v=1111",
                "video_type": "ondemand",
                "thumbnail_url": "https://i.ytimg.com/vi/ZS9dYbjC6i8/sddefault_live.jpg",
                "id": 7,
                "duration": 60,
                "guide": 1
            },
            {
                "platform": "Vimeo",
                "start_time": null,
                "end_time": null,
                "banner_url": "https://i.vimeocdn.com/video/45635537_1280x960.jpg?r=pad",
                "title": "My Second Video",
                "video_id": "2222",
                "url": "https://www.youtube.com/watch?v=2222",
                "video_type": "ondemand",
                "thumbnail_url": "https://i.vimeocdn.com/video/45635537_640x360.jpg?r=pad",
                "id": 8,
                "duration": 237,
                "guide": 1
            }
        ]
    }
    
    

    This endpoint can also be used to read data on Videos. A Video object has a lot more metadata than just the url and guide you set on creation. Most of this is determined by the platform that hosts the video.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/videos/?guide=<guide_id>

    Model Fields

    Parameter Type Description
    id integer A unique identifier for your Video.
    platform string The platform that your Video is hosted on. The options are Youtube, Vimeo, or Twitch.
    video_id string The id of your Video on its hosting platform.
    video_type string Indicates if the Video is live or ondemand.
    title string The title of your Video on its hosting platform.
    duration float The duration of your Video in seconds, if is is on demand.
    start_time datetime The scheduled start time of your Video, if it is live.
    end_time datetime The scheduled end time of your Video, if it is live.
    thumbnail_url url The url for the thumbnail image of your Video.
    banner_url url The url for the banner image of your Video.

    Filtering data by Guide id

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

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

    Retrieving a Video

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

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

    Updating a Video

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

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

    You will only need to include the specific fields you are updating and not a full request body. The fields that are allowed to be updated include: title, duration, start_time, end_time, thumbnail_url, and banner_url.

    Refreshing Video Metadata

    To request a video to be synced with the data on its respective platform, you may send a request to refresh a Video's metadata. This will automatically update any fields that have been changed on Youtube, Twitch, or Vimeo. To refresh the metadata of a Video, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1.1/videos/71/refresh-metadata/

    No fields are required for this request. This endpoint has a rate limit of 3 requests per hour.

    Deleting a Video

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

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

    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.1/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 = requests.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.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.0,
            "guide": 7
        },
        "category": 33,
        "_title": null,
        "_description": "testing overridden description",
        "last_updated": "2018-06-27T15:30:11.015128+0000"
    }
    
    
    

    This endpoint will create a Link for your Guide.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/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, uri_resource.pdffile, uri_resource.webview, and uri_resource.video.
    target_object_id yes integer The id number of the target object. Not updatable after creation.
    rank no float 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. Targets such as PDFs do not have their own title field, and depend on this to be given a custom name.
    _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.1/links/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `Links` you have access to
    response = requests.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": 1,
                "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.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.0,
                    "guide": 1
                },
                "category": 39,
                "_title": null,
                "_description": null,
                "last_updated": "2018-06-27T15:30:11.015128+0000"
            },
            {
                "id": 40,
                "guide": 1,
                "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.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.0,
                    "guide": 1
                },
                "category": 40,
                "_title": null,
                "_description": null,
                "last_updated": "2018-06-27T15:30:11.015128+0000"
            },
            {
                "id": 41,
                "guide": 1,
                "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.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.0,
                    "guide": 1
                },
                "category": 39,
                "_title": null,
                "_description": null,
                "last_updated": "2018-06-27T15:30:11.015128+0000"
            }
        ]
    }
    
    

    This endpoint can also be used to read data on Links. The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/links/?guide=<guide_id>

    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
    last_updated datetime Time when this Link was last updated - UTC.

    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.1/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.1/links/71/

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

    PATCH https://builder.guidebook.com/open-api/v1.1/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.1/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.1/link-categories/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `Links` you have access to
    response = requests.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": 1,
                        "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.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.0,
                            "guide": 1
                        },
                        "_title": null,
                        "_description": null
                    },
                    {
                        "id": 7,
                        "guide": 1,
                        "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.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.0,
                            "guide": 1
                        },
                        "_title": null,
                        "_description": null
                    }
                ],
                "created_at": "2018-06-27T15:56:28.651231+0000",
                "rank": 1.0,
                "guide": 1
            },
            {
                "id": 8,
                "name": "Sessions",
                "_name": "Sessions",
                "links": [
                    {
                        "id": 8,
                        "guide": 1,
                        "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.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.0,
                            "guide": 1
                        },
                        "_title": null,
                        "_description": null
                    }
                ],
                "created_at": "2018-06-27T15:56:28.663602+0000",
                "rank": 1.0,
                "guide": 1
            },
            {
                "id": 9,
                "name": "Sessions",
                "_name": "Sessions",
                "links": [
                    {
                        "id": 10,
                        "guide": 1,
                        "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.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.0,
                            "guide": 1
                        },
                        "_title": null,
                        "_description": null
                    }
                ],
                "created_at": "2018-06-27T15:56:28.685621+0000",
                "rank": 1.0,
                "guide": 1
            },
            {
                "id": 10,
                "name": "Sessions",
                "_name": "Sessions",
                "links": [
                    {
                        "id": 11,
                        "guide": 1,
                        "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.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.0,
                            "guide": 1
                        },
                        "_title": null,
                        "_description": null
                    }
                ],
                "created_at": "2018-06-27T15:56:28.697603+0000",
                "rank": 1.0,
                "guide": 1
            },
            {
                "id": 11,
                "name": "Sessions",
                "_name": "Sessions",
                "links": [
                    {
                        "id": 12,
                        "guide": 1,
                        "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.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.0,
                            "guide": 1
                        },
                        "_title": null,
                        "_description": null
                    }
                ],
                "created_at": "2018-06-27T15:56:28.707867+0000",
                "rank": 1.0,
                "guide": 1
            }
        ]
    }
    
    

    This endpoint can be used to read data on LinkCategories. The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/link-categories/?guide=<guide_id>

    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 float The order the LinkCategory will appear in the Links section on the app. LinkCategories are displayed in ascending rank value. If no rank value is supplied on creation, a default rank is used.

    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.1/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.1/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.1/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.1/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.1/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 = requests.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.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.1/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 float 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.1/quick-info/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `QuickInfo` you have access to
    response = requests.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": 1,
                "target_content_type": "schedule.session",
                "target_object_id": 38,
                "created_at": "2018-06-27T15:19:05.300403+0000",
                "rank": 0.0,
                "title": "Test Title 1",
                "content": "Test Content 1"
            },
            {
                "id": 40,
                "guide": 1,
                "target_content_type": "schedule.session",
                "target_object_id": 37,
                "created_at": "2018-06-27T15:19:05.310453+0000",
                "rank": 0.0,
                "title": "Test Title 2",
                "content": "Test Content 2"
            },
            {
                "id": 41,
                "guide": 1,
                "target_content_type": "schedule.session",
                "target_object_id": 39,
                "created_at": "2018-06-27T15:19:05.319159+0000",
                "rank": 0.0,
                "title": "Test Title 3",
                "content": "Test Content 3"
            }
        ]
    }
    
    

    This endpoint can also be used to read data on QuickInfo. The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/quick-info/?guide=<guide_id>

    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.1/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.1/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.1/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.1/quick-info/71/

    Albums

    Albums are used to store Photos in your Guide.

    Creating Albums

    import requests
    
    albums_url =  'https://builder.guidebook.com/open-api/v1.1/albums/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "name": "My Photo Album"
    }
    
    response = requests.post(albums_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
        "id": 8,
        "guide": 1,
        "name": "My Photo Album",
        "read_only": false
    }
    
    
    

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your Album belongs to. See section on Guides for more info.
    name yes string The title of your Album.
    read_only no boolean A booelan value that indicates whether or not users are allowed to upload Photos to this Album.

    Listing Albums

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

    The guide filter is required.

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

    The above command returns JSON structured like this:

    {
        "count": 3,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 6,
                "guide": 1,
                "name": "Photo Album",
                "read_only": false
            },
            {
                "id": 7,
                "guide": 1,
                "name": "Photo Album",
                "read_only": false
            },
            {
                "id": 8,
                "guide": 1,
                "name": "My Photo Album",
                "read_only": false
            }
        ]
    }
    
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/albums/?guide=<guide_id>

    Model Fields

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

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

    Filtering By Guide id

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

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

    Retrieving an Album

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

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

    Updating an Album

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

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

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

    Deleting an Album

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

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

    Photos

    The Photo resource is a way to create a photo that can be viewed and shared within an Album. To create an Album for a Photo, see the section on Albums.

    Creating a Photo

    import requests
    
    photo_url =  'https://builder.guidebook.com/open-api/v1.1/photos/'
    api_key = 'API_KEY'
    
    post_data =
    {
        "album": 5,
        "caption": "My Caption",
        "image": "photo"
    }
    
    with open('photo.png', 'rb') as photo:
        response = requests.post(photo_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    

    The above commands return JSON structured like this:

    {
        "id": 7,
        "album": 5,
        "caption": "My Caption",
        "image": "http://s3.amazonaws.com/media.guidebook.com/upload/1/albums/1/68e60d71-cbd3-493d-a167-a634f1506c74.jpg",
        "report_value": 0
    }
    
    

    This endpoint will create a Photo for your Album.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    album yes integer The specific Album your Photo belongs to. See section on Guides for more info.
    image yes file Your image file. It must be a PNG or JPEG.
    caption no string A caption to be displayed with your image.

    Listing Photos

    
    photo_url =  'https://builder.guidebook.com/open-api/v1.1/photos/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `Photos` you have access to
    response = requests.get(photo_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 3,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 5,
                "album": 5,
                "caption": "A Caption",
                "image": "http://s3.amazonaws.com/media.guidebook.com/upload/1/albums/1/53dd401a-fe27-4e08-ad45-8d661bf6d9e0.png",
                "report_value": 0
            },
            {
                "id": 6,
                "album": 5,
                "caption": "Another Caption",
                "image": "http://s3.amazonaws.com/media.guidebook.com/upload/1/albums/1/78123f55-cf0e-4746-bd76-aa0ddcc29789.png",
                "report_value": 0
            },
            {
                "id": 7,
                "album": 5,
                "caption": "My Caption",
                "image": "http://s3.amazonaws.com/media.guidebook.com/upload/1/albums/1/68e60d71-cbd3-493d-a167-a634f1506c74.jpg",
                "report_value": 0
            }
        ]
    }
    
    

    This endpoint can also be used to read data on Photos. The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/photos/?guide=<guide_id>

    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 Photo.
    report_value integer The number of times a Photo has been reported.

    Filtering data by Album id

    Including a query parameter album allows you to filter for all Photos related to an Album you have access to (Album 47 in this example):

    GET https://builder.guidebook.com/open-api/v1.1/photos/?album=47

    Retrieving a Photo

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

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

    Updating a Photo

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

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

    You will only need to include the specific fields you are updating and not a full request body. The image field is not updatable.

    Deleting a Photo

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

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

    Sponsors

    The Sponsors resource is a way to create a banner ad in your guide. Banner ads appear at the bottom of the navigation menu.

    Creating a Sponsor

    import requests
    
    sponsor_url =  'https://builder.guidebook.com/open-api/v1.1/sponsors/'
    api_key = 'API_KEY'
    
    post_data =
    {
        "guide": 5,
        "banner_url": "https://guidebook.com/",
        "name": "MySponsor",
        "banner_image": "banner_image",
        "website_only": true
    }
    
    with open('banner.png', 'rb') as banner_image:
        response = requests.post(sponsor_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    

    The above commands return JSON structured like this:

    {
        "id": 15,
        "guide": 5,
        "banner_url": "https://guidebook.com/",
        "name": "MySponsor",
        "duration": 5,
        "banner_image": "http://s3.amazonaws.com/media.guidebook.com/upload/5/6FTfnJ2M7YqbA0bX7aDiAIKXTGydE58Rdk66.png",
        "enabled": false,
        "banner_url_text": null,
        "website_only": true,
        "description_html": null
    }
    
    

    This endpoint will create a Sponsor for your Guide.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your Sponsor belongs to. See section on Guides for more info.
    name yes string Name of the Sponsor.
    banner_image yes file Your image file. It must be a PNG of size 600x110 pixels.
    website_only no boolean Indicates if a banner should launch directly to the banner_url, or to the description_html. The default is False, meaning that when a user taps on the banner in their device, they will be launched to banner_url_text.
    banner_url sometimes string The url that your banner_image should direct to when clicked on. This is required if website_only is True.
    banner_url_text sometimes string A sponsor description that is displayed instead of directing the user to the banner_url. This is required if website_only is False.
    description_html no string Optional html field to describe your Sponsor. Only rendered if website_only is False. This field supports basic HTML. See section on html text.
    duration no integer The number of seconds that a banner is displayed for. Options are 5, 10, 20, and 30 seonds. If not provided, it defaults to 5 seconds.
    enabled no boolean Indicates if the Sponsor banner should show up in the guide. The default is True.

    Listing Sponsors

    
    sponsor_url =  'https://builder.guidebook.com/open-api/v1.1/sponsors/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `Sponsors` you have access to
    response = requests.get(sponsor_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 14,
                "guide": 1,
                "banner_url": "https://www.google.com/",
                "name": "A Sponsor",
                "duration": 10,
                "banner_image": "http://s3.amazonaws.com/media.guidebook.com/upload/7/AHbKlnQeA4PPbV7MFxwRlOa8sPkzyMyaHorZ.png",
                "enabled": true,
                "banner_url_text": "Sponsor Description",
                "website_only": false,
                "description_html": null
            },
            {
                "id": 15,
                "guide": 1,
                "banner_url": "https://guidebook.com/",
                "name": "MySponsor",
                "duration": 5,
                "banner_image": "http://s3.amazonaws.com/media.guidebook.com/upload/5/6FTfnJ2M7YqbA0bX7aDiAIKXTGydE58Rdk66.png",
                "enabled": false,
                "banner_url_text": null,
                "website_only": true,
                "description_html": null
            }
        ]
    }
    
    

    This endpoint can also be used to read data on Sponsors. The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/sponsors/?guide=<guide_id>

    Model Fields

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

    Parameter Type Description
    id integer A unique identifier for your Sponsor.

    Filtering data by Guide id

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

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

    Retrieving a Sponsor

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

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

    Updating a Sponsor

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

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

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

    Deleting a Sponsor

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

    DELETE https://builder.guidebook.com/open-api/v1.1/sponsors/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.1/inboxes/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all inboxes you have access to
    response = requests.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": 1,
          "name": "test box 1"
        },
        {
          "id": 173,
          "guide": 1,
          "name": "test box 2"
        },
        {
          "id": 174,
          "guide": 1,
          "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.

    The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/inboxes/?guide=<guide_id>

    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.1/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.1/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.1/messages/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "inbox": 42,
        "title": "Title of Message",
        "message": "Message created from the Open API"
    }
    
    response = requests.post(messages_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",
      "attachment_object": null,
      "is_push_notification": false,
      "segmented_push_options": null
    }
    
    
    

    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.1/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.
    is_push_notification no boolean Optional boolean to indicate if you want to send the Message as a push notification. If left blank, it will default to false. Limits apply - See https://support.guidebook.com/hc/en-us/articles/205012050-Send-Notifications-to-Your-Users
    attachment_content_type no string String indicating the content type of the attachment object. The options are: "schedule.session", "custom_list.customlistitem". attachment_object_id must be filled out if this field is provided.
    attachment_object_id no integer The id number of the attachment object. Not updatable after creation. attachment_content_type must be filled out if this field is provided.
    segmented_push_options sometimes JSON Required information for if you want to send push notifications to specific users.

    Targeting Specific Users with segmented_push_options

    To target specific users, issue a POST request where the segmented_push_options field is a dictionary like:

    {"segment_type": <segment_type>, "targets": [<target_id_1>, <target_id_2>, <target_id_n>]}

    segment_type can be "session", "email", or "attendees_and_groups". If targeting attendees or groups, you must specify which with a dictionary like:

    {"segment_type": "attendees_and_groups", "targets": {"groups": [<group_id_1>, <group_id_2>, <group_id_n>]}}

    Listing Messages

    
    messages_url =  'https://builder.guidebook.com/open-api/v1.1/messages/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all messages you have access to
    response = requests.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": 1,
          "inbox": 219,
          "title": "Message 1",
          "message": "Hello",
          "scheduled_send_time": "2018-09-13T04:31:41.137633+0000",
          "attachment_object": null,
          "is_push_notification": false,
          "segmented_push_options": null
        },
        {
          "id": 39,
          "guide": 1,
          "inbox": 219,
          "title": "Message 2",
          "message": "Hello Again",
          "scheduled_send_time": "2018-09-13T04:31:41.139402+0000",
          "attachment_object": null,
          "is_push_notification": false,
          "segmented_push_options": null
        },
        {
          "id": 40,
          "guide": 1,
          "inbox": 219,
          "title": "Message 3",
          "message": "Good Bye",
          "scheduled_send_time": "2018-09-13T04:31:41.141097+0000",
          "attachment_object": null,
          "is_push_notification": false,
          "segmented_push_options": null
        }
      ]
    }
    
    

    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.

    The guide filter is required

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/messages/?guide=<guide_id>

    Model Fields

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

    Parameter Type Description
    id integer An unique identifier for your Message.
    attachment_object string A string indicating the content type and id of the object. Ex. schedule.session:321
    segmented_push_options JSON A dictionary listing the targets your message will be sent to.

    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.1/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.1/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.1/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.1/messages/71/

    Forms

    Creating a Form

    import requests
    
    form_url =  'https://builder.guidebook.com/open-api/v1.1/surveys/'
    api_key = 'API_KEY'
    post_data =
    {
      "submission_rule_type": "multiple-submission",
      "description": "Form for gathering feedback about the event.",
      "name": "Event Feedback Form",
      "location_content_type": "schedule.session",
      "question_set": 32,
      "user_login_required": false,
      "is_collecting_responses": true,
      "location_object_id": 8765,
      "label": "Please Fill in this Form"
    }
    
    response = requests.post(form_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
      "id": 1,
      "created_at": "2019-06-24T02:08:42.952413+0000",
      "last_updated": "2019-06-24T02:08:42.952434+0000",
      "label": "Please Fill in this Form",
      "name": "Event Feedback Form",
      "description": "Form for gathering feedback about the event.",
      "notification_emails": [],
      "submission_rule_type": "multiple-submission",
      "user_login_required": false,
      "version_number": 0,
      "question_set": {
        "id": 1,
        "created_at": "2019-06-24T02:08:42.901670+0000",
        "last_updated": "2019-06-24T02:08:42.901691+0000",
        "is_branch": false,
        "guide": 1,
        "name": "Question Set"
      },
      "location_content_type": "schedule.session",
      "location_object_id": 1,
      "is_collecting_responses": true
    }
    
    
    

    Forms are the top level model that allows you to control the UI and submission behavior for QuestionSets and Questions. The organization of the models is as follows. You can create a QuestionSet that is the container for your question objects. You can then create all the questions you want and link these to the QuestionSet container. Finally, you can then link your QuestionSet object to a Form object. This Form object will control additional options on how you want to handle response submissions from your Attendees.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    question_set yes integer The specific QuestionSet your Form is linked to. See section on QuestionSets for more info.
    submission_rule_type yes string Options are 'single-submission', 'revisions-allowed', 'multiple-submission'
    user_login_required no boolean A booelan value that indicates if an user needs to be logged in before they can submit an answer to this Form.
    label no string A call to action field for your Form.
    name yes string The title of your Form.
    description no string The description of your Form.
    is_collecting_responses no boolean A booelan value that indicates if this Form is collecting responses.
    location_content_type yes string Type of Object you want to link this form to. The options are: "schedule.session", "custom_list.customlistitem", and "menuitem.menuitem". If creating a Menu Item Form, you do not need to provide a location_object_id.
    location_object_id yes integer Object ID of the object you want to associate this form with. Not required if creating a Menu Item Form.
    notification_emails no list of emails List of email addresses to notify when an answer is submmitted for this form.

    Listing Forms

    This endpoint will list all Forms that are owned by your Account.

    The question_set__guide filter is required.

    
    form_url =  'https://builder.guidebook.com/open-api/v1.1/surveys/?question_set__guide=1'
    api_key = 'API_KEY'
    
    # This will return all forms you have access to
    response = requests.get(form_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
      "count": 3,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 2,
          "created_at": "2019-06-24T02:09:39.966166+0000",
          "last_updated": "2019-06-24T02:09:39.966182+0000",
          "label": "Fill out this form",
          "name": "Session Form",
          "description": "Please fill out this form for this session.",
          "notification_emails": null,
          "submission_rule_type": "multiple-submission",
          "user_login_required": false,
          "version_number": 0,
          "question_set": {
            "id": 2,
            "created_at": "2019-06-24T02:09:39.964328+0000",
            "last_updated": "2019-06-24T02:09:39.964344+0000",
            "is_branch": false,
            "guide": 1,
            "name": "Question Set"
          },
          "location_content_type": "schedule.session",
          "location_object_id": 2,
          "is_collecting_responses": true
        },
        {
          "id": 3,
          "created_at": "2019-06-24T02:09:39.969125+0000",
          "last_updated": "2019-06-24T02:09:39.969141+0000",
          "label": "Fill out this form",
          "name": "Session Form",
          "description": "Please fill out this form for this session.",
          "notification_emails": null,
          "submission_rule_type": "single-submission",
          "user_login_required": false,
          "version_number": 0,
          "question_set": {
            "id": 3,
            "created_at": "2019-06-24T02:09:39.967454+0000",
            "last_updated": "2019-06-24T02:09:39.967470+0000",
            "is_branch": false,
            "guide": 1,
            "name": "Question Set"
          },
          "location_content_type": "schedule.session",
          "location_object_id": 2,
          "is_collecting_responses": true
        },
        {
          "id": 4,
          "created_at": "2019-06-24T02:09:39.971788+0000",
          "last_updated": "2019-06-24T02:09:39.971804+0000",
          "label": "Fill out this form",
          "name": "Session Form",
          "description": "Please fill out this form for this session.",
          "notification_emails": null,
          "submission_rule_type": "revisions-allowed",
          "user_login_required": false,
          "version_number": 0,
          "question_set": {
            "id": 4,
            "created_at": "2019-06-24T02:09:39.970123+0000",
            "last_updated": "2019-06-24T02:09:39.970140+0000",
            "is_branch": false,
            "guide": 1,
            "name": "Question Set"
          },
          "location_content_type": "schedule.session",
          "location_object_id": 2,
          "is_collecting_responses": true
        }
      ]
    }
    
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/surveys/?question_set__guide=<guide_id>

    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 Form.
    created_at datetime Time when this Form was created - UTC.
    version_number integer Tracks what revision this Form is on.

    Filtering data by Guide id

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

    GET https://builder.guidebook.com/open-api/v1.1/surveys/?question_set__guide=47

    You can also filter by question_set.

    Retrieving a Form

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

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

    Updating a Form

    Updating data on a live Form will create a new form version and remove all responses. Be sure that this is what you want to do before proceeding. To modify an existing Form object, issue a PATCH request like:

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

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

    Deleting a Form

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

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

    QuestionSets

    Creating a QuestionSet

    import requests
    
    question_sets_url =  'https://builder.guidebook.com/open-api/v1.1/question-sets/'
    api_key = 'API_KEY'
    post_data =
    {
      "guide": 1,
      "is_branch": false,
      "name": "Test Question Set"
    }
    
    response = requests.post(question_sets_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
      "id": 2,
      "created_at": "2019-06-24T02:28:28.088618+0000",
      "last_updated": "2019-06-24T02:28:28.088638+0000",
      "is_branch": false,
      "guide": 1,
      "name": "Test Question Set"
    }
    
    
    

    QuestionSets are part of the larger feature of Forms. The organization of the models is as follows. You can create a QuestionSet that is the container for your question objects. You can then create all the questions you want and link these to the QuestionSet container. Finally, you can then link your QuestionSet object to a Form object. This Form object will control additional options on how you want to handle response submissions from your Attendees.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/question-sets/

    Model Fields

    Parameter Required Type Description
    guide yes integer The specific Guide your QUestionSet belongs to. See section on Guides for more info.
    name yes string The title of your QuestionSet.
    is_branch no boolean A booelan value that indicates if this QuestionSet is a branch off an existing Question.

    Listing QuestionSets

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

    The guide filter is required.

    
    question_sets_url =  'https://builder.guidebook.com/open-api/v1.1/question-sets/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all question sets you have access to
    response = requests.get(question_sets_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
      "count": 3,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 2,
          "created_at": "2019-06-24T02:26:54.616653+0000",
          "last_updated": "2019-06-24T02:26:54.616670+0000",
          "is_branch": false,
          "guide": 1,
          "name": "Question Set"
        },
        {
          "id": 3,
          "created_at": "2019-06-24T02:26:54.618841+0000",
          "last_updated": "2019-06-24T02:26:54.618858+0000",
          "is_branch": false,
          "guide": 1,
          "name": "Question Set"
        },
        {
          "id": 4,
          "created_at": "2019-06-24T02:26:54.620240+0000",
          "last_updated": "2019-06-24T02:26:54.620257+0000",
          "is_branch": true,
          "guide": 1,
          "name": "Question Set"
        }
      ]
    }
    
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/question-sets/?guide=<guide_id>

    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 QuestionSet.
    created_at datetime Time when this QuestionSet was created - UTC.

    Filtering By Guide id

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

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

    Retrieving a QuestionSet

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

    GET https://builder.guidebook.com/open-api/v1.1/question-sets/71/

    Updating a QuestionSet

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

    PATCH https://builder.guidebook.com/open-api/v1.1/question-sets/71/

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

    Deleting a QuestionSet

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

    DELETE https://builder.guidebook.com/open-api/v1.1/question-sets/71/

    Questions

    Creating a Question

    import requests
    
    free_response_question_url =  'https://builder.guidebook.com/open-api/v1.1/free-response-questions/'
    api_key = 'API_KEY'
    post_data =
    {
      "question_set": 42,
      "display_type": "short-text",
      "rank": 1,
      "requires_answer": false,
      "text": "What did you think of the event?"
    }
    
    response = requests.post(free_response_question_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
      "id": 1,
      "question_type": "free-response",
      "text": "What did you think of the event?",
      "requires_answer": false,
      "display_type": "short-text",
      "question_set": {
        "id": 1,
        "created_at": "2019-06-24T04:13:51.215868+0000",
        "last_updated": "2019-06-24T04:13:51.215888+0000",
        "is_branch": false,
        "guide": 1,
        "name": "Question Set"
      },
      "rank": 1,
      "uuid": "4e2e2d69-735c-482b-a902-6cf6793aa7fb"
    }
    
    
    
    
    grid_question_url =  'https://builder.guidebook.com/open-api/v1.1/grid-questions/'
    api_key = 'API_KEY'
    post_data =
    {
      "question_set": 1479,
      "rank": 1,
      "text": "Test Grid Question",
      "questions": [
        {
          "text": "question a",
          "rank": 0
        },
        {
          "text": "second question",
          "rank": 1
        },
        {
          "text": "last question",
          "rank": 2
        }
      ],
      "requires_answer": false
    }
    
    response = requests.post(grid_question_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
      "id": 364,
      "question_type": "grid",
      "text": "Test Grid Question",
      "requires_answer": false,
      "questions": [
        {
          "id": 1,
          "text": "question a",
          "rank": 0,
          "uuid": "3d00fe34-478f-49de-a3a3-f77263996ad3"
        },
        {
          "id": 2,
          "text": "second question",
          "rank": 1,
          "uuid": "48a9b985-b1de-4adf-99a6-2f2a2c752eee"
        },
        {
          "id": 3,
          "text": "last question",
          "rank": 2,
          "uuid": "0d508d26-7892-4a7c-9623-e1f5b3beb8cb"
        }
      ],
      "question_set": {
        "id": 2,
        "created_at": "2019-06-24T04:42:53.268110+0000",
        "last_updated": "2019-06-24T04:42:53.268131+0000",
        "is_branch": false,
        "guide": 2,
        "name": "Question Set"
      },
      "rank": 1,
      "choices": [],
      "uuid": "74c17df2-40f6-46e4-aa7d-449729641a52"
    }
    
    
    
    
    mc_question_choice_url =  'https://builder.guidebook.com/open-api/v1.1/multiple-choice-question-choices/'
    api_key = 'API_KEY'
    post_data =
    {
      "rank": 1,
      "text": "second choice",
      "grid_choice_question": 364,
      "multiple_choice_question": null
    }
    
    response = requests.post(mc_question_choice_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    

    The above command returns JSON structured like this:

    {
      "id": 1,
      "text": "second choice",
      "question_branch": null,
      "rank": 1,
      "multiple_choice_question": null,
      "grid_choice_question": 2,
      "question_set": {
        "id": 3,
        "created_at": "2019-06-24T05:00:22.759672+0000",
        "last_updated": "2019-06-24T05:00:22.759687+0000",
        "is_branch": false,
        "guide": 3,
        "name": "Question Set"
      }
    }
    
    
    

    There are four distinct types of Questions you can create via the Open API. The above examples illustrate how you can create Free Response Questions, Multiple Choice Questions, Sliding Scale Questions, and Grid Questions.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/free-response-questions/

    Model Fields

    Parameter Required Type Description
    question_set yes integer The specific QuestionSet your Question belongs to. See section on QuestionSets for more info.
    text yes string The text of your Question.
    requires_answer no boolean A booelan value that indicates if this Question requires an answer from the end-user.
    rank yes float Controls the display order in the QuestionSet. Questions are displayed in ascending order.
    display_type no string Options are 'short-text' display or 'long-text' display. Defaults to 'short-text'.

    POST https://builder.guidebook.com/open-api/v1.1/sliding-scale-questions/

    Model Fields

    Parameter Required Type Description
    question_set yes integer The specific QuestionSet your Question belongs to. See section on QuestionSets for more info.
    text yes string The text of your Question.
    requires_answer no boolean A booelan value that indicates if this Question requires an answer from the end-user.
    rank yes float Controls the display order in the QuestionSet. Questions are displayed in ascending order.
    scale_min_value yes integer The minimum value to display for the sliding scale. Lowest value is 0.
    scale_max_value yes integer The maximum value to display for the sliding scale. Highest value is 10.
    scale_min_label no string An optional label for the minimum value on the scale.
    scale_max_label no string An optional label for the maximum value on the scale.

    POST https://builder.guidebook.com/open-api/v1.1/multiple-choice-questions/

    Model Fields

    Parameter Required Type Description
    question_set yes integer The specific QuestionSet your Question belongs to. See section on QuestionSets for more info.
    text yes string The text of your Question.
    requires_answer no boolean A booelan value that indicates if this Question requires an answer from the end-user.
    rank yes float Controls the display order in the QuestionSet. Questions are displayed in ascending order.
    display_type no integer Options are 1 for list display and 2 for drop down display. Defaults to 1.
    selection_type no integer Options are 1 for single answer and 2 for multiple answer. Defaults to 1.
    num_required_answers yes integer The minimum number of required selections to be considered a valid submission.
    required_exact_number_of_answers no boolean A boolean value that indicates if the exact number of answers defined in num_required_answers need to be submitted.

    POST https://builder.guidebook.com/open-api/v1.1/multiple-choice-question-choices/

    Model Fields

    Parameter Required Type Description
    multiple_choice_question no integer The id of the specific Multiple Choice Question your choice belongs to.
    grid_choice_question no integer The id of the specific Grid Question this choice belongs to. Either this field OR multiple_choice_question needs to be filled in.
    text yes string The text of your choice.
    rank yes float Controls the display order of this choice.
    question_branch no integer The id of the QuestionSet branch that this choice will branch off into if selected.

    POST https://builder.guidebook.com/open-api/v1.1/grid-questions/

    Model Fields

    Parameter Required Type Description
    question_set yes integer The specific QuestionSet your Question belongs to. See section on QuestionSets for more info.
    choices yes list of integers The list of multiple question choices for the grid question.
    questions yes list of dictionaries A list of dictionaries of the questions in this grid question. The dictinoary should simply contain a text (string) key and a rank (float) key.

    Listing Questions

    The following endpoints will list all Questions that are owned by your Account. Typically, these endpoints are called with a question_set__guide filter or question_set filter such that it returns a list of Questions associated to a lone Guide or QuestionSet object that is owned by you. There is a dedicated endpoint for each type of Question.

    The question_set__guide filter is required.

    
    sliding_scale_question_lists_url =  'https://builder.guidebook.com/open-api/v1.1/sliding-scale-questions/?question_set__guide=1'
    api_key = 'API_KEY'
    
    # This will return all sliding scale questions you have access to
    response = requests.get(sliding_scale_question_lists_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
      "count": 3,
      "next": null,
      "previous": null,
      "results": [
        {
          "id": 1,
          "question_type": "sliding-scale",
          "text": "Rate this session on a scale of 1-10, 10 being the best.",
          "requires_answer": false,
          "scale_min_value": 0,
          "scale_max_value": 10,
          "question_set": {
            "id": 2,
            "created_at": "2019-06-24T04:08:41.778921+0000",
            "last_updated": "2019-06-24T04:08:41.778945+0000",
            "is_branch": false,
            "guide": 1,
            "name": "Question Set"
          },
          "rank": 1,
          "scale_min_label": "",
          "scale_max_label": "",
          "uuid": "3827e773-c764-43eb-bd2f-c45a0374a9fe"
        },
        {
          "id": 2,
          "question_type": "sliding-scale",
          "text": "Rate this session on a scale of 1-5, 5 being the best.",
          "requires_answer": false,
          "scale_min_value": 0,
          "scale_max_value": 5,
          "question_set": {
            "id": 2,
            "created_at": "2019-06-24T04:08:41.778921+0000",
            "last_updated": "2019-06-24T04:08:41.778945+0000",
            "is_branch": false,
            "guide": 1,
            "name": "Question Set"
          },
          "rank": 2,
          "scale_min_label": "",
          "scale_max_label": "",
          "uuid": "482c23d4-618d-431e-8913-df17790c09aa"
        },
        {
          "id": 3,
          "question_type": "sliding-scale",
          "text": "Rate this session on a scale of 3-7, 7 being the worst.",
          "requires_answer": false,
          "scale_min_value": 3,
          "scale_max_value": 7,
          "question_set": {
            "id": 2,
            "created_at": "2019-06-24T04:08:41.778921+0000",
            "last_updated": "2019-06-24T04:08:41.778945+0000",
            "is_branch": false,
            "guide": 1,
            "name": "Question Set"
          },
          "rank": 3,
          "scale_min_label": "best",
          "scale_max_label": "worst",
          "uuid": "ae98389a-5e64-4421-b536-bc034309aa96"
        }
      ]
    }
    
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/free-response-questions/?question_set__guide=<guide_id>

    GET https://builder.guidebook.com/open-api/v1.1/sliding-scale-questions/?question_set__guide=<guide_id>

    GET https://builder.guidebook.com/open-api/v1.1/multiple-choice-questions/?question_set__guide=<guide_id>

    GET https://builder.guidebook.com/open-api/v1.1/grid-questions/?question_set__guide=<guide_id>

    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 Question. Note that this is not unique across question types.
    uuid uuid An unique identifier for your Questio. Unique across question types.
    created_at datetime Time when this Question was created - UTC.

    Retrieving a Question

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

    GET https://builder.guidebook.com/open-api/v1.1/multiple-choice-questions/71/

    Updating a Question

    Updating data on a live Form will create a new form version and remove all responses. Be sure that this is what you want to do before proceeding. To modify an existing Question object, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1.1/multiple-choice-questions/71/

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

    Deleting a Question

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

    DELETE https://builder.guidebook.com/open-api/v1.1/multiple-choice-questions/71/

    FormAnswerSets

    Listing FormAnswerSets

    This endpoint will list all FormAnswerSets that are owned by your Account.

    import requests
    
    answer_set_url =  'https://builder.guidebook.com/open-api/v1.1/answer-sets/?survey=23&object_id=42939'
    api_key = 'API_KEY'
    
    # This will return all answers for the given form
    response = requests.get(answer_set_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    {
      "count": 3,
      "next": null,
      "previous": null,
      "results": [
        {
          "object_id": 42939,
          "survey": 23,
          "user": null,
          "content_type": "schedule.session",
          "survey_version_number": 1,
          "id": 152,
          "device_id": "bc07a281f9cc1f3d47fc864e",
          "completed_at":"2019-06-24T05:36:30.846778+0000"
        },
        {
          "object_id": 42939,
          "survey": 23,
          "user": null,
          "content_type": "schedule.session",
          "survey_version_number": 1,
          "id": 153,
          "device_id": "cb7f8e68cc11ddf42a6",
          "completed_at":"2019-06-24T05:36:30.846778+0000"
        },
        {
          "object_id": 42939,
          "survey": 23,
          "user": 1,
          "content_type": "schedule.session",
          "survey_version_number": 1,
          "id": 101,
          "device_id": "i13cb7f313d2d229f",
          "completed_at":"2019-06-24T05:36:30.846778+0000"
        }
      ]
    }
    
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/answer-sets/

    Model Fields

    Parameter Type Description
    id integer An unique identifier for your FormAnswerSets.
    survey integer The Form that this FormAnswerSets is for.
    content_type string The content type of the object this FormAnswerSets is for.
    object_id integer The object ID that this FormAnswerSets is for.
    device_id string Unique identifier for the device that submitted this FormAnswerSets.
    survey_version_number integer Tracks what revision this form is on.
    completed_at datetime The date and time that this FormAnswerSet was submitted.
    user integer The ID of the user that submitted this FormAnswerSet. This will be null if the user was not logged in.

    Retrieving a specific AnswerSet

    If you would like to see the details of a specific FormAnswerSets submitted, you can use the following detail URL to examine the detailed response data. The example below is fetching FormAnswerSets 71. To retrieve an individual FormAnswerSets object issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1.1/answer-sets/71/answers/

    
    answer_set_detail_url =  'https://builder.guidebook.com/open-api/v1.1/answer-sets/71/answers/'
    api_key = 'API_KEY'
    
    # This will return all answers for the given form
    response = requests.get(answer_set_detail_url, headers={'Authorization': 'JWT ' + api_key})
    

    The above command returns JSON structured like this:

    [
      {
        "id": 13,
        "question_uuid": "4e481586-85bc-4cc1-a33b-0c78b29a2366",
        "question_type": "sliding-scale",
        "question_text": "test 1",
        "answer": "3",
        "multi_choice_answers": []
      },
      {
        "id": 14,
        "question_uuid": "77cdabbc-d9d1-440c-9602-9574a062e7b4",
        "question_type": "free-response",
        "question_text": "test 1",
        "answer": "test answer",
        "multi_choice_answers": []
      },
      {
        "id": 15,
        "question_uuid": "315e41ca-ced4-4fce-8c35-1b98d680e472",
        "question_type": "multiple-choice",
        "question_text": "test 1",
        "answer": "",
        "multi_choice_answers": [
          "french fries",
          "soda",
          "hamburger"
        ]
      }
    ]
    
    

    Model Fields

    Parameter Type Description
    id integer An unique identifier for your Answer.
    question_uuid string The uuid of the Question this Answer is linked to.
    question_type string The type of the Question this Answer is linked to.
    question_text string The text of the Question this Answer is linked to.
    answer string The answer text that was submitted.
    multi_choice_answers list of strings Since multiple choice questions can have multiple answers. They will appear as a list of strings here.

    Attendees

    Creating an Attendee

    import requests
    
    attendees_list_url =  'https://builder.guidebook.com/open-api/v1.1/attendees/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "email": "open_api@example.com",
        "first_name": "Open API",
        "last_name": "Example User"
    }
    
    response = requests.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,
        "email_opt_out": false,
        "status": 0,
        "last_email_send": null,
        "qr_badge": "f=Open+API&l=Example+User&i=1&ii=&s=e9dfa0c529c4a6f4880f4d324a12723d5475b3d9"
    }
    
    
    

    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.

    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.1/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.
    avatar no image Avatar image for this Attendee. For newly invited Attendees, you can update this field. If the Attendee has logged in and claimed their account, then this field is read-only. See section on images to update.
    cover no image Cover (background) image for the Attendee. For newly invited Attendees, you can update this field. If the Attendee has logged in and claimed their account, then this field is read-only. See section on images to update.
    app_profile no dictionary of strings Contains profile information filled out by the Attendee. Possible keys include company, position, contact_email, phone_number, and website. Note that these keys can change at anytime! For newly created Attendees over the API, you can submit data for this field. If there is existing app_profile data for an Attendee, then this field is read-only.
    revoked no 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. Defaults to False.
    email_opt_out boolean Indicates if this Attendee is opted out of emails for this Guide. Defaults to False.

    Listing Attendees

    import requests
    
    attendees_url =  'https://builder.guidebook.com/open-api/v1.1/attendees/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all attendees you have access to
    response = requests.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": 1,
                "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,
                "email_opt_out": false,
                "status": 1,
                "last_email_send": null,
                "qr_badge": "f=&l=&i=2&ii=&s=e9dfa0c529c4a6f4880f4d324a12723d5475b3d9"
            },
            {
                "id": 3,
                "guide_id": 1,
                "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,
                "email_opt_out": false,
                "status": 1,
                "last_email_send": null,
                "qr_badge": "f=&l=&i=3&ii=&s=bw7lsa87leh9wql8nuiwutykgi5d5gig1o0czl08"
            },
            {
                "id": 4,
                "guide_id": 1,
                "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,
                "email_opt_out": false,
                "status": 1,
                "last_email_send": null,
                "qr_badge": "f=&l=&i=4&ii=&s=7vexvjq13lthpz1690u69ksawt3v65ff73b9hxao"
            },
            {
                "id": 5,
                "guide_id": 1,
                "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,
                "email_opt_out": false,
                "status": 1,
                "last_email_send": null,
                "qr_badge": "f=&l=&i=5&ii=&s=bla4e60zq1d19pzg85x1j9jh9fskukmqpw2p4dl7"
            }
        ]
    }
    
    

    This endpoint can also be used to read data on Attendees. 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.

    The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/attendees/?guide=<guide_id>

    Model Fields

    The fields returned in the GET responses are the 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 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.
    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.
    qr_badge string String that is used to create an attendee's QR code.

    Sending Invite Emails to Attendees

    
    attendees_email_url =  'https://builder.guidebook.com/open-api/v1.1/guides/47/send-attendee-invite-email/'
    api_key = 'API_KEY'
    
    post_data =
    {
        "attendees": [1,2,3,4,5]
    }
    
    response = requests.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.1/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.1/attendees/?guide=47

    You are also able to filter by the fields revoked, status, import_id, and account__email 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.1/attendees/?guide=47&status=3

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

    GET https://builder.guidebook.com/open-api/v1.1/attendees/?guide=47&account__email=test@example.com

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

    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.1/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.1/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.1/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 three fields we allow you to update - revoked, email_opt_out, 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.

    Publishing a PersonalizedSchedule for an Attendee

    To publish a PersonalizedSchedule for a specific Attendee object, issue a POST request like:

    POST https://builder.guidebook.com/open-api/v1.1/attendees/21/publish-personalized-schedules/

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

    To successfully publish a personalized schedule for an attendee, the attendee's guide must be on a Premium service level and must already be published.

    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.1/attendee-groups/'
    api_key = 'API_KEY'
    post_data =
    {
        "guide": 1,
        "name": "Test AttendeeGroup created via the Open API"
    }
    
    response = requests.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.1/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

    
    attendee_groups_list_url =  'https://builder.guidebook.com/open-api/v1.1/attendee-groups/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all AttendeeGroups you have access to
    response = requests.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.

    The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/attendee-groups/?guide=<guide_id>

    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.1/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.1/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.1/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.1/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.1/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.1/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.1/attendee-groups/71/

    Guidebook ID

    Guidebook ID is a QR code that identifies attendees. It is scannable and holds some attendee information.

    The QR code contains a url encoded query string. You will have to decode the query string in order to get the original values.

    Guidebook ID query string properties

    Property Type Description
    f string First name of the attendee. Optional: This can be omitted from the query string
    l string Last name of the attendee Optional: This can be omitted from the query string
    i integer The attendee ID
    ii string. Import id: If the user is imported from an external source, the importer can specify a customized id to append to each user.

    Verifying Guidebook ID is issued by Guidebook

    This endpoint will verify the QR code query string content is issued by Guidebook.

    The verification of the QR code can be checked by the response's status code and message.

    You can get the following response code & related message: HTTP 200 - This is a valid Guidebook ID QR code HTTP 400 - This is an invalid Guidebook ID QR code HTTP 400 - qr_badge is not in the request data.

    import requests
    
    verify_guidebook_id_badge_url = 'https://builder.guidebook.com/open-api/v1.1/verify-qr-badge/'
    api_key = 'API_KEY'
    post_data = {
        'qr_badge': 'QR_BADGE_QUERY_STRING'
    }
    
    response = requests.post(verify_guidebook_id_badge_url, data=post_data, headers={'Authorization': 'JWT ' + api_key})
    
    is_valid_guidebook_id = response.status_code == 200
    

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/verify-qr-badge/

    Fields

    Parameter Required Type Description
    qr_badge yes string The query string contained in the Guidebook ID QR code

    PersonalizedSchedules

    Creating a PersonalizedSchedule

    import requests
    
    personalized_schedule_url =  'https://builder.guidebook.com/open-api/v1.1/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 = requests.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.

    HTTP Request

    POST https://builder.guidebook.com/open-api/v1.1/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

    
    personalized_schedule_url =  'https://builder.guidebook.com/open-api/v1.1/personalized-schedules/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all `PersonalizedSchedule` you have access to
    response = requests.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": 1,
                "name": "Example Schedule for Sales Team",
                "attendees": [
                    6,
                    7,
                    8
                ],
                "sessions": [
                    1,
                    2,
                    3
                ]
            },
            {
                "id": 2,
                "guide": 1,
                "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. The guide filter is required.

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/personalized-schedules/?guide=<guide_id>

    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.1/personalized-schedules/?guide=47

    Filtering by Attendee id

    Including a query parameter attendees__id allows you to filter for all PersonalizedSchedule related to an Attendee (Attendee 12 in the following example):

    GET https://builder.guidebook.com/open-api/v1.1/personalized-schedules/?attendees__id=12

    NOTE: filtering for all PersonalizedSchedule related to an Attendee created via the CVS/Excel import functionality is not currently supported.

    Filtering by Attendee import_id

    Including a query parameter attendees__import_id allows you to filter for all PersonalizedSchedule related to an Attendee import_id (import_id 142 in the following example):

    GET https://builder.guidebook.com/open-api/v1.1/personalized-schedules/?attendees__import_id=142

    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.1/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.1/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.1/personalized-schedules/71/

    Publishing PersonalizedSchedules

    PersonalizedSchedules can be published for an entire guide, or for a specific attendee. To publish all schedules for a guide, see Publishing Personalized Schedules for a Guide. To publish a schedule for a specific attendee, see Publishing Personalized Schedules for Attendees.

    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.

    Make sure that if you are using both the open api and webhooks that you take note of open_api_version in order to differentiate events caused by open api actions vs. other sources.

    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.
    open_api_version String of the open api version used that caused the event. Can be null.

    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-UserUnregisteredScheduleSession

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

    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-UserReportedPhoto

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

    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-UserCheckedIn

    Standard fields. No additional fields.

    Builder-GuidePublished

    Standard fields. No additional fields.

    Builder-GuideCloned

    Standard fields. No additional fields.

    MobileApp-AnswerSetSubmitted

    Key Description
    answer_set_id The id of the AnswerSet that was just submitted. See section on AnswerSets for more info.
    device_id The unique identifier for the device that submitted this AnswerSet.
    content_type If this AnswerSet is related to an object, this is the type of that object.
    object_id If this AnswerSet is related to an object, this is the id of that object.
    survey_id The ID of the Form object that this AnswerSet relates to.
    survey_version_number The version of the Form that was answered.

    Builder-SessionCreated

    Key Description
    session_id The id of the session.
    session_name The name of the session.

    Builder-SessionUpdated

    Key Description
    session_id The id of the session.
    session_name The name of the session.

    Builder-SessionDeleted

    Key Description
    session_id The id of the session.
    session_name The name of the session.

    Builder-AllSessionsInGuideDeleted

    Standard fields, No additional fields.

    Builder-ScheduleCSVImport

    Standard fields, No additional fields.

    Builder-AttendeeVerificationCreated

    Key Description
    session_id The id of the session.
    session_name The name of the session.
    attendee_id The id of the attendee.
    attendance_manager_id The account id of the attendance manager.

    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.

    Guidebook Web

    Guidebook Web is the website representation of your guide, and its settings can be controlled by the Guidebook Web Metadata resource.

    Listing Guidebook Web Metadata objects

    This endpoint will list all Guidebook Web Metadata objects that are owned by your Account. Typically, this endpoint is called with a guide filter such that it returns the Guidebook Web Metadata object associated to a lone Guide object that is owned by you.

    The guide filter is required.

    import requests
    
    guidebook_web_metadata_url = 'https://builder.guidebook.com/open-api/v1.1/guidebook-web-metadata/?guide=1'
    api_key = 'API_KEY'
    
    # This will return all Guidebook Web metadata objects you have access to
    response = requests.get(guidebook_web_metadata_url, headers={'Authorization': 'JWT' + api_key})
    

    The above command returns JSON structured like this:

    {
        "count": 4,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": 1,
                "created_at": "2017-09-27T07:31:48.637192+0000",
                "guide": 1,
                "space": null,
                "enabled": true
            }
        ]
    }
    
    

    HTTP Request

    GET https://builder.guidebook.com/open-api/v1.1/guidebook-web-metadata/?guide=<guide_id>

    Model Fields

    Parameter Type Description
    id integer An unique identifier for your Guidebook Web Metadata object.
    created_at datetime Time when this Guidebook Web Metadata object was created - UTC.
    guide integer The specific Guide your Guidebook Web Metadata object belongs to.
    space integer The specific Space your Guidebook Web Metadata object belongs to.
    enabled boolean Whether the specific Guides Guidebook Web page is accessible.

    Filtering by Guide id

    Including a query parameter guide allows you to filter for the Guidebook Web Metadata object related to a Guide you have access to (Guide 47 in the following example)

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

    Retrieving a Guidebook Web Metadata object

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

    GET https://builder.guidebook.com/open-api/v1.1/guidebook-web-metadata/71/

    Updating a Guidebook Web Metadata object

    To modify an existing Guidebook Web Metadata object, issue a PATCH request like:

    PATCH https://builder.guidebook.com/open-api/v1.1/guidebook-web-metadata/71/

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

    Parameter Type Description
    enabled boolean Whether the specific Guides Guidebook Web page is accessible.

    BuilderIcons

    A BuilderIcon is an object that allows you to create custom MenuItem icons from PNG images which can be shared across all your Guides and/or Organizations.

    Creating a BuilderIcon

    import requests
    
    builder_icon_url = 'https://builder.guidebook.com/open-api/v1.1/builder-icons/'
    api_key = 'API_KEY'
    post_data = 
    {
      "file": "icon_image",
      "tags": "['tag one', 'tag two]",
      "org": 123
    }
    
    response = requests.post(builder_icon_url, data=post_data, headers={'Authorization': 'JWT ' + api_key}).json()
    
    

    The above commands return JSON structured like this:

    {
      "id": 293,
      "file": "https://mediacdn.guidebook.com/upload/builderfile/c1c88374-2133-12ee-a0z1-3d957ascee78/rEiJ5EG43j0ViHVuWsXSuckPD0tlYAeYAugL.png",
      "tags": ["tag one", "tag two"],
      "creator": 1784,
      "access_control": [
        {
          "object_id": 1784,
          "entity": "user"
        },
        {
          "object_id": 2343,
          "entity": "org"
        }
      ]
    }
    
    
    

    This endpoint will create a BuilderIcon for the PNG image file that you specify.

    HTTP Request

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

    Model Fields

    Parameter Required Type Description
    file yes file Your icon image file. It must be PNG and be of size 180x180px, 180x150px, 150x150px, 120x100px, or 100x100px.
    tags no array or stringified array A list of strings used to identify & search icons.
    org no id of the Organization you wish to share the BuilderIcon with.

    Listing BuilderIcons

    
    menu_item_url = 'https://builder.guidebook.com/open-api/v1.1/builder-icons/'
    api_key = 'API_KEY'
    
    # This will return all `BuilderIcons` you have access to
    response = requests.get(menu_item_url, headers={'Authorization': 'JWT ' + api_key}).json()
    
    

    The above command returns JSON structured like this:

    {
      "count": 2,
      "next": null,
      "previous": null,
      "results": [
          {
              "id": 369,
              "file": "https://mediacdn.guidebook.com/upload/builderfile/315bac20-2a69-11ee-afe4-dbf38e2997f2/Sbpnmc2CD9B9Fe9nuOL4hZzfd0i9WOUtJ8co.png",
              "tags": [
                  "tag one",
                  "tag two"
              ],
              "creator": 1,
              "access_control": [
                  {
                      "object_id": 1,
                      "entity": "user"
                  }
              ]
          },
          {
              "id": 368,
              "file": "https://mediacdn.guidebook.com/upload/builderfile/10a0dc94-2a69-11ee-afe4-dbf38e2997f2/1TY9VtysL5gmFPKai8pFyFeXf9wPn5ONNWNV.png",
              "tags": [],
              "creator": 1,
              "access_control": [
                  {
                      "object_id": 3,
                      "entity": "org"
                  }
              ]
          }
      ]
    }
    
    

    HTTP Request

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

    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 BuilderIcon.
    created_at datetime Time when this BuilderIcon was created - UTC.
    creator integer id of the Account that created the BuilderIcon.
    access_control array Array of access records specifying who has permissions to interact with the BuilderIcon.

    Filtering Data by Guide id and other fields

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

    GET https://builder.guidebook.com/open-api/v1.1/builder-icons/?guide=13

    By default, all BuilderIcons you have permissions to will be returned.

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

    GET https://builder.guidebook.com/open-api/v1.1/builder-icons/?org=2

    GET https://builder.guidebook.com/open-api/v1.1/builder-icons/?guide=13&org=2

    GET https://builder.guidebook.com/open-api/v1.1/builder-icons/?tags=cat,dog

    GET https://builder.guidebook.com/open-api/v1.1/builder-icons/?guide=13&tags=cat,dog

    Retrieving a BuilderIcon

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

    GET https://builder.guidebook.com/open-api/v1.1/builder-icons/42/

    Retrieving available BuilderIcon tags

    To view tags for available BuilderIcons issue a GET request like:

    GET https://builder.guidebook.com/open-api/v1.1/builder-icons/tags/

    By default, a list of tags for all BuilderIcons you have permissions to will be returned.

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

    GET https://builder.guidebook.com/open-api/v1.1/builder-icons/tags/?guide=23

    GET https://builder.guidebook.com/open-api/v1.1/builder-icons/tags/org=4

    GET https://builder.guidebook.com/open-api/v1.1/builder-icons/tags/?guide=23&org=4

    Updating a BuilderIcon

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

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

    You will only need to include the specific fields you are updating and not a full request body. Only file and tags are updatable after creation.

    Deleting a BuilderIcon

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

    DELETE https://builder.guidebook.com/open-api/v1.1/builder-icons/82/