Overview#
A creative test shows your ads, images, videos, or audio to your customers' digital twins where people would meet them, in a feed, a story, search results, a page, or an inbox, and asks how each twin reacts. You can run the same test you run from Studio > Assets > Test assets from your own code, for example right after a designer exports a file from Canva or Adobe.
You need an API key with Research write access, and an audience you have set up in Point11: a business profile and its customers. Every request below sends the key as Authorization: Bearer $POINT11_API_KEY, and every request that changes something sends a new UUID in Idempotency-Key.
Upload each creative#
Upload each picture, PDF, text, or audio file in three requests. First, reserve the upload: send the file's name, type, exact size in bytes, and SHA-256:
curl https://point11.ai/api/v1/research/study-attachments/reserve-upload-v5 \
-H "Authorization: Bearer $POINT11_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"filename": "summer-ad.png", "mediaType": "image/png", "byteLength": 482113, "sha256": "<hex sha-256>"}'Then send the file as the body of the upload request in the response, with exactly its method, URL, and headers, before it expires a minute later. Finally, finish the upload with the attachment's id and the etag the upload answered:
curl https://point11.ai/api/v1/research/study-attachments/complete-upload-v3 \
-H "Authorization: Bearer $POINT11_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"id": "<attachment id>", "etag": "<etag>"}'Images (PNG, JPEG, WebP) can be up to 3,750,000 bytes, the most one picture can carry to every AI model a twin may run on, and PDFs and audio (MP3, WAV) up to 4 MiB.
A video is converted instead, so it plays and seeks in every browser. Reserve it at /api/v1/research/study-attachment-sources/reserve with its name, type, and exact size in bytes (up to 500 MiB, no SHA-256), send the file to the upload in the response the same way, then ask for its conversion with the source's id:
curl https://point11.ai/api/v1/research/study-attachment-sources/convert \
-H "Authorization: Bearer $POINT11_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"id": "<source id>", "filename": "summer-ad.mp4"}'The response names the video's own id. Point11 converts it into an MP4 of up to 3 minutes, and twins see it as timed frames and its transcript, so wait until GET /api/v1/research/study-attachments-v2/{id} shows it ready with its storyboard ready.
Start the test#
Name what the test shows (the uploaded files and where each one runs), what you want to learn, the audience, and how twins should meet the creative:
curl https://point11.ai/api/v1/research/creative-tests/start-v7 \
-H "Authorization: Bearer $POINT11_API_KEY" \
-H "Idempotency-Key: $TEST_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Summer ads",
"brief": "Which ad makes people want to book a visit, and why?",
"objectives": ["conversion"],
"sellerProfileId": null,
"contentLanguage": "en",
"audience": {
"audienceProfileId": "<business profile id>",
"targetedGroupIds": null,
"targetedCustomerIds": null,
"targetInterviewCount": 50
},
"studyMode": {"kind": "first_impressions"},
"exposure": {
"kind": "single",
"options": [
{
"attachment": {"artifactId": "<attachment id>", "filename": "summer-ad.png", "mediaType": "image/png", "byteLength": 482113},
"placement": {"platform": "Instagram", "format": "Feed image", "unit": "feed", "medium": "image"}
}
],
"yardstick": {"kind": "no_ad"}
}
}'- Audience.
audienceProfileIdis your business profile's id fromGET /api/v1/business/profiles. LeavetargetedGroupIdsempty to draw from all its customers, or name up to 20 saved audiences. - First impressions or a buying situation.
first_impressionsshows the creative to each twin as they are.buying_scenariowith adirectionfirst places each twin in the buying situation you describe. - What the test shows. A
singletest compares 1 to 3 options in one placement (the same platform, format, and unit) with no ad, or with the ad you run today ({"kind": "current_ad", "attachment": ...}). Theunitsays how people meet the ad, for examplefeed,story,search, ordisplay-banner. To test ads in different placements, test each placement on its own, or send asequence: 1 to 5 ads in the order people meet them, each with its own placement and the time before it (gapBefore). A sequence can end on a landing page: capture it withPOST /api/v1/research/study-attachments/import-pageand pass what it returns aspage, with thedeviceit is shown on. - Objectives. Choose what the test asks with
objectives: one to three of the marketing funnel's stages, each once and in this order.awarenessasks whether people pick out your brand among its rivals after your ad, and what the ad told them.considerationasks how they feel about your brand, whether they would consider it, and why.conversionasks whether they would engage with each ad and take the action it asks for, such as booking a demo, signing up, or buying, and why. Leaveobjectivesout and Point11 chooses them from your brief. With awareness or consideration, each ad is shown to its own group of twins, beside a group that sees neutral content in its place. A test that ends on a landing page runs conversion alone.
The test answers 202 at once. Keep the Idempotency-Key you sent: it names the test from now on.
Earlier versions keep working through April 25, 2027: start-v4 takes track instead of objectives (performance runs conversion, brand runs awareness and consideration), and creative-tests-v5, launch-v3, and results-v8 read a test by its track when its objectives match one. Move to the versions on this page before then.
Follow the test#
While Point11 reads your creative, prepares the twins, and writes the study, read the test by that key:
curl https://point11.ai/api/v1/research/creative-tests-v7/$TEST_KEY \
-H "Authorization: Bearer $POINT11_API_KEY"status is preparing, then awaiting_approval, failed, or unsupported, and phase says how far it has got. Only the key that started a test can read it this way.
Launch the interviews#
Nothing is interviewed until you launch the test. Once it is awaiting_approval, objectives are the ones you named or Point11 chose, brief what it read from your creative (your brand, its category, and its competitors), and design the study it wrote: its questions, each naming the ad it asks about, and a message about them. To test other objectives, start a new test that names them, with a new Idempotency-Key; preparing it again uses Alpha credits. Review it, then launch it with the test's key as id and the reviewedDigest the read answered:
curl https://point11.ai/api/v1/research/creative-tests/launch-v6 \
-H "Authorization: Bearer $POINT11_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"id": "<test key>", "reviewedDigest": "<reviewedDigest>"}'To launch an edited study or brief, send it as study or brief. The launch first draws each ad where people meet it, among neutral posts or results; if it can't draw them right now it answers 503, so send the same launch again after the Retry-After seconds. The test then reads launched, and campaignId and runId name its interviews and results. Only the key that started a test can launch it.
The interviews take longer, so instead of reading every test, read your organization's activity revision every 30 to 60 seconds. It changes when any study finishes or its results publish, so one request covers all your tests:
curl https://point11.ai/api/v1/campaigns/activity-revisions/organization \
-H "Authorization: Bearer $POINT11_API_KEY"When products.research changes, read the results.
Read the scorecard#
curl "https://point11.ai/api/v1/research/results-v10/$CAMPAIGN_ID?runId=$RUN_ID" \
-H "Authorization: Bearer $POINT11_API_KEY"The results give each question's answers, a summary with quotes, how many interviews finished, and the scorecard, with one section for each objective the test asked, in funnel order:
- Awareness: how many twins noticed your brand, and what your ad told them.
- Consideration: how many feel good about your brand and would consider it, and why.
- Conversion: how many twins engaged with each ad and went on to take its action, such as booking a demo, signing up, or buying, and why.
Awareness and consideration compare the twins who saw each ad with those who saw neutral content instead, so you see what the ad changed. Conversion compares each ad with the one you run today, or, with no ad, the options with each other. Each share comes with its 95% range, and the scorecard leaves the verdict to you. Results are simulated research with your customers' digital twins, not measured clicks, sales, or conversion.
Costs and limits#
- A creative test is billed like any Research study: each delivered interview counts toward your plan at the Research interview price, and reading the creative and preparing the twins use Alpha credits at their exact cost.
- Each key has 100 requests a minute across the API and the MCP server. A key can start about 6 tests a minute, and upload 128 files a minute and 300 a day. When a budget runs out you get
429; wait theRetry-Afterseconds. - To retry a request safely, send it again with the same
Idempotency-Key. Retrying a start gives you the same test back, and nothing is charged twice.