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_key
with your personal API key.Note that the sample python code sample in this documentation uses the python
requests
package. Installation instructions forrequests
can 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_id
field 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/