Studio Session Guide

The Bluebeam Developer Portal is only available to active customers in the US region.

Think of a Studio Session like a digital conference room where PDF drawings can be marked up either simultaneously or asynchronously. This guide covers the general life cycle of a Studio Session and includes code examples. To learn more about Studio and Studio Sessions in general, visit our Studio FAQ page.

You can follow along with this guide and try many of the call outs in the Studio section of our API docs. See our Getting started in the Bluebeam Developer Portal guide for instructions on how to get a valid access token.

Studio Sessions lifecycle

The lifecycle of a Studio Session can be split up into 4 parts:

Initialization – Opens up the "digital conference room"
Add PDFs to the Session for viewing and mark up
Add users to the Session so they can view and mark up
Finalization – Closes the Session and returns the marked up PDFs to their originating system

1. Initialize Session

The first phase of a Studio Session's lifecycle is its creation. To begin, make a POST command to the Sessions endpoint with the following parameters.

Endpoint

Copy

1
https://api.bluebeam.com/publicapi/v1/sessions

Be sure to include client_id in the header of your request.

Request parameters

Name	Description	Value Type / Possible Values
`Name`	Session Name	String
`Notification`	`true`: Current user will be subscribed to email notifications about changes to this Session. `false`: Current user will not be subscribed to email notifications about changes to this Session.	Boolean
`Restricted`	`true`: Restricts the Session to only email addresses that have been invited or added. `false`: Leaves the Session open to anyone who has the 9-digit Session ID.	Boolean
`SessionEndDate`	Once this date is reached, all participants except for the Host will be removed from the Session.	Must be formatted in UTC format.
`DefaultPermissions`	This permission set will apply to all users added to this Session except for the Host (the current user). The Host gets full control.	Define types of permissions and permissions themselves below.

Permission	Description	Value Type / Possible Values
`Type`	Type of permission	`SaveCopy` – Allow attendees to Save As. `PrintCopy` – Allow attendees to print PDFs included in the Session. `Markup` – Allow attendees to place markups. `AddDocuments` – Allow attendees to add new documents to the Session. `FullControl` – Give attendees admin rights to the Session. `MarkupAlert` – Allow attendees to send and receive markup alerts during the Session.
`Allow`	Permission state	Allow, Deny, Default

Permission

Description

Value Type / Possible Values

Type

Type of permission

SaveCopy – Allow attendees to Save As.

PrintCopy – Allow attendees to print PDFs included in the Session.

Markup – Allow attendees to place markups.

AddDocuments – Allow attendees to add new documents to the Session.

FullControl – Give attendees admin rights to the Session.

MarkupAlert – Allow attendees to send and receive markup alerts during the Session.

Allow

Permission state

Allow, Deny, Default

Session End Date
Session End Dates are not required, but if a Session End Date is selected, participants of the Session will be notified via email at 7 days, 2 days, and 24 hours prior to the expiration date.

cURL example

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
cURL [https://api.bluebeam.com/publicapi/v1/sessions](https://api.bluebeam.com/publicapi/v1/sessions) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client_id]" \
-d '{

    "Name":"Pied Piper Acquisition Review",

    "Notification": true,

    "Restricted": true,

    "SessionEndDate": "2016-08-17T21:09:07.5174221Z",

    "DefaultPermissions":[  
      {  
        "Type":"SaveCopy",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"PrintCopy",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"Markup",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"MarkupAlert",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"AddDocuments",  
        "Allow":"Deny"  
      }  
    ]
}' \
-X POST

Permissions
Current Studio users are often accustomed to specific Permissions defaults. It's always a good idea to either check what the default permissions should be or allow users to choose their permissions. When using the Bluebeam API to set permissions, 'Deny' is the default value.

Response Body

Copy

1
2
3
4
{
    "$id": "1",
    "Id": "123-456-789"
}

2. Add PDFs

The next step is to add the PDF files. Adding files is a 3-step process:

Create the Metadata Block for the file via the Bluebeam API
Upload the file directly to AWS
Confirm upload via the Bluebeam API

Note: Studio Sessions do not support PDF/A files.
Because PDF/A is an archival format, it does not allow editing and will cause step 4, below, to fail.

a. Create Metadata Block

Endpoint

Copy

1
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files

Parameters

Name	Description	Value Type / Possible Values
`Name`	Name of file	String ending in ".pdf"
`Source`	Source path; this may help you identify where the file came from later on in the process	String
`Size`	File size; leave null for server to calculate	Integer
`CRC`	Leave null for server to calculate	String

cURL example

Copy

1
2
3
4
5
6
7
8
9
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client_id]" \
-d '{  
      "Name":"Pied_Piper_Acquisition.pdf",  
      "Source":"[https://portfolio.raviga.com/primarybets/piedpiper/legaldocs/Pied_Piper_Acquisition.pdf](https://portfolio.raviga.com/primarybets/piedpiper/legaldocs/Pied_Piper_Acquisition.pdf)"
    }' \
-X POST

Example Response

Copy

1
2
3
4
5
{
  "Id": 1234567
  "UploadUrl":"{upload file to this URL}"
  "UploadContentType":"Application/PDF"
}

