Scout PDF API

Owned by Linh Cao
Last updated: Jun 06, 2023
7 min read

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

Send email to lcao@eplansoft.com 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:

  1. Get a scout token.

    1. url: <scout-url>/api/auth (POST)

    2. API parameters: username/password
  2. Get an "upload" url
  3. Upload file using the "upload" url obtained from step 2
  4. 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.