Create a creative

Updated:

POST/ads/{connection_id}/creative

Creates a AdsCreative. Provide the unified AdsCreative fields in the request body; they are mapped to the provider's API. Returns the created AdsCreative.

Parameters

fieldsstring array
Fields to return
rawstring
Raw parameters to include in the 3rd-party request. Encoded as a URL component. eg. raw parameters: foo=bar&zoo=bar -> raw=foo%3Dbar%26zoo%3Dbar
connection_idstring required
ID of the connection

Payload

idstring
created_atdate-time
(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atdate-time
(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
namestring
The creative's name
campaign_idstring
group_idstring
(reference to AdsGroup)
item_idstring
references Commerce Item ID (reference to CommerceItem)
organization_idstring
status enum
Valid values:
"UNSPECIFIED"
"ACTIVE"
"PAUSED"
"ARCHIVED"
"DRAFT"
creative_type enum
Valid values:
"UNSPECIFIED"
"STANDARD"
"EXPANDABLE"
"VIDEO"
"NATIVE"
hosting_source enum
Valid values:
"UNSPECIFIED"
"CM"
"THIRD_PARTY"
"HOSTED"
"RICH_MEDIA"
widthnumber
heightnumber
asset_urlsstring array
Hosted asset mode (best-effort, provider-specific
cards array
Carousel cards, in display order
link_urlstring
Destination URL for creatives with links
url_tagsstring
Appended URL tracking params (e.g. utm_source=..&utm_medium=..); Meta url_tags, Google tracking template
bodystring
titlestring
ctastring
third_party_tagstring
vast_tag_urlstring
external_creative_referencestring
external_placement_referencestring
external_ad_referencestring
promoted array
path1string
Display URL path 1 (Microsoft RSA Path1)
path2string
Display URL path 2 (Microsoft RSA Path2)
datastring
labelsstring array
metadata array

Returns

Response fieldTypeRequiredDescription
idstringNo
created_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
namestringNoThe creative's name
campaign_idstringNo
group_idstringNo(reference to AdsGroup)
item_idstringNoreferences Commerce Item ID (reference to CommerceItem)
organization_idstringNo
statusenumNoValues: UNSPECIFIED, ACTIVE, PAUSED, ARCHIVED, DRAFT, SCHEDULED_FOR_DELETION, PROCESSING, PROCESSING_FAILED
creative_typeenumNoValues: UNSPECIFIED, STANDARD, EXPANDABLE, VIDEO, NATIVE, AUDIO, PUBLISHER_HOSTED, ASSET_BASED, IMAGE, DOCUMENT, SHARE
hosting_sourceenumNoValues: UNSPECIFIED, CM, THIRD_PARTY, HOSTED, RICH_MEDIA, PUBLISHER_HOSTED
widthnumberNo
heightnumberNo
asset_urlsstring[]NoHosted asset mode (best-effort, provider-specific
cardsAdsCreativeCard[]NoCarousel cards, in display order
cards[].asset_urlstringNoSame format as asset_urls (provider asset ref or URL)
cards[].titlestringNo
cards[].descriptionstringNo
cards[].link_urlstringNo
cards[].ctastringNo
link_urlstringNoDestination URL for creatives with links
url_tagsstringNoAppended URL tracking params (e.g. utm_source=..&utm_medium=..); Meta url_tags, Google tracking template
bodystringNo
titlestringNo
ctastringNo
third_party_tagstringNo
vast_tag_urlstringNo
external_creative_referencestringNo
external_placement_referencestringNo
external_ad_referencestringNo
promotedAdsPromoted[]No
promoted[].idstringYes
promoted[].namestringNo
promoted[].typeenumYesPromoted entity types for ads_promoted list endpoint Values: PAGE_ID, APP_ID, STORE_URL, PIXEL_ID, CUSTOM_CONVERSION_ID, CATALOG_ID, PRODUCT_SET_ID, PRIORITIZED_SET_ID, EVENT_ID, OFFER_ID, LEAD_FORM_ID, MESSAGING_CHANNEL_ID, PRODUCT_ID, TWEET_ID, AD_GROUP_TYPE
promoted[].metadataAdsMetadata[]No
promoted[].metadata[].idstringNo
promoted[].metadata[].slugstringNo
promoted[].metadata[].valueobjectNo
promoted[].metadata[].namespacestringNo
promoted[].metadata[].formatenumNoValues: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
promoted[].metadata[].extra_dataobjectNo
path1stringNoDisplay URL path 1 (Microsoft RSA Path1)
path2stringNoDisplay URL path 2 (Microsoft RSA Path2)
datastringNo
labelsstring[]No
metadataAdsMetadata[]No
metadata[].idstringNo
metadata[].slugstringNo
metadata[].valueobjectNo
metadata[].namespacestringNo
metadata[].formatenumNoValues: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
metadata[].extra_dataobjectNo

Errors

Errors return the HTTP status code and a JSON body with statusCode, error (the short label) and message (a human-readable detail).

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests to unified.to API; max requests per minute: N"
}
StatusErrorMeaning
400Bad RequestThe request was malformed or failed validation.
401UnauthorizedThe connection is likely broken; re-authorize it.
403ForbiddenThe connection is missing permissions or scopes.
404Not FoundThe requested resource does not exist.
429Too Many RequestsRate limit exceeded (see the two sources below).
500Internal Server ErrorAn unexpected error occurred.
501Not ImplementedNot supported by this integration.

Errors from the underlying integration pass through: the integration's status comes back as ours (429, 401, 403, 404 or 5xx), usually with its message. When the integration's error body is unclear, Unified extracts what it can and returns a clearer message.

429 Too Many Requests

A 429 has two possible sources:

  • The integration's own rate limit, passed through.
  • Unified's workspace limit: a rolling 60 seconds, set by plan, with the message Too many requests to unified.to API; max requests per minute: N.
const options = {
  method: 'POST',
  url: 'https://api.unified.to/ads/5de520f96e439b002043d8dc/creative',
  headers: {
    authorization: 'bearer .....'
  },
  data: undefined,
  params: {
    fields: '',
    raw: '',
  }
};

const results = await axios.request(options);
Are we missing anything? Let us know
Was this page helpful?