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.

Caution: API endpoint "Get list of files" (/files) is removed and can no longer be used. Calling this endpoint will return a HTTP 410 (Gone) response.

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
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)
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
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)
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
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 list of files (Removed)

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

Caution: This API endpoint is removed and can no longer be used. Calling this endpoint will return a HTTP 410 (Gone) response.
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)
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
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
    }
}

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)
options FileOption [ ] Array of additional options for this file
id string Option ID
value mixed Option value
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 started
Sell with Printful
Create custom products
Explore
Resources
About Printful
Latest updates
Printful
So much more than printing

Trusted to deliver 32.4M items
since 2013

Payment methods we accept:

We deliver with:

© 2013 - 2021 All Rights reserved. Printful® Inc. 11025 Westlake Dr, Charlotte, North Carolina 28273