File Upload API (UAS)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by david.simerly on Jul 31, 2018
Version 7Show Document
  • View in full screen mode
Before using PubMatic APIs, first generate the API Token. For more information, see Getting Started with PubMatic APIs.

Use the File Upload API to upload different creative assets supported for the selected Creative Type.

For more information about UAS Creative Management Services, see Creative Management Services (UAS)

Supported Operations

Method PathHTTP Method TypeDescription
/fileuploadPOST

This API will upload the file on the CDN Server using a multi-part Body:

  1. Accepts Content-Type "multi-part/form-data."
  2. Creates uploaded files on the CDN Server.
  3. Extracts zip file on CDN if decompress=true in request.

 

Request

 

Request Headers

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYes Content type of multi-part protocol along with boundary parameter required by multi-part entities.
AuthorizationStringBearer ${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

 

Request Parameters

Parameter NameTypeMandatoryDescription
accountLongYesYour account identifier
entityNameStringNoUsed to define the context in which the files are uploaded.This will be used to create sub-folders on CDN using this name.
decompress BooleanNo

Used to extract the compressed zip file on CDN. If decompress=true, the zip file will be uploaded and decompressed on the original server.

Note: Set decompress=true will perform HTML5 Validations on zip file and html file uploaded via this API.

 

Upload Image File for Creative

Request

 

Sample Request URL

https://api.pubmatic.com/v1/uas/fileupload?entityName=Creative&account=1&decompress=false

Post Body

curl -X POST -H "PubToken: sometoken" -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "Cache-Control: no-cache" -H "Postman-Token: sometoken" -F "file=@Pepsi_logo.jpeg" "http://$URI_PREFIX/{apiVersion}/phoenix/phoenix/fileupload?account=130917&entityName=Creative&decompress=false"

The file=<file name which you would like to upload> should not contain spaces or other non-printing or non-English characters.

Sample Request JSON

{
"files": [{
"filename": "Pepsi_logo.jpeg",
"url": "//$CDN_URI/Pepsi_logo.jpeg",
"status": "SUCCESS"
}]
}

 

Upload Zip File for HTML5 Creative

This endpoint is used to upload zip files or HTML5 files for HTML Creative. Here, the decompress flag is set to true. This request will be treated as HTML5 Creative Upload and HTML5 specific validations will be performed on uploaded zip file or HTML file.

 

Request

 

Sample Request URL

https://api.pubmatic.com/v1/uas/fileupload?entityName=Creative&account=1&decompress=true

 

Post Body

curl -X POST -H "PubToken: sometoken" -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "Cache-Control: no-cache" -H "Postman-Token: sometoken" -F "file=@filename.zip" "http://$URI_PREFIX/{apiVersion}/phoenix//fileupload?account=130917&entityName=Creative&decompress=true"
The file=<file name which you would like to upload> should not contain spaces or other non-printing or non-English characters.

 

Response

Sample Response JSON

{
    "files": [{
        "filename": "index.320x320.html",
        "url": "//$CDN_URI/index.320x320.html",
        "metadata": {
            "width": "320",
            "clickTags": [{
                "clickTag": "<clickTag URI if found in provided HTML>"
            }],
            "height": "320"
        }
    }, {
        "filename": "index.300x250.html",
        "url": "//$CDN_URI/index.300x250.html",
        "metadata": {
            "width": "300",
            "clickTags": [],
            "height": "250"
        }
    }, {
        "filename": "index.468x240.html",
        "url": "//$CDN_URI/index.468x240.html",
        "metadata": {
            "width": "468",
            "clickTags": [],
            "height": "240"
        }
    }, {
        "filename": "index.980x240.html",
        "url": "//$CDN_URI/index.980x240.html",
        "metadata": {
            "width": "980",
            "clickTags": [],
            "height": "240"
        }
    }, {
        "filename": "index.250x360.html",
        "url": "//$CDN_URI/index.250x360.html",
        "metadata": {
            "width": "250",
            "clickTags": [{
                "clickTag": "<clickTag URI if found in provided HTML>"
            }],
            "height": "360"
        }
    }]
}

 

Response Parameters

Parameter NameTypeDescription
filenameStringName of the file, which is uploaded.
urlString

URL of the CDN path where the file is uploaded.

Important note: The URL returned by API will not contained https: or http:  protocol and will start with // only.

Creative API will apply the https: or http: on PubMatic hosted Assets based on SSL Compatibility user has provided during Creative Create / Update operation.

metadataObject

Metadata holds all the required metadata information of the file that is uploaded. This field is populated in response when a zip file or html file is uploaded with decompress=true in the request.

The following are metadata of the uploaded file:

Parameter NameTypeDescription
widthStringWidth of the uploaded HTML5 creative
height StringHeight of the uploaded HTML5 creative
clickTagsArray of clickTagLanding page URL mentioned in uploaded HTML5 creative inside "clickTag" variable.

 

Error Codes for File Upload API

Sr. No.Error CodesDescription
1.PH_INVALID_REQUESTRequest is invalid.
2.PH_MISSING_REQUIRED_PARAMETERRequired parameters are missing in the request.
3.PH_MISSING_OR_INVALID_PARAMETERInvalid parameter is mentioned in the request.
4.PH_FILE_SIZE_EXCEEDS_MAX_LIMITMaximum File Size is exceeded for upload.
5.PH_FILE_TYPE_ALLOWEDUnsupported file type is uploaded.
6.PH_FILE_ALREADY_EXISTSFile already exists on the CDN Server.
7.PH_INVALID_FILE_NAMEInvalid file name is mentioned.
8.PH_MISSING_HTML5_FILEZip file does not contain any HTML5 file.
9.PH_FILE_SIZE_EXCEEDEDZip file size exceeds the size limit configured by the system.
12.PH_UNSUPPORTED_FILE_FORMATSZip file contains files that have an extension that is not supported.
13.PH_MISSING_REFERENCESThe HTML5 file inside the zip file has some references that are not present in the zip file.
14.PH_INVALID_HTML_5_FILEHTML file does not contain <!DOCTYPE html> at first line in the file.
15.PH_FILE_COUNT_LIMIT_EXCEEDEDThe number of files inside the zip file exceeds the limit configured in the system.

 

Unified Ad Server References

 

Version 0.17

 

⇧ Top

Attachments

    Outcomes