Lookup Creatives

Resolve creatives by either handle: the campaign a name ran in, or the names a campaign covers. Both directions of what POST /creatives/launched and POST /packs/launched recorded.

A POST because it reads a batch — up to 500 names and 500 campaign ids per call, more than a URL holds, and the ad_id half costs one query per call rather than one per id.

Rows come back in the order asked, names first and campaign ids after, one row per handle naming what it resolved to. Never a 404: a handle nothing carries gets an empty creatives in its own row, and 422 stays for what the client got wrong — a blank handle, a batch over the cap, a body naming neither list.

The packs are read once for the whole batch, not per row: they carry varied_elements, which no creative has a field for, and they are what a card minted before the rollup falls back to. The task owner and assignee are resolved the same way, one read of the user directory per batch.

POST/api/v1/integrations/creative-tests/creatives/lookup

Authorization

AuthorizationBearer token · headerrequired

Static token issued to an integrating platform (INTEGRATIONS__TOKENS)

Request body

requiredapplication/json

namesstring[]

canonical Kumquat creative names

max items 500

ad_idsstring[]

campaign ids as the ad account knows them

max items 500

Responses

200Successful Response

Array of CreativeLookupResult

querystringrequired

handleLookupHandlerequired

Which of a creative's two handles a lookup row was asked by.

Allowed:namead_id

creativesKumquatCreativeRef[]

Show properties

Array of KumquatCreativeRef

idstringrequired

namestringrequired

ad_idstring | any

Show properties

Any of:

string

string

any

any

localeLanguage | any

Show properties

Any of:

Language

string

any

any

geoGeo | any

Show properties

Any of:

Geo

string

any

any

subjectstring | any

Show properties

Any of:

string

string

any

any

topicstring | any

Show properties

Any of:

string

string

any

any

subtopicsstring[]

primary_anchorPrimaryAnchor | any

Show properties

Any of:

PrimaryAnchor

string

any

any

audiencestring | any

Show properties

Any of:

string

string

any

any

awareness_stageAwarenessStage | any

Show properties

Any of:

AwarenessStage

string

any

any

messaging_angleMessagingAngle | any

Show properties

Any of:

MessagingAngle

string

any

any

hook_triggerHookTrigger | any

Show properties

Any of:

HookTrigger

string

any

any

hook_typeHookType | any

Show properties

Any of:

HookType

string

any

any

ad_formatAdFormat | any

Show properties

Any of:

AdFormat

string

any

any

tagsstring[]

traffic_flowTrafficFlow | any

Show properties

Any of:

TrafficFlow

string

any

any

landingany

Show properties

Any of:

any

any

any

any

funnelany

Show properties

Any of:

any

any

any

any

cppany

Show properties

Any of:

any

any

any

any

varied_elementsVariedElement[]

task_ownerKumquatPerson | any

Show properties

Any of:

KumquatPerson

namestring | any

Show properties

Any of:

string

string

any

any

initialsstring | any

Show properties

Any of:

string

string

any

any

any

any

assigneeKumquatPerson | any

Show properties

Any of:

KumquatPerson

namestring | any

Show properties

Any of:

string

string

any

any

initialsstring | any

Show properties

Any of:

string

string

any

any

any

any

created_atstring<date-time>required

422Validation Error

detailValidationError[]

Show properties

Array of ValidationError

locstring | integer[]required

Show properties

Array of string | integer

Any of:

string

string

integer

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Request

curl -X POST "/api/v1/integrations/creative-tests/creatives/lookup" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "names": [
    "string"
  ],
  "ad_ids": [
    "string"
  ]
}'

const response = await fetch("/api/v1/integrations/creative-tests/creatives/lookup", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "names": [
    "string"
  ],
  "ad_ids": [
    "string"
  ]
})
});

import requests

response = requests.post(
    "/api/v1/integrations/creative-tests/creatives/lookup",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "names": [
    "string"
  ],
  "ad_ids": [
    "string"
  ]
},
)

Response

[
  {
    "query": "string",
    "handle": "name",
    "creatives": [
      {
        "id": "string",
        "name": "string",
        "ad_id": "string",
        "locale": "EN",
        "geo": "US",
        "subject": "string",
        "topic": "string",
        "subtopics": [
          "string"
        ],
        "primary_anchor": "pain_led",
        "audience": "string",
        "awareness_stage": "unaware",
        "messaging_angle": "pattern_interrupt",
        "hook_trigger": "pattern_interrupt",
        "hook_type": "pattern_interrupt",
        "ad_format": "animation",
        "tags": [
          "string"
        ],
        "traffic_flow": "W2A",
        "landing": {},
        "funnel": {},
        "cpp": {},
        "varied_elements": [
          "hook"
        ],
        "task_owner": {
          "name": "string",
          "initials": "string"
        },
        "assignee": {
          "name": "string",
          "initials": "string"
        },
        "created_at": "2019-08-24T14:15:22Z"
      }
    ]
  }
]