Box API Documentation

The PrintOS Box API is a RESTful API which involves HTTP commands (GET, POST, PUT etc.) to a base URL followed by a specific endpoint path.  The base URLs and endpoints are covered below.

Table of Contents

Base URL

  • Production:  https://printos.api.hp.com/box  (for current PrintOS customers)
  • Staging: https://stage.printos.api.hp.com/box  (for 3rd parties with a development account)

Code samples: https://github.com/HPInc/printos-box-api-samples/
 


Create a Folder

HTTP Method Endpoint Body
POST /api/partner/folder JSON Object

HTTP Body:

{
    "name": "Folder Name",
    "from": "Sender",
    "to": "Receiver",
    "files": [{
        "name": "File name",
        "copies": 1,
        "notes": "This is a file",
        "url": "File url"
    }]
}
Field Required Description
name Yes Name of the folder to be created
from

Optional

Should be an email that can be replied to for queries on this order
to Optional  
files Optional Files to upload into the folder after creation
{
    "__v": 0,
    "_id": "581ca993772bca1000bba26b",
    "created": "2016-09-07T17:43:54.193Z",
    "createdAt": "2016-09-07T17:43:54.193Z",
    "createdFrom": "box",
    "fileCount": 0,
    "from": "Python_Sender",
    "lname": "python_folder",
    "modified": "2016-09-07T17:43:54.193Z",
    "name": "Python_Folder",
    "organizationId": "Organization_id",
    "preflightStatus": "ok",
    "status": "ready",
    "tags": [],
    "to": "Python_Receiver",
    "totalSize": 0,
    "unread": false,
    "updatedAt": "2016-09-07T17:43:54.193Z"
}

Note: The "_id" field contains the unique ID for this folder and must be retained for future folder queries, or file uploads to that folder.


Query a Folder

HTTP Method Endpoint
GET /api/partner/folder/{folderId}

Note: The folderId is returned from the JSON response after creating a folder (See response portion of creating a folder or response below. _id is the folder Id needed). 

{
    "__v": 0,
    "_id": "581ca993772bca1000bba26b",
    "created": "2016-11-04T15:30:27.285Z",
    "createdAt": "2016-11-04T15:30:27.285Z",
    "createdFrom": "box",
    "fileCount": 1,
    "lname": "python_folder",
    "modified": "2016-11-09T16:23:16.028Z",
    "name": "Python_Folder",
    "organizationId": "18e59aed-1973-4bc9-a57d-4b33709e229f",
    "preflightStatus": "ok",
    "status": "ready",
    "tags": [],
    "to": "Python_Receiver",
    "totalSize": 7945,
    "unread": false,
    "updatedAt": "2016-11-09T21:08:02.219Z"
}

 

Upload File

Two ways to upload a file into Box.

  1. Direct file submission using the files external URL.
  2. Local file which needs to be hosted before a direct file submission.

Direct File Submission:

HTTP Method Endpoint Body
POST /api/partner/file JSON Object

HTTP Body:

