Upload a creative

Upload your first creative using IQM's API in this step-by-step quickstart guide.

The following endpoints are used to upload a creative:

POST
GET
POST
GET

About IQM creatives

The IQM APIs provide access to upload a creative in image, video, audio, HTML, XLSX, or CSV formats. The APIs can be used to connect to the desired applications.

More resources

• Creatives and specifications Help Center article
• Creative API guidelines

Before you begin

To upload a creative and create a campaign, the following are required:

1. An account on the IQM platform
   • See Before you begin to create an account and request a Client ID and Client Secret
2. Image, video, audio, HTML, VAST, DAAST, CSV, or XLSX file to upload creative

info

File requirements for creative file:

• 2MB for JPG, JPEG, PNG
• 750KB for GIF
• 400MB for MOV, MP4
• 100MB for MP3, WAV, OGG, MPEG

See IAB Tech Lab's documentation on VAST and DAAST for more information.

Sample CSV file: https://app.iqm.com/creatives/example-files/sample_html_creatives.csv

Authentication

Use the following header parameters for all requests after logging in:

Headers
Authentication string required	Authentication bearer token See Sign up and authenticate
X-IAA-OW-ID integer required	Organization Workspace ID Header

Upload a creative using the IQM API

This quickstart guide covers how to create a campaign and upload a creative.

The minimum requirements to perform this task are: logging in with authentication credentials, uploading a creative, and creating a campaign. Once these steps are accomplished, more can be learned about IQM's API through the guidelines pages.

1. Log in
   • Optional if you have already logged in and have a token
2. Request creative types
   • Optional if you already know supported/desired types
3. Upload creative file
4. Check creative status

Step 1: Log in

POST

To log in, the Authentication: Basic header is required. The Login API returns an OAuth-compliant response with an Organization Workspace ID (owId), a unique identifier for each organization. This ID is used for any further API communications.

For further information see OAuth token.

Headers
Authentication string required	Authentication bearer token See Sign up and authenticate

Request schema
grant_type string required	password for login OAuth Grant Types
username string required	User account email
password string required	User account password

JSON

Request sample

curl -i --location 'https://api.iqm.com/api/v3/ua/oauth/token' \
--header 'accept: application/json, text/plain, */*' \
--header 'Authorization: Basic <Client ID/Client Secret>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=user@iqm.com' \
--data-urlencode 'password=<your password>'

Response 200

{
  "success": true,
  "data":
  {
    "access_token": "106adb25-37b0-4cab-8381-d682fe7cc3c8",
    "refresh_token": "eac4c1f6-781e-4b04-baff-9c2e415d1f64",
    "scope": "read write",
    "token_type": "bearer",
    "expires_in": 35999,
    "owId": 200001
  }
}

More responses

Response 400

{
   "success": false,
   "data":
   {
      "status": "On Hold",
      "reason": "The particular account is kept on hold due to missed payment dates for last 3 months.",
      "supportEmail": "support@iqm.com"
   },
   "errorObjects":
   [
      {
         "error": "User is not allowed to access provided customer",
         "reason": "User is not associated with any active organization."
      }
   ]
}

Response 403

{
   "success": false,
   "errorObjects":
   [
      {
         "error": "User doesn't exist or user is not allowed to provided workspace."
      }
   ]
}

Step 2: Request creative types

GET

To upload a creative, a creative type must be provided. Use the creative type list endpoint to request a full list of allowed creative types.

For further information see Get creative types list.

JSON

Response 200

{
  "success": true,
  "data": {
    "data": [
      {
        "id": 17,
        "name": "Audio",
        "rtbTypeId": 2
      },
      {
        "id": 15,
        "name": "Native",
        "rtbTypeId": 4
      },
      {
        "id": 14,
        "name": "Video",
        "rtbTypeId": 3
      },
      {
        "id": 13,
        "name": "HTML",
        "rtbTypeId": 1
      },
      {
        "id": 11,
        "name": "Image",
        "rtbTypeId": 1
      }
    ],
    "totalRecords": 5,
    "filteredRecords": 5
  }
}

More responses

Response 500

{
  "statusCode": 500,
  "responseObject": {
    "errorMsg": "Internal server error",
    "errorCode": 500
  }
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: number;
          label: string;
          rtbTypeId: string;
        }[];
        totalRecords: number;
        filteredRecords: number;
      }
    };
  };
};

function getCreativeTypes_1(): Promise < Responses > {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/crt/master/static/creative-types',
    params: {
      query?: {
        creativeTypeIds?: `string`,
        ids?: `string`,
        pageNo?: `number`,
        noOfEntries?: `number`,
        sortBy?: `string`,
        order?: `string`,
        searchField?: `string`
      }
    }
  };

  return axios.request(options).then(({ data }: { data: Responses }) => data);
}

