Technical Reference

Data schemas, state machines, validation rules, and low-level specifications for implementing Creator Collaboration workflows.

---

API Reference Quick Links

Profile Engagement Audiences

API Documentation: Profile Engagement Audiences

Implementation Guide: Audience Targeting

---

Partnership & Role Objects

API Documentation: Partnership Roles API

Key Endpoints:

• POST /v1/public_profiles/{profile_id}/roles — Send invitation
• GET /v1/public_profiles/{profile_id}/roles/{role_id} — Check status
• GET /v1/public_profiles/{profile_id}/brand_partner_profiles — List brand partners
• GET /v1/public_profiles/{profile_id}/ad_partner_profiles — List ad partners

Implementation Guide: Partnership Setup

Critical Fields:

• partnershipLevel: BRAND_LEVEL or AD_LEVEL
• roleStatus: PENDING, ACCEPTED, EXPIRED, or DECLINED
• inviteeUserId: Creator's User ID (not username)

---

Media Objects (Collaborative)

API Documentation: Claim Media API

Key Endpoints:

• POST /v1/adaccounts/{ad_account_id}/claim_media_by_snap_reference — Claim by Snap ID
• POST /v1/adaccounts/{ad_account_id}/claim_media_by_ad_code — Claim by Ad Code
• GET /v1/media/{media_entity_id} — Check processing status

Implementation Guides:

• Brand Partnerships — Claim organic creator content
• Ad Codes — Claim content via ad codes

Critical Fields:

• media_status: PENDING_UPLOAD, READY, or ERROR
• content_source_type: ORGANIC_CONTENT for claimed media
• Poll every 5-10 seconds until READY

---

Creative Objects (Partnership-Enhanced)

API Documentation: Creatives API

Key Endpoint:

• POST /v1/adaccounts/{ad_account_id}/creatives — Create partnership ad

Implementation Guides:

• Brand Partnerships — Use BRAND_PARTNERSHIP type
• Ad Partnerships — Use AD_PARTNERSHIP type with primary_profile

Critical Fields:

• creator_partnership_type: BRAND_PARTNERSHIP or AD_PARTNERSHIP (required for disclosure)
• primary_profile: CREATOR or BRAND (for Ad Partnerships only)

---

State Machine Logic

Partnership Handshake Flow

The lifecycle of a partnership invitation.

State Transitions

From State	To State	Trigger	System Action
(none)	PENDING	Brand calls POST /roles	Push notification sent to creator
PENDING	ACCEPTED	Creator taps "Approve" in Profile Settings	Partnership becomes active
PENDING	DECLINED	Creator taps "Decline" in Profile Settings	Invitation closed
PENDING	EXPIRED	No response within invitation validity period	Invitation closed
ACCEPTED	EXPIRED	approvalTimeInDays duration completed	Active ads may pause, new ads blocked

Capabilities by State

State	Creator Can Tag Brand	Brand Can Discover Content	Brand Can Create Ads
PENDING	❌	❌	❌
ACCEPTED	✅ (BRAND_LEVEL)	✅ (BRAND_LEVEL)	✅ (AD_LEVEL only)
EXPIRED	❌	❌	❌
DECLINED	❌	❌	❌

---

Media Processing Flow

The lifecycle of transforming organic content into ad media.

Processing Details

State	System Action	Developer Action
Unclaimed	Content lives only on Creator's profile	Call claim endpoint
PENDING_UPLOAD	Async: Download → Transcode → Upload to Ad Account library	Poll GET /media/{id} every 5-10 seconds
READY	Media in Asset Library, ready for creative attachment	Proceed to POST /creatives
ERROR	Processing failed (codec issue, size limit, etc.)	Investigate error, retry or request new content

Timeout Handling

Recommended: Poll every 5-10 seconds with 60-minute max timeout.

Implementation: See Brand Partnerships - Developer Track for polling best practices

---

Content Requirements

Spotlight & Story Validation

Full Requirements: Brand Partnerships - Content Requirements

Quick Reference:

• Spotlight: 5-60 seconds, 9:16 aspect ratio, video only
• Stories: 3-180 seconds, 9:16 aspect ratio, expires in 24 hours unless saved
• Music: No Snap Library music allowed in either

Ad Code Format

Format: adcode_[UUID-string]

