MyWhistleBox provides developers a path to integrate their applications to the MyWhistleBox service through an Application Programming Interface (API). This is a great way to extend the MyWhistleBox service using an existing workflow.
Here are a just a few examples of things you can do with the REST API:
The MyWhistleBox API is implemented using a REST model and requires an Enterprise plan. The REST model uses standard HTTP requests to communicate with the
MyWhistleBox API service. Developers can use any programming language that support standard HTTP request calls.
A public PHP wrapper is available on github located at
.
Although the wrapper makes things a bit easier to implement using PHP, any HTTP library like cURL can be used to make requests and handle return values.
To access a REST endpoint via the service, construct a URL using the base endpoint along with an action suffix described below.
The base endpoint for the REST service is
MyWhistleBox uses a simple API Key for authentication. All requests must contain a valid API key. You simply make an HTTP Request
by including the following header:
The "apikey" can be generated and copied from your MyWhistleBox Account Settings API Tab (see Configuration Guide).
The endpoints (actions) below are described using the following form:
For example, a generic request would look like:
https://mywhistlebox.com/api/rest/v1.0/{action}/<params>
To list the boxes in your account (no params required):
Send a http request with the GET method type along with the Authorization header and url:
https://mywhistlebox.com/api/rest/v1.0/list/boxes
The action's response (if any) will be decribed in the Response portion.
To make integrating easier, we offer a php api sdk library. Instructions are included with the sdk. You can also use any request
mechanism your language offers including cURL. If you want to use cURL, check out the cURL example document on the developer home page.
To get familiar with using the endpoints, we provide a test endpoint called /test/ping. You can use this endpoint to
determine if your authentication process is working and your request is reaching the REST server.
If the response is “ok”, your request has reached the service and your APIKey has been authorized.
Some endpoints require Date or Date/Time inputs. These values should be formatted following the ISO 8601 format. An example of a date parameter is:
In addition to the Responses noted for each endpoint, all endpoints can receive an error Response in the following form:
If you receive an Access Denied error, this typically mean the APIKey can't be validated (due to typos or revocation),
or the account lacks API access. If you are sure your request is formatted properly, check to make sure you copied and pasted the API key correctly.
Keys shouldn't contain any spaces.
Actions are grouped into categories. To query certain resources, it may be necessary to query more than one endpoint.
For example, /file/info requires a "file_id". You could first use the /list/files endpoint to obtain the desired file_id and then use that id with the
/file/info endpoint.
A list of endpoints by
Use these category tabs to obtain more details of each endpoint.
GET /list/boxes
Description: List all boxes for this account.
Request {
}
Response {
status: "ok",
boxes: [{
id: box id,
name: box name
}],
defaultBoxId: default box id
}
GET /list/pages
Description: List all WhistlePages for this account.
Request {
}
Response {
status: "ok",
pages: [{
id: whistlepage id,
name: whistlepage name
}]
}
GET /list/folders/<parent_id>
Description: List all first level child folders in specified box or folder.
Request {
<parent_id>: id of the parent folder [required]
}
Response {
status: "ok",
folders: [{
id: folder id,
name: folder name
}]
}
GET /list/files/<folder_id>
Description: List all files in specified box or folder.
Request {
<folder_id>: id of the folder files reside in [required]
}
Response {
status: "ok",
files: [{
id: file id,
name: file name
}]
}
GET /list/memos/<folder_id>
Description: List all memos (personal notes) in specified memo folder.
Request {
<folder_id>: id of the memo folder [required]
}
Response {
status: "ok",
memos: [{
id: memo id,
title: memo title
}]
}
POST /user/file/upload
Description: Upload a file to a users box.
Request {
address: WhistleBox address string of user, [required]
file: file path to the local file to be uploaded, [required]
confirmEmail: email for confirmation,
subject: subject of the file,
note: note attached to the uploaded file,
}
Response {
status: "ok",
id: id of the new uploaded file
}
POST /user/memo/upload
Description: upload a personal note to a users box
Request {
address: WhistleBox address string of user, [required]
title: title of the memo, [required]
text: memo text [required]
}
Response {
status: "ok",
id: id of the new memo
}
POST /user/file/send/<file_id>
Description: send an account file to a users box
Request {
<file_id>: optional id of the file to be sent,
file_ids: comma separated list of file_ids, [required?]
address: WhistleBox address of user, [required]
confirmEmail: email for confirmation,
note: note attached to the uploaded file
}
Response {
status: "ok",
fileCount: number of files sent,
to: recipient address,
sentStatus: [{
id: file id,
file: file name,
result: result of send
}]
}
Note: If <file_id> is omitted, file_ids are required
POST /folder/upload/<folder_id>
Description: direct upload a file to our folder
Request {
<folder_id>: our target folder id [required]
file: file path to the local file to be uploaded [required]
}
Response {
status: "ok",
id: id of the new file
}
POST /folder/<parent_id>
Description: Create a new folder in parent
Request {
<parent_id>: id of the parent folder we want to create in [required]
name: name of folder to be created [required]
}
Response {
status: "ok",
id: id of the new folder
}
GET /file/info/<file_id>
Description: get a file's metadata
Request {
<file_id>: id of target file [required]
}
Response {
status: "ok",
file: {
id: file id,
name: file name,
size: size in bytes,
mimeType: file mime type,
senderName: name of person who uploaded,
company: sender company,
subject: subject of file,
notes: file note,
confirmed: has this file been confirmed received?,
unread: has this file been unread?,
signed: is this file signed?,
created: created date (gmt),
modified: modified date (gmt)
}
}
GET /file/download/<file_id>
Description: download a file
Request {
<file_id>: id of target file [required]
}
Response: Full file contents. File name and mime type included in http response header. Typically response content should be
saved to a local file with the name specified in the header.
GET /memo/<memo_id>
Description: fetch a memo
Request {
<memo_id>: id of memo [required]
}
Response {
status: "ok",
memo: {
id: memo id,
title: memo title,
text: memo contents,
created: created date (gmt),
modified: modified date (gmt)
}
}
POST /memo/<folder_id>
Description: create a new memo
Request {
<folder_id>: memo folder id [required],
title: memo title string [required],
text: memo text string [required]
}
Response {
status: "ok",
id: memo id
}
POST /request/upload/<box_id>
Description: email an upload request
Request {
<box_id>: id of the upload target box [required]
email: email address of recipient [required]
expireDays: how many days before email link expires (0-14)
note: note to be included with email body
}
Response {
status: "ok"
}
POST /request/whistlepage/<page_id>
Description: email a whistlePage request
Request {
<page_id>: id of the page to be requested [required]
email: email address of recipient [required]
expireDays: how many days before email link expires (0-14)
note: note to be included with email body
}
Response {
status: "ok"
}
POST /request/signature/<file_id>
Description: email a signature request
Request {
<file_id>: optional id of the file to be signed
file_ids: comma separated list of file_ids [required?]
email: email address of recipient [required]
accessType: Security type required of signor [required]
accessCode: security code signor must enter [required?]
expireDays: how many days before email link expires (1-14)
note: note to be included with email body
}
Response {
status: "ok"
}
Notes:
- If <file_id> is omitted, file_ids are required
- accessType: 'NONE', 'SSN4', 'SSN5', 'ZIP5', 'PHONE4', 'CUSTOM'
- accessCode is required if accessType is not NONE.
POST /request/download/<file_id>
Description: email a download request
Request {
<file_id>: optional id of the file to be signed,
file_ids: comma separated list of file_ids [required?],
email: email address of recipient [required],
accessType: Security type required of signor [required],
accessCode: security code signor must enter [required?],
expireDays: how many days before email link expires (1-14),
note: note to be included with email body
}
Response {
status: "ok"
}
Notes:
- If <file_id> is omitted, file_ids are required
- accessType: 'NONE', 'SSN4', 'SSN5', 'ZIP5', 'PHONE4', 'CUSTOM'
- accessCode is required if accessType is not NONE.
POST /report/log/upload
Description: generate upload request log report. For large reports, can be called repeatedly to get record sets.
Request {
startDate: report period start (YYYY-MM-DD) [required],
endDate: report period end (YYYY-MM-DD) [required],
limit: max records to return (default 5000),
startAt: start record number(default 0)
}
Response {
status: "ok",
entries: [{
folderId: box id,
folderName: box name,
email: recipient's email,
status: request status,
expires: expiration date,
created: created date
}],
count: number of records returned in this set,
total: total records in report,
next: record number beginning of next set (-1 if last set)
}
Notes: If total records is greater than the limit, startAt can be used in successive calls by using returned "next" value to retrieve the next set of records.
POST /report/log/whistlepage
Description: generate WhistlePage request log report. For large reports, can be called repeatedly to get record sets.
Request {
startDate: report period start (YYYY-MM-DD) [required]
endDate: report period end (YYYY-MM-DD) [required]
limit: max records to return (default 5000)
startAt: start record number(default 0)
}
Response {
status: "ok",
entries: [{
pageId: whistlepage id,
pageName: whistlepage name,
email: recipient's email,
status: request status,
expires: expiration date,
created: created date
}],
count: number of records returned in this set,
total: total records in report,
next: record number beginning of next set (-1 if last set)
}
Notes: If total records is greater than the limit, startAt can be used in successive calls by using returned "next" value to retrieve the next set of records.
POST /report/log/download
Description: generate download request log report. For large reports, can be called repeatedly to get record sets.
Request {
startDate: report period start (YYYY-MM-DD) [required]
endDate: report period end (YYYY-MM-DD) [required]
limit: max records to return (default 5000)
startAt: start record number(default 0)
}
Response {
status: "ok",
entries: [{
fileId: file id,
fileName: filename,
accessType: security access type,
accessCode: security access code,
email: recipient's email,
status: request status,
expires: expiration date,
created: created date
}],
count: number of records returned in this set,
total: total records in report,
next: record number beginning of next set (-1 if last set)
}
Notes: If total records is greater than the limit, startAt can be used in successive calls by using returned "next" value to retrieve the next set of records.
POST /report/log/signature
Description: generate signature request log report. For large reports, can be called repeatedly to get record sets.
Request {
startDate: report period start (YYYY-MM-DD) [required]
endDate: report period end (YYYY-MM-DD) [required]
limit: max records to return (default 5000)
startAt: start record number(default 0)
}
Response {
status: "ok",
entries: [{
fileId: file id,
fileName: filename,
accessType: security access type,
accessCode: security access code,
email: recipient's email,
status: request status,
expires: expiration date,
created: created date
}],
count: number of records returned in this set,
total: total records in report,
next: record number beginning of next set (-1 if last set)
}
Notes: If total records is greater than the limit, startAt can be used in successive calls by using returned "next" value to retrieve the next set of records.
POST /report/log/sender
Description: generate sender log report. For large reports, can be called repeatedly to get record sets.
Request {
startDate: report period start (YYYY-MM-DD) [required]
endDate: report period end (YYYY-MM-DD) [required]
limit: max records to return (default 5000)
startAt: start record number(default 0)
}
Response {
status: "ok",
entries: [{
wbAddress: whistlebox address,
fileId: file id,
fileName: file name,
folderName: box name,
signRequest: is a signature requested?,
expires: signing request expiration date,
downloaded: has signed document been accessed?,
confirmRequest: is a confirmation requested?,
Confirmed: has this file been confirmed?,
created: sent date
}],
count: number of records returned in this set,
total: total records in report,
next: record number beginning of next set (-1 if last set)
}
Notes: If total records is greater than the limit, startAt can be used in successive calls by using returned "next" value to retrieve the next set of records.
POST /report/log/audit
Description: generate audit log report. For large reports, can be called repeatedly to get record sets.
Request {
startDate: report period start (YYYY-MM-DD) [required]
endDate: report period end (YYYY-MM-DD) [required]
limit: max records to return (default 5000)
startAt: start record number(default 0)
}
Response {
status: "ok",
entries: [{
userName: name of user ,
action: what was done,
on: object of the action,
to: result of the action,
created: action date
}],
count: number of records returned in this set,
total: total records in report,
next: record number beginning of next set (-1 if last set)
}
Notes: If total records is greater than the limit, startAt can be used in successive calls by using returned "next" value to retrieve the next set of records.
GET /test/ping
Description: test your APIKEY connection
Request {
}
Response {
"status": "ok"
}