Upload window
Upload URL is valid for 10 minutes to start upload.

c. Confirm upload

Endpoint

Copy

1
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/confirm-upload

cURL example

Copy

1
2
3
4
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/confirm-upload](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/confirm-upload) \
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \
-X POST

Response

If successful, you will get a 204 response. For errors, see the Common HTML response codes at the bottom of our Authentication Guide .

3. Add users

Now that you have a Session with PDFs in it, it's time to add users to the Session. The initiator of the Session (the current user) automatically becomes the Host of the Session and is automatically added to the Session's users. More users can always be added while the Session is active. There are 2 methods for adding users:

Method A: Invite user

This method is best to invite users who may not yet have a Studio account. An email is sent to the invitee with an opportunity to create a free Studio account.

Endpoint

Copy

1
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/invite

Parameters

Name	Description
`Email`	Email address to send the invitation to
`Message`	Custom message that displays in the email

Example

Copy

1
2
3
4
5
6
7
8
9
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/invite](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/invite) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-d '{  
      "[Email":"gavin.belson@hooli.com](mailto:Email%22:%22gavin.belson@hooli.com)",  
      "Message":"Please join this Session to review documents regarding the Pied Piper acquisition."
    }' \
-X POST

Response

If successful, you will get a 204 response. For errors, see the Common HTML response codes at the bottom of our Authentication Guide .

Method B: Add user

This method is best if you know that the email address is already associated with a Studio account and you want them to be added to a Studio Session without opting in. If the user does not have an account or if they are unsure if they do, use Method A: Invite user. Using Method B: Add user, the user is added to the Studio Session's attendees, and the Studio Session appears under their Attended Sessions within the Studio tab of the Revu interface.

Endpoint

Copy

1
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/users

Parameters

Name	Description
`Email`	Email address of the known Studio account
`SendEmail`	Boolean; True: send an email to the invitee, False: do not send an email notification to the invitee
`Message`	Custom message that displays in the email

Example

Copy

1
2
3
4
5
6
7
8
9
10
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/users](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/users)
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-d '{  
      "Email": "[peter.gregory@raviga.com](mailto:peter.gregory@raviga.com)",  
      "SendEmail": true,  
      "Message": "As requested, here is the Session to review the Pied Piper acquisition documents."
    }' \
-X POST

Response

If successful, you will get a 204 response. For errors, see the Common HTML response codes at the bottom of our Authentication Guide .

Sample Session invite email

4. Finalize Session

To end a Session (typically done after the attendees have finished marking up or the Session expiration date has been reached), its Status must be changed, its files must be dealt with, and the Session itself must be properly disposed of.

a. Set status to Finalizing

Setting a Session's Status to Finalizing removes all users from the Session, except the Host. This is done to prevent further changes to the Session files after they are downloaded.

Endpoint

Copy

1
https://api.bluebeam.com/publicapi/v1/sessions/{id}

Example

Copy

1
2
3
4
5
6
cURL https://api.bluebeam.com/publicapi/v1/sessions/123-456-789 \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-d '{"Status": "Finalizing"}' \
-X PUT

b. Download the marked up Session files

Downloading the marked up Session files is a 2-part process. Follow the steps below for each file in the Session.

i. Create a Snapshot

While in a Session, PDFs and markups are stored separately. A Snapshot combines the PDF content with the markup layer into a single PDF so that the markups are viewable on the PDF outside of the Studio Session.

Endpoint

Copy

1
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/snapshot

Example

Copy

1
2
3
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/snapshot](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/snapshot) \
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \

ii. Check status of Snapshot, download if complete

Make a GET request to the Snapshot endpoint until the Status is either Complete or Error.

If Error: We will include an error message that can be presented to the user.
If Complete: Use the DownloadUrl to download the Snapshot

Endpoint

Copy

1
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/snapshot

Example

Copy

1
2
3
4
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/)
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \
-X GET

Response Body

Copy

1
2
3
4
5
6
{
    "Status": "Complete",
    "StatusTime": "{The last time the Status was changed}",
    "LastSnapshotTime": "{Time of last successful Snapshot}",
    "DownloadUrl": "{A download URL for the last successful Snapshot}"
}

Status options

Status	Description
`NoSnapshot`	When a Snapshot has never been called on a file
`Requested`	The Snapshot job has not yet started, but we received the request
`InProgress`	The Snapshot job is in progress
`Complete`	The Snapshot job is finished and can be downloaded via `DownloadUrl`
`Error`	The Snapshot job failed. The status will include an error message.

c. Close out the Session

Now that you have the marked up PDF(s), you can dispose of the Session by sending a DELETE request to the Session ID endpoint.

Endpoint

Copy

1
https://api.bluebeam.com/publicapi/v1/sessions/{id}

Example for closing out a Session

Copy

1
2
3
4
5
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-X DELETE

Conclusion

Returning the file to its originating location and archiving the Session completes the typical Studio Session lifecycle. Though there are many different ways to work with Studio Sessions, we hope this walk-through has given you a good grasp of the basics.

Studio Session Guide

Studio Sessions lifecycle

Conclusion

See also: