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 |
Response Body:
{ "__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" }Query a Folder
| HTTP Method | Endpoint |
|---|---|
| GET | /api/partner/folder/{folderId} |
HTTP Body:
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.
- Direct file submission using the files external URL.
- 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 |
Response Body:
{ "__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" } ] }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) |
Response Body:
{ "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.90277777777772, "top": 297.03888888888886 } }, "colors": [ "Cyan", "Magenta", "Yellow", "Black" ], "height": 297.03888888888886, "rotation": 0, "width": 209.90277777777772 } ], "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.90277777777772, "top": 297.03888888888886 } }, "colors": [ "Cyan", "Magenta", "Yellow", "Black" ], "height": 297.03888888888886, "rotation": 0, "width": 209.90277777777772 } ], "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.90277777777772, "top": 297.03888888888886 } }, "colors": [ "Cyan", "Magenta", "Yellow", "Black" ], "height": 297.03888888888886, "rotation": 0, "width": 209.90277777777772 } ], "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.
Response Body:
[ "Gloss Text Content", "Matte Text", "Gloss Text Cover" ]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 |
Response Body:
{ "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.