File Upload API (UAS)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 29, 2017
Version 4Show Document
  • View in full screen mode

Description

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

For more information about UAS Creative Management Services, refer to 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.
pubTokenString${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"

Important note: The file=<file name which you would like to upload> should not contain the space in between name or special 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.Upload Zip File for HTML5 Creative

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"

Important note: The file=<file name which you would like to upload> should not contain the space in between name or special non English characters or Zip file should not contain file having spaces in the name 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

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

 

 

Version 0.17

Attachments

    Outcomes