Claim Media

Users can claim media to associate organic content with ad accounts. Once claimed, this content can be used to create ads.

Generally, the steps are:

1. Claim the media by ad code or Snap Id.
2. Check the media status, and wait for media_status to become READY.
3. Create an ad using the claimed media.

Utility endpoints:

• Extract Snap ID — Convert a Snapchat URL to a Snap ID
• Combine Snaps — Merge multi-segment Stories into a single media asset

Claim media by ad code allows callers to claim any media, whereas Claim media by Snap Id allows callers to claim only Snaps to which they have access.

Claim media by ad code

Ad codes allow creators and advertisers to easily collaborate on paid partnerships content at a post level. An ad code is generated when a creator creates a piece of content on Snapchat. When this ad code is shared with an advertiser, the advertiser can then use this code to check the status of the media/content. If the content is ready, the advertiser can use it to set up a creative.

Using the Snapchat app Ad Codes can be set up by any Creator. There is no requirement to be allowlisted. Learn more at how Ad Codes are set up by Creators.

Parameters

Parameter	Required	Data Type	Description
ad_code	Yes	String	The ad code shared by the creators
profile_id	Yes	String	The profile id of advertiser/brand

Request

POST

https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/claim_media_by_ad_code

Response

{
  "request_status": "SUCCESS",
  "request_id": "d8943beb-7c3c-4522-8d4e-df7b8f0dbca9",
  "media_entity_id": "d645bac7-e310-4fb2-8481-98842d254a75",
  "error_messages": {}
}

Claim media by Snap Id

We also allow users to Promote a Snap in-app and in Profile Manager. Snap Promote uses the claim_media_by_snap_reference endpoint, which API clients can use to similar effect.

Request

POST

https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/claim_media_by_snap_reference?snap_id={snap_id}

where snap_id is the Snapʼs id, e.g., W7_EDlXWTBiXAEEniNoMPwAAYZXJwdnd1YWloAYu1RnTVAYu1RnRGAAAAAQ.

Callers must have permissions to both the target ad account and Snap (i.e., callers must have access to the Snapʼs profile).

Response

{
  "request_status": "SUCCESS",
  "request_id": "61515daf-5bc9-4487-8ca3-f8bc8d437502",
  "media_entity_id": "c7f9387a-bae0-4ea4-84ba-0204b30a778e"
}

Check media status

Use the media_entity_id received in the claim media step to verify its readiness.

Request

GET

https://adsapi.snapchat.com/v1/media/{media_id}

Response

{
  "request_status": "SUCCESS",
  "request_id": "2aa5fdca-6087-457a-aa62-23c3bb89b3f5",
  "media": [
    {
      "sub_request_status": "SUCCESS",
      "media": {
        "id": "d645bac7-e310-4fb2-8481-98842d254a75",
        "updated_at": "2024-08-08T20:31:46.268Z",
        "created_at": "2024-08-08T20:31:40.777Z",
        "ad_account_id": "19500815-b276-466a-8a4c-f890554ac1b3",
        "type": "VIDEO",
        "media_status": "READY",
        "download_link": "…",
        "target_business_profile_id": "73329e8b-108e-4a33-9218-183bbbeaa452",
        …
      }
    }
  ]
}

"media_status": "READY" means the media is ready to be used for ad creation. Otherwise, it will show "PENDING_UPLOAD".

Create ad

Use the media_id as the top_snap_media_id to set up a Creative that shows the creator’s profile.

Parameters

Parameter	Required	Data Type	Description
top_snap_media_id	Yes	String	The media_id acquired from previous steps
creator_profile_properties	No	String	The profile id of the creator of the snap, if left null, creative will show brand’s profile
profile_tagged_in_headline	No	String	To get the brand tagged, add this parameter with brand’s profile id

For comprehensive list of all parameters needed to create an ad from a creative, please refer to our Create a Snap Ad documentation.

Request

POST

https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives

Response

{
  "request_status": "success",
  "request_id": "526ddba9-f082-4ea8-a93d-c313badcd5fb",
  "creatives": [
    {
      "sub_request_status": "success",
      "creative": {
        "id": "c1e6e929-acec-466f-b023-852b8cacc18f",
        "updated_at": "2016-08-14T06:45:04.300Z",
        "created_at": "2016-08-14T06:45:04.300Z",
        "name": "Creative Creative",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "SNAP_AD",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE"
      }
    }
  ]
}

Extract Snap ID

If a creator shares a Snapchat URL or short link instead of a snap_id, use this utility endpoint to extract the ID before claiming.

Parameters

Parameter	Required	Data Type	Description
url	Yes (if no code)	String	Full Snapchat URL (e.g., snapchat.com/spotlight/...)
short_url_code	Yes (if no URL)	String	Short code only (e.g., iR7tFNNh from t.snapchat.com/iR7tFNNh)

Request

GET

https://adsapi.snapchat.com/v1/tools/extract_snap_id?short_url_code={code}

or

GET

https://adsapi.snapchat.com/v1/tools/extract_snap_id?url={full_url}

Response

{
  "request_status": "SUCCESS",
  "request_id": "c5d0792e-ef39-4e06-b476-f8bdc3fe34cd",
  "snap_id": "W7_EDlXWTBiXAEEniNoMPwAAYZmVreG1udXpiAY5g4L4iAY5g4FROAAAAAQ"
}

Creators can share content URLs from the Snapchat app:

• Regular URL: Tap the three-dot icon → "Copy Link"
• Short URL: Tap the share icon → "Copy" (produces t.snapchat.com/CODE)

Both formats are supported by this endpoint.

Combine Snaps

When creator content spans multiple Snaps (common for Stories longer than 10 seconds), use this endpoint to combine them into a single ad-ready video asset.

Parameters

Parameter	Required	Data Type	Description
snap_ids	Yes	Array[String]	Array of Snap IDs to combine (in desired playback order)
tagged_profile_id	Yes	String	Profile ID of the brand tagged in the content OR the content creator

Request

POST

https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/combine_snaps?tagged_profile_id={profile_id}&snap_ids={snap_id_1}&snap_ids={snap_id_2}

Response

{
  "request_status": "SUCCESS",
  "request_id": "e4105591-61b4-42be-93d9-9ecea35c9bfd",
  "media_entity_id": "f64bc1e1-bf4d-4280-b801-a46cb3138940"
}

• You only need to provide one Snap ID per bundle—the API automatically fetches related Snaps from the same longform content
• All Snaps must have the same resolution
• The returned media_entity_id requires the same status check as claimed media
• Processing time varies by total video length; if not ready after 60 minutes, retry