Snapchat API

Connect an authorized Snapchat Public Profile and publish Saved Stories or Spotlight submissions.

Current RelayAPI capability

Property	RelayAPI behavior
Platform key	`snapchat`
Connection	OAuth 2.0 with `snapchat-profile-api`, followed by Public Profile selection
Provider access	Snapchat Public Profile API; the OAuth client must be allowlisted by Snapchat
Published types	Saved Story and Spotlight
Story	Not currently supported; RelayAPI cannot correlate a Story create request to a terminal provider result
Media	Exactly one image or video; Spotlight requires video
Scheduling	Yes, through RelayAPI
Native analytics endpoints	Not currently implemented

This integration is for a Snapchat Public Profile, not an ordinary personal identity or the Snapchat Ads API. Create the OAuth app in Snap Business Manager, request Public Profile API allowlisting for its client ID, and select a profile returned by the authorized my_profile endpoint.

Connect a Public Profile

Start OAuth with GET /v1/connect/snapchat. Snapchat returns only the Public Profiles the authorizing user can access. The callback produces a connect_token; list and select one of those profiles:

curl --get https://api.relayapi.dev/v1/connect/snapchat/profiles \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  --data-urlencode "connect_token=$CONNECT_TOKEN"

curl -X POST https://api.relayapi.dev/v1/connect/snapchat/profiles \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connect_token": "operation-token",
    "profile_id": "authorized-public-profile-id"
  }'

RelayAPI stores the selected Public Profile ID as the account identity and records an internal verification marker that generic metadata updates cannot forge. A publish request cannot redirect that profile token to another profile.

Every Snapchat account created before this Public Profile verification marker was introduced must reconnect. Legacy Marketing API organization/account identities and unmarked records fail publishing and reconciliation with SNAPCHAT_RECONNECT_REQUIRED; RelayAPI does not guess that they represent a Public Profile.

Publish a Saved Story

Use the connected account ID to select one exact Public Profile:

curl -X POST https://api.relayapi.dev/v1/posts \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: snapchat-saved-story-20260809" \
  -d '{
    "content": "Behind the scenes",
    "targets": ["acc_snapchat_example"],
    "media": [
      {"url": "https://cdn.example.com/story.jpg", "type": "image"}
    ],
    "scheduled_at": "now",
    "target_options": {
      "snapchat": {"content_type": "saved_story"}
    }
  }'

The broader snapchat target selector is also valid, but it expands to every authorized Snapchat account in the post's workspace boundary. In either case, each resolved account publishes only to its selected Public Profile.

Saved Story titles are limited to 45 characters. RelayAPI reports success only when Snapchat returns a successful sub-request and a Saved Story ID.

Submit a Spotlight

{
  "content": "Launch day #new",
  "targets": ["acc_snapchat_example"],
  "media": [
    {"url": "https://cdn.example.com/spotlight.mp4", "type": "video"}
  ],
  "scheduled_at": "now",
  "target_options": {
    "snapchat": {
      "content_type": "spotlight",
      "locale": "en_US"
    }
  }
}

Spotlight descriptions are limited to 160 characters. A successful submission is initially pending_review, not proof that the Spotlight is live. RelayAPI retains Snapchat's request and Spotlight IDs and can reconcile the Spotlight to published, pending_review, or failed when Snapchat exposes its status.

`target_options.snapchat`

Field	Type	Required	Behavior
`content_type`	`saved_story` or `spotlight`	Yes	Required typed publish surface. Generic Stories are not accepted by the public request schema.
`locale`	string	Spotlight only, optional	Defaults to `en_US`
`content`	string	No	Snapchat-specific content/title override
`media`	array	No	Snapchat-specific media override; exactly one item

Media and outcomes

RelayAPI downloads the source through its public-URL safety checks, encrypts the bytes as required by Snapchat, uploads bounded parts, and finalizes the media before creating content. Managed RelayAPI media accepts direct-to-storage upload sessions up to 200 MiB, while the Worker-proxy endpoint remains 50 MiB; Snapchat can still reject an asset for its current codec, dimensions, duration, orientation, or content policy.

Do not automatically retry an ambiguous creation with a new idempotency key. Saved Story creation has no correlation-safe status lookup after an ambiguous response, while Spotlight reconciliation requires the IDs returned by Snapchat.

Common errors

Code	Meaning
`CONTENT_TYPE_REQUIRED`	Dry-run validation did not receive `saved_story` or `spotlight`
`SNAPCHAT_STORY_UNSUPPORTED`	A legacy/untyped caller reached the publisher without a supported surface; generic Story remains disabled
`MEDIA_REQUIRED` / `TOO_MANY_MEDIA`	The request did not contain exactly one media item
`VIDEO_REQUIRED`	Spotlight media was not marked as video
`TITLE_TOO_LONG`	Saved Story title exceeded 45 characters
`DESCRIPTION_TOO_LONG`	Spotlight description exceeded 160 characters
`PROFILE_ID_MISMATCH`	A compatibility field attempted to target a profile other than the connected one
`SNAPCHAT_RECONNECT_REQUIRED`	The account predates connector-verified Public Profile identity; reconnect before publishing or reconciliation

Official Snapchat references

Found something wrong? Help us improve this page.

Report an issue Edit this page on GitHub

Snapchat API

On this page