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:
- Adding additional Open API resources
- Adding optional request parameters to existing routes
- Adding new properties to existing responses
- Changing the order of properties in existing API responses
- Changing the length or format of object IDs or other opaque strings.
Previous API versions documentation
To see previous API documentation, see the following links:
v1 https://developer.guidebook.com/v1/
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_keywith your personal API key.Note that the sample python code sample in this documentation uses the python
requestspackage. Installation instructions forrequestscan be found here; alternatively, for the more eager, you can runpip 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 |
span |
style |
| 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 |
Allowed Styles
Currently, we only allow style attributes for span tags. The supported styles are: color.
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.
Retrieving Leaderboard rankings for a Guide
To retrieve Leaderboard rankings for a Guide, issue a GET request like:
GET https://builder.guidebook.com/open-api/v1.1/guides/21/get-leaderboard-rankings/
A successful request to this endpoint will return a status code of 200 OK
This endpoint is paginated with a maximum page_size of 500. See the section on Pagination. It defaults to returning user scores, but if you would like to retrieve scores by group, you can provide a query param in your request like:
GET https://builder.guidebook.com/open-api/v1.1/guides/21/get-leaderboard-rankings/?scoring_entity=groups
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,
"registration_end_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,
"registration_end_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. |
| registration_end_date | no | datetime | The date when users can no longer register 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,
"registration_end_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,
"registration_end_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,
"registration_end_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,
"registration_end_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=<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 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.
Creating a Link
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. |
Listing Links
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
Retrieving a Link
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/
Updating a Link
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.
Deleting a Link
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. |
| 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. If the Attendee has logged in and claimed their account, then this field is read-only. |
| last_name | no | string | Last name of the Attendee. Only used if no existing Guidebook Account was found via email matching. If the Attendee has logged in and claimed their account, then this field is read-only. |
| 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. However, we do allow you to manipulate the profile information of individual accounts if they have not yet been claimed by the attendees.
There are three fields we allow you to update for all attendees - revoked, email_opt_out, 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.
There are five fields we allow you to update only for attendees that have not yet logged in and claimed their accounts - first_name, last_name, avatar, cover, and app_profile. See "Creating an Attendee" for more details.
Deleting an Attendee
Attendees can only be deleted if they are in a Created or Invited state, which means the attendee has not yet logged in and claimted their account. To delete an eligible user, issue a DELETE request to the url that points to the specific Attendee you'd like deleted:
DELETE https://builder.guidebook.com/open-api/v1.1/attendees/82/
If you just 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. |
| 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/