Step 3: Upload a creative

POST

Once you have the desired creative type ID, you can upload a creative. With the two request parameters, creativeRequest and creativeFiles, you add the creative metadata and the creative file respectively.

creativeRequest maps an ID to fields defining the creative metadata outlined in the table below and shown as an example in the request sample code block in the right-hand column.

creativeFiles are added as multipart format. See the MDN documentation on Multipart/form-data encoding for more information.

Request schema
creativeRequest form data required	This parameter accepts a map of IDs to creative metadata. Each ID corresponds to a single creative.
creativeFiles multipart/form-data	Array of creative files to upload. Required only when creative source type is FILE in the creative metadata. Each uploaded file's name must exactly match the creativeSource value specified in the corresponding creative object. Supports multiple file uploads for batch creative creation. Accepted file types include images (JPEG, PNG, GIF), videos (MP4, WebM), and audio (MP3, WAV, OGG).

Creative metadata

creativeName string	Creative name
externalCreativeId string	External creative ID
platformCreativeTypeId integer	Creative type ID +Supported values 0 All 11 Image 13 HTML 14 Video 15 Native 17 Audio
creativeSourceType string	Creative source type Supported values: HTML, FILE, URL, VAST_URL, VAST_XML, DAAST_URL, DAAST_XML
creativeSource string	Creative source
clickUrl string	Click URL
subMediaType integer	Subcategory of media type (for native video creatives)
htmlDetails object	HTML creative details
htmlDetails object properties creativeWidth integer Creative width (px) creativeHeight integer Creative height (px)
imageDetails object	Image creative details
imageDetails object properties pixelUrl string Pixel URL creativeWidth integer Creative width (px) creativeHeight integer Creative height (px)
audioDetails object	Audio creative details
audioDetails object properties duration integer Audio duration (s) customTracking object Custom tracking details customTracking object properties startUrl string Start URL firstQuartileUrl string First quartile URL midPointUrl string Midpoint URL thirdQuartileUrl string Third quartile URL completeUrl string Complete URL impressionUrl string Impression URL logoSource string Logo source
videoDetails object	Video creative details
videoDetails object properties creativeWidth integer Creative width (px) creativeHeight integer Creative height (px) duration integer Video duration (s) customTracking object Custom tracking details customTracking object properties startUrl string Start URL firstQuartileUrl string First quartile URL midPointUrl string Midpoint URL thirdQuartileUrl string Third quartile URL completeUrl string Complete URL impressionUrl string Impression URL
nativeDetails object	Native creative details
nativeDetails object properties title string Title description string Description cta object Call-to-Action object details (for native video) cta object properties id integer CTA ID ctaText string CTA display text defaultCta boolean Default CTA for associated creative brandName string Brand name brandIconSourceUrl string Brand icon source URL brandIconHeight integer Brand icon height (px) brandIconWidth integer Brand icon width (px) thumbnailSourceUrl string Thumbnail source URL (for native video) thumbnailHeight integer Thumbnail height (px, for native video) thumbnailWidth integer Thumbnail width (px, for native video)

Response properties

successData object	Success data
successData object properties PS string Partial success
failedData object	Failed data
failedData object properties PF string Partial failure

Request samplesForm data samplecURL sample

POST /api/v3/crt/creatives HTTP/1.1
Host: https://api.iqm.com
Authorization: Bearer YOUR_TOKEN_HERE
X-IAA-OW-ID: 12345
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="creativeRequest"

{"I001":{"creativeName":"Summer Sale Banner","externalCreativeId":"campaign-2024-001","platformCreativeTypeId":11,"creativeSourceType":"FILE","creativeSource":"summer-banner.jpg","clickUrl":"https://www.example.com/summer-sale","imageDetails":{"pixelUrl":"https://tracker.example.com/pixel","creativeWidth":728,"creativeHeight":90}},"V001":{"creativeName":"Product Demo Video","externalCreativeId":"campaign-2024-002","platformCreativeTypeId":14,"creativeSourceType":"FILE","creativeSource":"product-demo.mp4","clickUrl":"https://www.example.com/products","videoDetails":{"creativeWidth":1920,"creativeHeight":1080,"duration":30,"customTracking":{"startUrl":"https://tracker.example.com/start","firstQuartileURL":"https://tracker.example.com/25","midPointURL":"https://tracker.example.com/50","thirdQuartileURL":"https://tracker.example.com/75","completeURL":"https://tracker.example.com/complete","impressionURL":"https://tracker.example.com/impression"}}},"H001":{"creativeName":"Interactive HTML Ad","platformCreativeTypeId":13,"creativeSourceType":"HTML","creativeSource":"<a href='https://example.com'><img src='https://cdn.example.com/ad.jpg'></a>","clickUrl":"https://www.example.com","htmlDetails":{"creativeWidth":300,"creativeHeight":250}}}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="creativeFiles"; filename="summer-banner.jpg"
Content-Type: image/jpeg