Validation: See Ad Codes - Developer Track

---

Utility Endpoints

Extract Snap ID from URL: GET /v1/tools/extract_snap_id — Convert Snapchat URLs to Snap IDs

Get Profile from Snap: GET /public/v1/snaps/{snap_id}/public_profile — Find which creator owns a Snap

API Documentation: Claim Media API

---

Identifying Collaborative Ads

Process:

1. Get Ad → extract creative_id
2. Get Creative → extract top_snap_media_id
3. Get Media → check content_source_type

If content_source_type is ORGANIC_CONTENT → Collaborative ad from creator's organic post

API Documentation:

• Ads API
• Creatives API
• Media API

---

ID Reference Guide

A common source of errors is confusing different ID types.

ID Type	Used For	API Context
profile_id	Public Profile identification	Roles API, creative attribution
ad_account_id	Ad Account identification	Media, Creatives, Campaigns
inviteeUserId	Creator's internal User ID	Roles API invitation
snap_id	Specific organic Snap content	Claim media endpoint input
media_entity_id	Claimed/uploaded media asset	Creative creation
segment_id	Audience segment	Ad Set targeting

Profile ID vs. Ad Account ID confusion:

• Use profile_id for Permissions (Roles API)
• Use ad_account_id for Media and Ads (Ads API)

Attempting to add a creator role using an Ad Account ID will fail.

---

Error Code Reference

Error Code / Message	Context	Root Cause	Resolution
E3003 / "Resource not found"	Invitation	Incorrect profile_id or inviteeUserId	Verify IDs via Creator Discovery endpoint
INVALID_PENDING_REVIEW_STATUS	Ad Creation	Media still processing or Creative in review	Ensure Media status is READY before use
"Permission Denied" (HTTP 403)	Roles API	OAuth token user is not Profile Admin	Ensure user has Profile Admin role
"Duplicate Role"	Invitation	Active invitation/role already exists	Check GET /roles before sending new invitation
media_entity_id not found	Ad Creation	Using Snap ID instead of Media ID	Must claim Snap ID first to get Media ID
Code expired (HTTP 404)	Ad Code	Ad code TTL elapsed or creator revoked	Request new code from creator

HTTP Status Code Patterns

Status	General Meaning	Partnership-Specific Context
200	Success	Operation completed
400	Bad Request	Invalid parameters, format errors
401	Unauthorized	Invalid or expired OAuth token
403	Forbidden	Insufficient permissions (not Profile Admin)
404	Not Found	Invalid ID, expired ad code, deleted content
409	Conflict	Duplicate role, already claimed media
429	Rate Limited	Too many requests—implement backoff
500	Server Error	Retry with exponential backoff

---

Reporting Metrics

Key Metrics for Partnership Campaigns:

• impressions — Total (organic + paid)
• paid_impressions — Paid only
• shares — Often higher on collaborative ads
• saves — High-intent engagement
• swipes — CTA engagement

Organic Impressions = impressions - paid_impressions

API Documentation: Stats & Reporting API

See Also: Brand Partnerships - Metrics & Reporting

---

Implementation Gotchas

1. No Webhooks for Approvals

The API does not send webhooks when creators accept invitations. You must poll every 5-10 minutes.

Implementation: See Partnership Setup - Developer Track for polling patterns

2. Required Partnership Type Flag

You must set creator_partnership_type in the Creative payload. Omitting this:

• Creates a generic ad without "Paid Partnership" label
• May violate FTC/advertising disclosure regulations
• Could result in ad rejection during review

Implementation:

• Brand Partnerships — Use BRAND_PARTNERSHIP
• Ad Partnerships — Use AD_PARTNERSHIP

3. Tagging vs. Paid Partnership Label

Simple @mentions in text overlays do not trigger the partnership system.

Method	Appears in shared_snaps?	Can Be Claimed?
"Paid Partnership" label	✅ Yes	✅ Yes
@mention in text overlay	❌ No	❌ No
Hashtag mention	❌ No	❌ No

Creators must use the official "Paid Partnership" tool when posting for content to be discoverable and claimable.

---

Next Steps

• Troubleshooting — Detailed FAQ and common error resolutions
• Brand Partnerships — Implementation guide for organic-to-paid flow
• Ad Partnerships — Implementation guide for paid-first flow