{
    "url": "https://FileHostSite/path/file1.pdf",
    "name": "Super cool file",
    "folderId":"581ca993772bca1000bba26b",
    "copies": 5,
    "notes": "This is a super cool file",
    "substrate": "Sandpaper",
    "flow": "Preflight"
}
Field Required Description
url Yes External URL where file is hosted
name Yes Name of file as it will appear in Box
folderId Yes Id of the folder to upload file to
copies Optional Number of copies
notes Optional Any additional information to provide when file is uploaded
substrate Optional Substrate information for the file
flow Optional Select a pre-defined flow for this file
{
    "__v": 1,
    "_id": "58239975772bca1000bba8e0",
    "created": "2016-11-09T21:47:33.589Z",
    "createdAt": "2016-11-09T21:47:33.589Z",
    "currentRevision": 2,
    "currentVersion": {
        "_id": "58239975772bca1000bba8e4",
        "created": "2016-11-09T21:47:33.694Z",
        "pageConfigs": [],
        "pageCount": 0,
        "pages": [],
        "preflight": {
            "fixups": []
        },
        "profile": "standard",
        "revision": 2,
        "size": 0,
        "status": "pending"
    },
    "currentVersionId": "58239975772bca1000bba8e4",
    "folderId": "581ca993772bca1000bba26b",
    "id": "58239975772bca1000bba8e0",
    "lastAction": "Preflighting",
    "lastPrinted": null,
    "lastSent": null,
    "modified": "2016-11-09T21:47:33.714Z",
    "name": "Python_File (1).pdf",
    "organizationId": "18e59aed-1973-4bc9-a57d-4b33709e229f",
    "printInstructions": {
        "copies": 1,
        "notes": "File was uploaded using Python"
    },
    "size": 0,
    "sourceUrl": "http://www.cbu.edu.zm/downloads/pdf-sample.pdf",
    "updatedAt": "2016-11-09T21:47:33.713Z",
    "versions": [
        {
            "_id": "58239975772bca1000bba8e2",
            "created": "2016-11-09T21:47:33.589Z",
            "pageConfigs": [],
            "pageCount": 0,
            "pages": [],
            "preflight": {
                "fixups": []
            },
            "revision": 1,
            "size": 0,
            "status": "pending"
        },
        {
            "_id": "58239975772bca1000bba8e4",
            "created": "2016-11-09T21:47:33.694Z",
            "pageConfigs": [],
            "pageCount": 0,
            "pages": [],
            "preflight": {
                "fixups": []
            },
            "profile": "standard",
            "revision": 2,
            "size": 0,
            "status": "pending"
        }
    ]
}

Note: The _id (third line of the response) is used to query information about the file.

 

Get Upload URL:

Note: This API is only to provide an upload URL where you can host a file on your local system. If your file is on an external URL already, see above to do a Direct file submission.

HTTP Method Endpoint Parameters
GET /api/partner/file/uploadurls

?mimeType=application/pdf 

(where the mimeType value matches file type to upload)

HTTP Response:

{
  "upload": "https://dev-printbox-files.s3-eu-west-1.amazonaws.com/85b2f78b-423f-4774-bfc3-8ce032b3439b/uploads/2016-05-25/d3ac1f25-ba22-4f2d-868b-e7822adfa583?AWSAccessKeyId=AKIAI62PBE3X6DSRJ3GQ&Content-Type=application%2Fpdf&Expires=1464298497&Signature=Ea5P2pg3vsF%2BiTpDV%2FdffhIer2I%3D",
  "fetch": "https://dev-printbox-files.s3-eu-west-1.amazonaws.com/85b2f78b-423f-4774-bfc3-8ce032b3439b/uploads/2016-05-25/d3ac1f25-ba22-4f2d-868b-e7822adfa583?AWSAccessKeyId=AKIAI62PBE3X6DSRJ3GQ&Expires=1464298497&Signature=ViGSYt0ccQYO9Up832qpwiFt%2FxA%3D"
}

Upload File to Upload URL:

HTTP Method Endpoint HTTP Headers
PUT "upload" url (see HTTP Response above)

Content-Type = application/pdf

(where Content-Type value matches file mime type)

HTTP Response:

HTTP Status = 200 OK   (no message content)

Note: After a 200 OK status, the fetch URL will be the url you use to do a direct file submission.
 


Query a File

HTTP Method Endpoint
GET /api/partner/file/{fileId}

Note: ​The fileId is returned from the JSON response after a direct file submission (See response, first occurence of _id is the fileId used for this API call).  