[Binary image data]
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="creativeFiles"; filename="product-demo.mp4"
Content-Type: video/mp4

[Binary video data]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

curl -X POST https://api.iqm.com/api/v3/crt/creatives \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "X-IAA-OW-ID: 12345" \
  -F 'creativeRequest={"I001":{"creativeName":"Summer Sale Banner","externalCreativeId":"campaign-2024-001","platformCreativeTypeId":11,"creativeSourceType":"FILE","creativeSource":"summer-banner.jpg","clickUrl":"https://www.example.com/summer-sale","imageDetails":{"pixelUrl":"https://tracker.example.com/pixel","creativeWidth":728,"creativeHeight":90}},"V001":{"creativeName":"Product Demo Video","externalCreativeId":"campaign-2024-002","platformCreativeTypeId":14,"creativeSourceType":"FILE","creativeSource":"product-demo.mp4","clickUrl":"https://www.example.com/products","videoDetails":{"creativeWidth":1920,"creativeHeight":1080,"duration":30,"customTracking":{"startUrl":"https://tracker.example.com/start","firstQuartileURL":"https://tracker.example.com/25","midPointURL":"https://tracker.example.com/50","thirdQuartileURL":"https://tracker.example.com/75","completeURL":"https://tracker.example.com/complete","impressionURL":"https://tracker.example.com/impression"}}},"H001":{"creativeName":"Interactive HTML Ad","platformCreativeTypeId":13,"creativeSourceType":"HTML","creativeSource":"<a href=\"https://example.com\"><img src=\"https://cdn.example.com/ad.jpg\"></a>","clickUrl":"https://www.example.com","htmlDetails":{"creativeWidth":300,"creativeHeight":250}}}' \
  -F 'creativeFiles=@summer-banner.jpg' \
  -F 'creativeFiles=@product-demo.mp4'

Response 200

{
  "success": true,
  "data": {
    "successData": {
      "PS": "701388"
    },
    "failedData": {
      "PF": "Creative file missing. Please attach the required file. : null"
    }
  }
}

Step 4: Check creative status

GET

This API checks a creative's status. Use the creativeId (6 digit number under data parameter in response) retrieved from the previous step to get its details.

The creative details endpoint returns a status ID (highlighted in code sample). A status ID of 2 means the creative is running.

Path parameter
creativeId array of integers	Creative ID

JSON

Response 200

{
  "success": true,
  "data": {
    "creativeId": 686855,
    "creativeName": "300x600-w23-01",
    "rtbCreativeTypeId": 1,
    "platformCreativeTypeId": 11,
    "creativeStatusId": 2,
    "creativeSource": "https://d3jme5si7t6llb.cloudfront.net/image/202760/efk0sUk_1730201855013.jpg",
    "creativeCardSource": "https://d3jme5si7t6llb.cloudfront.net/Screenshots/202760/278x220/efk0sUk_1730201855013.jpg",
    "clickUrl": "http://iqm.com",
    "imageDetails": {
      "pixelUrl": "http://pixel.com",
      "creativeWidth": 300,
      "creativeHeight": 600
    },
    "creativeSourceType": "file",
    "creativePreviewFlag": 1,
    "createdAt": 1730201855165,
    "modifiedAt": "2024-10-29T06:10:15.000+00:00",
    "userDetails": {
      "uowId": 175891,
      "userName": "Hardik",
      "userEmail": "hardik.v+iqmsuper@iqm.com",
      "hasApprovalAccess": true,
      "hasEditAccess": true
    },
    "organizationDetails": {
      "owId": 202760,
      "organizationName": "AdWing"
    }
  }
}

TypeScript

See TypeScript Prerequisites page for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          creativeId: number;
          creativeName: string;
          rtbCreativeTypeId: number;
          platformCreativeTypeId: number;
          creativeStatusId: number;
          creativeSource: string;
          creativeCardSource: string;
          clickUrl: string;
          imageDetails: {
            pixelUrl: string;
            creativeWidth: number;
            creativeHeight: number;
          };
          creativeSourceType: string;
          creativePreviewFlag: number;
          createdAt: number;
          modifiedAt: number;
          userDetails: {
            uowId: number;
            userName: string;
            userEmail: string;
            hasApprovalAccess: boolean;
            hasEditAccess: boolean;
          };
          organizationDetails: {
            owId: number;
            organizationName: string
          }
        }
      };
    };
  };
}

function getCreative(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/crt/creatives/{creativeId}',
    params: {
      path: {
        creativeId: `number`
      }
    }
  };