Sign in Sign up

File Library API

To avoid the need to upload every file again when the same item is ordered, your print files are stored in the File Library and can be reused.

You can use this API to directly add files to the library, and later use File IDs when creating orders. However the more convenient way is to specify the files by URL at the same time the order is created.

Most probably you will never need to use this API - just specify the file URL when creating orders and the files will be added automatically.

File processing can be very time consuming, so they are processed asynchronously. After you add a file, it is saved with the status waiting and downloaded and processed later. Afterwards the status is changed to ok if the file was loaded successfully and was a valid image file, or failed if the process did not succeed. Some of the file metadata fields like dimensions and resolution are only filled in after the file has been processed.

If an order with a file has been confirmed before the file was processed and the file turns out to be invalid, then the order is reverted to a failed state and needs to be corrected and confirmed again.

If you try to add a file that has an identical URL to an already existing file, then no new file is created, and the system returns the old one without refreshing its contents.

Remember - if you have changed the original, make sure that the URL is changed as well for future orders, otherwise the old version will be reused.
You can add a “last modified” timestamp to the end of the URL to ensure that the URL is different for changed files.

Files that are added through the API can be set not to show up in the File library on the web, just set the visible attribute to false when creating them.

Get list of files

GET https://api.printful.com/files

Returns list of last added files
Input parameters:
status string Filter by file status
offset integer Result set offset
limit integer Number of items per page (max 100)
Response format:
code integer Response status code 200
result File [ ]
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer Resolution DPI.
Note: for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
paging Paging Paging information
total integer Total number of items available
offset integer Current result set page offset
limit integer Max number of items per page
API key
status Filter by file status
offset Result set offset
limit Number of items per page (max 100)
Execute
File list with one file just added and three already processed.
Response data: 
{
    "code": 200,
    "result": [{
        "id": 11815,
        "type": "default",
        "hash": null,
        "url": "http://www.example.com/images/tshirts/front_123.pdf",
        "filename": null,
        "mime_type": null,
        "size": 0,
        "width": null,
        "height": null,
        "dpi": null,
        "status": "waiting",
        "created": 1390818471,
        "thumbnail_url": null,
        "preview_url": null,
        "visible": true
    }, {
        "id": 10003,
        "type": "preview",
        "hash": "8a635765cc782c8c72a2a37ab7729a07",
        "url": "http://example.com/images/tshirts/preview_1.jpg",
        "filename": "tshirt_preview.jpg",
        "mime_type": "image/jpeg",
        "size": 19941,
        "width": 420,
        "height": 200,
        "dpi": 72,
        "status": "ok",
        "created": 1390818271,
        "thumbnail_url": "https://www.printful.com/storage/files/1559/8/8a635765cc782c8c72a2a37ab7729a07_thumb.png",
        "preview_url": "https://www.printful.com/storage/files/1559/8/8a635765cc782c8c72a2a37ab7729a07_preview.png",
        "visible": false
    }, {
        "id": 10002,
        "type": "default",
        "hash": "f259979918a51587c636fbc41508ce9b",
        "url": null,
        "filename": "mug-template.psd",
        "mime_type": "image/x-psd",
        "size": 1268210,
        "width": 2700,
        "height": 1380,
        "dpi": 300,
        "status": "ok",
        "created": 1390554376,
        "thumbnail_url": "https://www.printful.com/storage/files/1559/f/f259979918a51587c636fbc41508ce9b_thumb.png",
        "preview_url": "https://www.printful.com/storage/files/1559/f/f259979918a51587c636fbc41508ce9b_preview.png",
        "visible": true
    }, {
        "id": 11802,
        "type": "default",
        "hash": "756a648308bf49d4b763b87cdbd301dc",
        "url": "http://example.com/images/posters/test.pdf",
        "filename": "test.pdf",
        "mime_type": "application/pdf",
        "size": 5846629,
        "width": 5000,
        "height": 6667,
        "dpi": 300,
        "status": "ok",
        "created": 1390551170,
        "thumbnail_url": "https://www.printful.com/storage/files/1559/7/756a648308bf49d4b763b87cdbd301dc_thumb.png",
        "preview_url": "https://www.printful.com/storage/files/1559/7/756a648308bf49d4b763b87cdbd301dc_preview.png",
        "visible": true
    }],
    "paging": {
        "total": 4,
        "offset": 0,
        "limit": 20
    }
}

Add a new file

POST https://api.printful.com/files

Adds a new File to the library by providing URL of the file.

If a file with identical URL already exists, then the original file is returned. If a file does not exist, a new file is created.

Input parameters:
Request body File File data (url parameter is required)
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer Resolution DPI.
Note: for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
Response format:
code integer Response status code 200
result File
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer Resolution DPI.
Note: for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
API key
Request body
Execute
Add file to the print file library, file name will be detected from URL. After creation file is not processed instantly.
Request body: 
{
    "url": "http://www.example.com/files/tshirts/example.psd"
}
Response data: 
{
    "code": 200,
    "result": {
        "id": 11816,
        "type": "default",
        "hash": null,
        "url": "http://www.example.com/files/tshirts/example.psd",
        "filename": null,
        "mime_type": null,
        "size": 0,
        "width": null,
        "height": null,
        "dpi": null,
        "status": "waiting",
        "created": 1390819101,
        "thumbnail_url": null,
        "preview_url": null,
        "visible": true
    }
}
Add file to the mockup library, and specify file name manually
Request body: 
{
    "type": "preview",
    "url": "http://www.example.com/files/tshirts/example.png",
    "filename": "shirt1.png"
}
Add file to the library, but not show up in the web interface
Request body: 
{
    "url": "http://www.example.com/files/tshirts/example.psd",
    "visible": 0
}

Get file information

GET https://api.printful.com/files/{id}

Returns information about the given file
Input parameters:
id integer File ID
Response format:
code integer Response status code 200
result File
id integer File ID
type string Role of the file in the order
hash string MD5 checksum of the file
url string Source URL where the file is downloaded from
filename string File name
mime_type string MIME type of the file
size integer Size in bytes
width integer Width in pixels
height integer Height in pixels
dpi integer Resolution DPI.
Note: for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
status string File processing status:
ok - file was processed successfuly
waiting - file is being processed
failed - file failed to be processed
created timestamp File creation time
thumbnail_url string Small thumbnail URL
preview_url string Medium preview image URL
visible boolean Show file in the Printfile Library (default true)
API key
id File ID
Execute
Response data: 
{
    "code": 200,
    "result": {
        "id": 11802,
        "type": "default",
        "hash": "756a648308bf49d4b763b87cdbd301dc",
        "url": "http://example.com/images/posters/test.pdf",
        "filename": "test.pdf",
        "mime_type": "application/pdf",
        "size": 5846629,
        "width": 5000,
        "height": 6667,
        "dpi": 300,
        "status": "ok",
        "created": 1390551170,
        "thumbnail_url": "https://www.printful.com/storage/files/1559/7/756a648308bf49d4b763b87cdbd301dc_thumb.png",
        "preview_url": "https://www.printful.com/storage/files/1559/7/756a648308bf49d4b763b87cdbd301dc_preview.png",
        "visible": true
    }
}

Ready to try Printful ?

Get Me Started

Products

Services

Resources

Features

Printful

From the blog

Printful
So much more than printing

Trusted to deliver 10.2M items since 2013

© 2013 - 2019 Printful® Inc. All Rights reserved.