Scout PDF API
- Linh Cao
- Scott Malabarba
- Stacy Reno (Unlicensed)
This article describes how to utilize the PDF Scout™ Inspector Tool API to check or pre-flight PDF files.
- PDF files are uploaded to Scout.
- A Scout process will analyze the PDF for pre-configured checks such as file size, known corrupted PDF data, page dimensions, etc
- Scout results are available via the url /api/scout (POST) in json format
Scout checks are required before PDF files can be used for plan review in EPR.
Best Practices
e-PlanREVIEW® (EPR) will not accept plan review documents rejected by Scout. All plan review documents must be submitted in PDF format.
Prerequisites
See: Scout Inspector Tool
SCOUT API Step-by-step guide
Open a support ticket to get your SCOUT API credentials, please include your name company or agency name.
Postman collection to help with API development: scout-client.postman_collection.json.
Overview of PDF checking with Scout:
Get a scout token.
url: <scout-url>/api/auth (POST)
- API parameters: username/password
- Get an "upload" url
- Upload file using the "upload" url obtained from step 2
- Call Scout to get the json result.
ALERT!
Tokens automatically expire after 12 hours of inactivity.
Step 1. Get a token
POST https://scout-api.eplansoftreview.com/api/auth
Request Body format:
{
"username": "admin_username",
"password": "admin_password"
}
Sample Response:
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImVwbGFuYWRtaW4iLCJpYXQiOjE1MjU0NDk2MDcsImV4cCI6MTUyNTQ1MzIwN30.5uRl1WIjpGwJaA-qVbnYI_wenzKl0bRy6RPuvp2WUzo"
}
Step 2. Get an Upload Url
GET https://scout-api.eplansoftreview.com/api/uploadUrl?filename=your_filename
Sample Response:
{
"success": true,
"message": "Use the method and url to upload file to Scout server.",
"data": {
"method": "PUT",
"url": "https://eplan-scout.s3.us-west-2.amazonaws.com/1525449678912evil.pdf?Content-Type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIGT7NUYPP3IOYOBA%2F20180504%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20180504T160118Z&X-Amz-Expires=300&X-Amz-Signature=0cf8ad94edf98902134f7909246549d2b1059fc228bb2054f9fea42d33f2f1a2&X-Amz-SignedHeaders=host",
"contentType": "application/pdf",
"filename": "sample.pdf",
"filePath": "1525449678912sample.pdf"
}
}
Step 3. Upload file to Scout Server
PUT [url_from_last_step]
Note: You must upload file using the PUT method.
Step 4. Call Scout api to get the result
POST https://scout-api.eplansoftreview.com/api/scout
Request Body format:
{
"filePath": "filePath from step 2 response body"
}
Sample Response:
{
"success": true,
"data": {
"filename": "1525449678912sample.pdf",
"filesize": 73121,
"numPages": 1,
"outlines": null,
"results": [
{
"key": "accessible",
"success": true,
"value": null
},
{
"key": "version",
"success": true,
"value": "1.7"
},
{
"key": "size",
"success": true,
"value": "0.07MB"
},
{
"key": "rotation",
"success": true,
"value": null
},
{
"key": "pageAccess",
"success": true,
"value": null
},
{
"key": "annotation",
"success": true,
"value": null
},
{
"key": "resolution",
"success": true,
"value": null
}
],
"pages": [
{
"pageNumber": 1,
"dimension": {
"pageNumber": 1,
"mediaBox": [
0,
0,
1728,
1296
],
"rotate": 0,
"orientation": "Landscape",
"width": 1728,
"height": 1296
},
"pageAccess": {
"value": null,
"errMessage": null,
"debugData": null
},
"annotation": {
"value": null,
"errMessage": null,
"debugData": null
},
"resolution": {
"value": null,
"errMessage": null,
"debugData": null
}
}
],
"pageDimensions": {
"1": {
"pageNumber": 1,
"mediaBox": [
0,
0,
1728,
1296
],
"rotate": 0,
"orientation": "Landscape",
"width": 1728,
"height": 1296
}
},
"author": "",
"version": 1.7,
"isPassed": true
}
}
Determining the Results
Check "isPassed" value in the response body to see if the file passes Scout.
Best Practices
Documents rejected by Scout should be rejected in the public facing/customer portal.