{
    "__v": 1,
    "_id": "58239975772bca1000bba8e0",
    "created": "2016-11-09T21:47:33.589Z",
    "createdAt": "2016-11-09T21:47:33.589Z",
    "currentRevision": 2,
    "currentVersion": {
        "_id": "58239975772bca1000bba8e4",
        "contentType": "application/pdf",
        "created": "2016-11-09T21:47:33.694Z",
        "downloadUrl": "",
        "pageConfigs": [
            {
                "_id": "5823997e772bca1000bba8f3",
                "boxes": {
                    "media": {
                        "bottom": 0,
                        "left": 0,
                        "right": 209.90277777777771,
                        "top": 297.03888888888883
                    }
                },
                "colors": [
                    "Cyan",
                    "Magenta",
                    "Yellow",
                    "Black"
                ],
                "height": 297.03888888888883,
                "rotation": 0,
                "width": 209.90277777777771
            }
        ],
        "pageCount": 1,
        "pageThumbnailPath": "default/workqueues/2016-11-09/5823997567b95a1300d2fcb7/5823997567b95a1300d2fcb3/thumb_{page}_400.png",
        "pages": [
            0
        ],
        "preflight": {
            "annotatedUrl": "",
            "fixups": [
                {
                    "_id": "58239982772bca1000bba8f9",
                    "count": "5",
                    "display_comment": "If a PDF uses fonts which are not embedded into the PDF file they are embedded when using this fixup. It is required that the respective fonts are available in the operating system or in a specified folder. Some fonts may have a flag indicating that their licence does not allow embedding. In this case the fonts are not embedded into the PDF.",
                    "display_name": "Embed missing fonts",
                    "name": "FIX1",
                    "severity": "SUCCESS",
                    "type": "fixup"
                },
                {
                    "_id": "58239982772bca1000bba8f8",
                    "count": "1",
                    "display_comment": "Repairs syntactical problems in the ToUnicode CMap of CID fonts.",
                    "display_name": "Repair invalid ToUnicode CMap information in fonts",
                    "name": "FIX2",
                    "severity": "SUCCESS",
                    "type": "fixup"
                },
                {
                    "_id": "58239982772bca1000bba8f7",
                    "count": "22",
                    "display_comment": "Object uses a device independent color space (ICC based Gray/RGB/CMYK, Lab, CalRGB or CalGray).",
                    "display_name": "Uses device independent color",
                    "name": "RUL13",
                    "severity": "Info",
                    "type": "check"
                }
            ],
            "result": "passed"
        },
        "profile": "standard",
        "revision": 2,
        "size": 7945,
        "status": "ready",
        "thumbnailUrl": ""
    },
    "currentVersionId": "58239975772bca1000bba8e4",
    "folderId": "581ca993772bca1000bba26b",
    "id": "58239975772bca1000bba8e0",
    "lastAction": "Preflight",
    "lastPrinted": null,
    "lastSent": null,
    "modified": "2016-11-09T21:47:46.271Z",
    "name": "Python_File (1).pdf",
    "organizationId": "18e59aed-1973-4bc9-a57d-4b33709e229f",
    "printInstructions": {
        "copies": 1,
        "notes": "File was uploaded using Python"
    },
    "size": 7945,
    "sourceUrl": "",
    "updatedAt": "2016-11-09T21:47:46.271Z",
    "versions": [
        {
            "_id": "58239975772bca1000bba8e2",
            "contentType": "application/pdf",
            "created": "2016-11-09T21:47:33.589Z",
            "downloadUrl": "",
            "pageConfigs": [
                {
                    "_id": "5823997a772bca1000bba8ec",
                    "boxes": {
                        "media": {
                            "bottom": 0,
                            "left": 0,
                            "right": 209.90277777777771,
                            "top": 297.03888888888883
                        }
                    },
                    "colors": [
                        "Cyan",
                        "Magenta",
                        "Yellow",
                        "Black"
                    ],
                    "height": 297.03888888888883,
                    "rotation": 0,
                    "width": 209.90277777777771
                }
            ],
            "pageCount": 1,
            "pageThumbnailPath": "default/workqueues/2016-11-09/582399756e73c913004f84b8/582399756e73c913004f84b6/thumb_{page}_400.png",
            "pages": [
                0
            ],
            "preflight": {
                "fixups": []
            },
            "revision": 1,
            "size": 7945,
            "status": "ready",
            "thumbnailUrl": ""
        },
        {
            "_id": "58239975772bca1000bba8e4",
            "contentType": "application/pdf",
            "created": "2016-11-09T21:47:33.694Z",
            "downloadUrl": "",
            "pageConfigs": [
                {
                    "_id": "5823997e772bca1000bba8f3",
                    "boxes": {
                        "media": {
                            "bottom": 0,
                            "left": 0,
                            "right": 209.90277777777771,
                            "top": 297.03888888888883
                        }
                    },
                    "colors": [
                        "Cyan",
                        "Magenta",
                        "Yellow",
                        "Black"
                    ],
                    "height": 297.03888888888883,
                    "rotation": 0,
                    "width": 209.90277777777771
                }
            ],
            "pageCount": 1,
            "pageThumbnailPath": "default/workqueues/2016-11-09/5823997567b95a1300d2fcb7/5823997567b95a1300d2fcb3/thumb_{page}_400.png",
            "pages": [
                0
            ],
            "preflight": {
                "annotatedUrl": "",
                "fixups": [
                    {
                        "_id": "58239982772bca1000bba8f9",
                        "count": "5",
                        "display_comment": "If a PDF uses fonts which are not embedded into the PDF file they are embedded when using this fixup. It is required that the respective fonts are available in the operating system or in a specified folder. Some fonts may have a flag indicating that their licence does not allow embedding. In this case the fonts are not embedded into the PDF.",
                        "display_name": "Embed missing fonts",
                        "name": "FIX1",
                        "severity": "SUCCESS",
                        "type": "fixup"
                    },
                    {
                        "_id": "58239982772bca1000bba8f8",
                        "count": "1",
                        "display_comment": "Repairs syntactical problems in the ToUnicode CMap of CID fonts.",
                        "display_name": "Repair invalid ToUnicode CMap information in fonts",
                        "name": "FIX2",
                        "severity": "SUCCESS",
                        "type": "fixup"
                    },
                    {
                        "_id": "58239982772bca1000bba8f7",
                        "count": "22",
                        "display_comment": "Object uses a device independent color space (ICC based Gray/RGB/CMYK, Lab, CalRGB or CalGray).",
                        "display_name": "Uses device independent color",
                        "name": "RUL13",
                        "severity": "Info",
                        "type": "check"
                    }
                ],
                "result": "passed"
            },
            "profile": "standard",
            "revision": 2,
            "size": 7945,
            "status": "ready",
            "thumbnailUrl": ""
        }
    ]
}

 


Get Available Substrates

HTTP Method Endpoint
GET /api/partner/substrate

You can query the current list of substrates available so that an uploaded file can be assigned one of these substrates.  In order for a substrate to be returned in this query a substrate must be configured in Box to "Display in Easy Submit", and must have an "Easy Submit Name" defined.

HTTP Response: 

Array of substrate names

Note: When submitting a file and defining a substrate, the name of the substrate must match an existing Easy Submit substrate name, or an HTTP 404 "Not Found" response will be returned with a message "The requested resource couldn't be found".


Get List of Flows

HTTP Method Endpoint
GET /api/partner/flow
{
	"count": 3,
	"items": [{
			"_id": "59371e914459ca12008e8ca7",
			"organizationId": "ed3d7bd2-6d3f-4f12-b6f1-04e5a30c1ddf",
			"name": "Impose Only",
			"ezName": "impose_only",
			"__v": 0,
			"deleted": false,
			"steps": {
				"send": {
					"enabled": false
				},
				"imposition": {
					"templateId": "44149",
					"templateName": "2UP Duplex on 320x470-1",
					"enabled": true
				},
				"preflight": {
					"stopIfWarn": false,
					"enabled": false
				}
			},
			"ezDisplay": true
		}, {
			"_id": "59371e4e2ce57a1200942d13",
			"organizationId": "ed3d7bd2-6d3f-4f12-b6f1-04e5a30c1ddf",
			"name": "Preflight Only",
			"ezName": "preflight_only",
			"__v": 0,
			"deleted": false,
			"steps": {
				"send": {
					"enabled": false
				},
				"imposition": {
					"enabled": false
				},
				"preflight": {
					"profileName": "standard",
					"profile": "standard",
					"profileId": null,
					"stopIfWarn": false,
					"enabled": true
				}
			},
			"ezDisplay": true
		}, {
			"_id": "5937212b4459ca12008e8d4f",
			"organizationId": "ed3d7bd2-6d3f-4f12-b6f1-04e5a30c1ddf",
			"name": "Preflight and Impose",
			"ezName": "preflight+impose",
			"__v": 0,
			"deleted": false,
			"steps": {
				"send": {
					"enabled": false
				},
				"imposition": {
					"templateName": "2UP Duplex on 320x470-1",
					"templateId": "44149",
					"enabled": true
				},
				"preflight": {
					"profileName": "standard",
					"profile": "standard",
					"profileId": null,
					"stopIfWarn": false,
					"enabled": true
				}
			},
			"ezDisplay": true
		}
	]
}

 

Note: When selecting a flow during file submission you can use either the "_id" value, or the "ezName" value from the response JSON.