Profile Asset Management
An important aspect of working with creators and businesses involves asset management. We will go over the different types of assets and the actions that can be performed on them.
Media
Media is owned by the public profile and can be used to post stories and spotlights.
Uploading a media involves these steps:
- Encrypt the media file to be used for media upload
- If the file is larger than 32MB then split it into smaller chunks
- Create a container media object using the Create Media API.
- Use the media_id returned from the above API to upload a media file using the multipart upload API. Note : If the media is being created for story posting then the uploaded file should adhere to the constraints listed in the story posting section.
Encrypt and split file
- First encrypt the file as shown in the sample
$ key=`openssl rand -hex 32`
# generate random iv of 16 bytes
$ iv=`openssl rand -hex 16`
# encrypt the media file using the generated key and iv
$ openssl enc -aes-256-cbc -nosalt -e \
-in video.mp4 -out video.enc.mp4 \
-K $key -iv $iv
- If your file is larger than 32 MB, split the file into chunks
split -b 32m video.mp4 video.mp4
Create Media
A media object is a container for a single video or image which can later be used for story posting. The media object is owned by the public profile. A media object stays active for 24 hours after creation and can be used for story posting until then.
To create the Media container, first base64 encode the encryption Key and IV used in the previous step and then make the API call to the media upload endpoint.
HTTP Request
POST https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/media
Parameters
Field name | Required | Description | Possible Values | |
---|---|---|---|---|
type | R | Type of media. | VIDEO, IMAGE | |
name | R | Human readable name for the media | ||
key | R | 32 byte key with which the media is encrypted. Should be base64 encoded. | ||
iv | R | 16 byte Initial vector used to encrypt the media. Should be base64 encoded. |
HTTP Response
Name | Description | Possible Values | ||
---|---|---|---|---|
request_id | A UUID to identify this request. | |||
request_status | SUCCESS / ERROR | |||
media_id | Media id which can be used for uploading the media. | |||
debug_message | A debug message to help debug if there is an error | |||
display_message | Display message if there is an error. | |||
error_code | Error code if there is an error |
Example
Provide the base64 encoding of the key and iv which was used to encrypt the file in this request.
To encode the key and iv to base64 this can be used :
# encode the 32 byte hexadecimal key to base64
$ key64=`echo $key | xxd -r -p | base64`
# encode the 16 byte hexadecimal iv to base64
$ iv64=`echo $iv | xxd -r -p | base64`
curl --request POST 'https://businessapi.snapchat.com/v1/public_profiles/62d2298b-925b-4953-9cb0-b3a492d51d0c/media'\
--header 'Authorization: <ACCESS_TOKEN>'\
--data-raw "{ \"type\":\"VIDEO\", \"name\":\"my-video\", \"key\":\"${key64}\", \"iv\": \"${iv64}\" }"
Response
{
"request_id": "ecfe244d-0b1b-4787-9919-4ee7dd275a0a",
"request_status": "SUCCESS",
"media_id": "abed133c-0b1b-3676-8808-3dd6cc164909",
"add_path": "/us/v1/public_profiles/62d2298b-925b-4953-9cb0-b3a492d51d0c/media/abed133c-0b1b-3676-8808-3dd6cc164909/multipart-upload",
"finalize_path": "/us/v1/public_profiles/62d2298b-925b-4953-9cb0-b3a492d51d0c/media/abed133c-0b1b-3676-8808-3dd6cc164909/multipart-upload"
}
Multipart Upload
After a media object has been created, use the add_path url provided in the response to upload the media file.
- If the file is larger than 32 MB, first split it into chunks of upto 32 MB.
- A file of upto 1 GB can be uploaded through the multipart upload API.
- Use the add_path and ADD action to upload a file chunk. Multiple chunks can be uploaded in parallel.
- Once all chunks have been uploaded, use the finalize_path and the FINALIZE action to indicate the file has been completely uploaded.
Note : If the file is being uploaded for story posting then it should adhere to the constraints listed in the story posting section.
HTTP Request - ADD
POST https://businessapi.snapchat.com/{add_path}
Parameters
Field name | Required | Description | Possible Values | |
---|---|---|---|---|
action | R | ADD | ||
file | R | The file part to upload | ||
part_number | R | File part number, used during reassembly of file | Can be between 1 to 35 |
HTTP Request - FINALIZE
POST https://businessapi.snapchat.com/{finalize_path}
Parameters
Field name | Required | Description | Possible Values | |
---|---|---|---|---|
action | FINALIZE |
HTTP Response ADD & FINALIZE
Name | Description | Possible Values | ||
---|---|---|---|---|
request_id | A UUID to identify this request. | |||
request_status | SUCCESS / ERROR | |||
debug_message | A debug message to help debug if there is an error | |||
display_message | Display message if there is an error. | |||
error_code | Error code if there is an error |
Example for ADD
curl --request POST 'https://businessapi.snapchat.com/us/v1/public_profiles/62d2298b-925b-4953-9cb0-b3a492d51d0c/media/123c1688-3725-452e-ade2-d89645cd2486/multipart-upload' \
--header 'Authorization: <ACCESS_TOKEN>' \
--header 'Content-Type: multipart/form-data' \
--form 'action="ADD"' \
--form 'file=@"video.enc.mp4aa"' \
--form 'part_number="1"'
{
"request_id": "47ed85dd-0ca7-449e-94a0-d48486fcc56e",
"request_status": "SUCCESS",
}
curl --request POST 'https://businessapi.snapchat.com/us/v1/public_profiles/62d2298b-925b-4953-9cb0-b3a492d51d0c/media/123c1688-3725-452e-ade2-d89645cd2486/multipart-upload' \
--header 'Authorization: <ACCESS_TOKEN>' \
--header 'Content-Type: multipart/form-data' \
--form 'action="ADD"' \
--form 'file=@"video.enc.mp4ab"' \
--form 'part_number="2"'
Response
{
"request_id": "47ed85dd-0ca7-449e-94a0-d48486fcc56e",
"request_status": "SUCCESS",
}
Example for FINALIZE
curl --request POST 'https://businessapi.snapchat.com/us/v1/public_profiles/62d2298b-925b-4953-9cb0-b3a492d51d0c/media/123c1688-3725-452e-ade2-d89645cd2486/multipart-upload' \
--header 'Content-Type: multipart/form-data' \
--form 'action="FINALIZE"' \
--header 'Authorization: <ACCESS_TOKEN>'
Response
{
"request_id": "ef9f6253-0c07-4c1d-8779-de4281bde83a",
"request_status": "SUCCESS",
}
Stories
Stories can be retrieved in batch, by profile ID. Snaps contained in stories can be retrieved by the Story ID.
Get Story by Profile ID
This endpoint retrieves all Stories for a given profile.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/stories
Parameters
Parameter | Required | Description | Possible Values | |
---|---|---|---|---|
profile_id | Yes | the profile id in the url path | UUID | |
limit | No | Pagination limit size of returned stories. If not specified, default is 10 | Integers that is bigger than 0 | |
cursor | No | Pagination encoded cursor for next page of stories. Default is empty |
HTTP Response
Field | Description | Possible Values | ||
---|---|---|---|---|
request_id | UUID of the request | UUID | ||
request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
stories | List of sub responses which contains Stories | Refer to the Story table below | ||
paging | Next page information if exists | |||
debug_message | Debug information string if request_status is ERROR or Partial | |||
display_message | Display information string if request_status is ERROR or Partial | |||
error_code | Error code string if request_status is ERROR or Partial |
Stories
Field | Description | Possible Values | ||
---|---|---|---|---|
sub_request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
story | Story metadata object | |||
sub_request_error_reason | Error reason string if sub_request_status is ERROR or Partial |
Story
Field | Description | Possible Values | ||
---|---|---|---|---|
id | UUID of the story | |||
profile_id | UUID of the profile the story belongs to | |||
thumbnail_url | Unencrypted thumbnail url to render the story | |||
created_at | Creation timestamp | |||
ended_at | Ended timestamp | |||
type | Story type | PUBLIC_STORY |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/stories?limit=10&cursor=xxxx"
-H "Authorization: <ACCESS_TOKEN>"
Response
{
"request_id": "0efe011f-4f91-409b-8329-987d29769c40",
"request_status": "SUCCESS",
"stories": [
{
"sub_request_status": "SUCCESS",
"story":
{
"id": "1ea5a405-85b7-40f0-bcc5-148a29d142c2",
"profile_id": "76da494b-76bc-4bbb-bb27-c5a66fb0d1ab",
"thumbnail_url": "https://cf-st.sc-cdn.net/d/nOyACxG8CUS7VOKjUqSL1.410.IRZXSOY?uc=12",
"created_at": "2021-03-05T02:33:39.240Z",
"type": "PUBLIC_STORY",
"ended_at": "2021-03-05T12:37:00.210Z",
}
}],
"paging":
{
"next_page_id": "ImV5SlFjbTltYVd4bFNVUWlPaUkzTm1SaE5EazBZaTAzTm1KakxUUmlZbUl0WW1JeU55MWpOV0UyTm1aaU1HUXhZV0lpTENKSWFXZG9iR2xuYUhSSlJDSTZJakZsWVRWaE5EQTFMVGcxWWpjdE5EQm1NQzFpWTJNMUxURTBPR0V5T1dReE5ESmpNaUlzSWs5eVpHVnlhVzVuSWpveE5qRTBPVEV4TmpFNU1qUXdMQ0pUYjNWeVkyVlBjbVJsY21sdVp5STZJaUo5Ig",
"next_link": "https://businessapi.snapchat.com/v1/public_profiles/76da494b-76bc-4bbb-bb27-c5a66fb0d1ab/stories%3Flimit=1?limit=1&cursor=ImV5SlFjbTltYVd4bFNVUWlPaUkzTm1SaE5EazBZaTAzTm1KakxUUmlZbUl0WW1JeU55MWpOV0UyTm1aaU1HUXhZV0lpTENKSWFXZG9iR2xuYUhSSlJDSTZJakZsWVRWaE5EQTFMVGcxWWpjdE5EQm1NQzFpWTJNMUxURTBPR0V5T1dReE5ESmpNaUlzSWs5eVpHVnlhVzVuSWpveE5qRTBPVEV4TmpFNU1qUXdMQ0pUYjNWeVkyVlBjbVJsY21sdVp5STZJaUo5Ig"
}
}
Get Snaps by Story ID
This endpoint retrieves Snaps by the Story ID.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/{profile_id}/stories/{story_id}/snaps
Parameters
Parameter | Required | Description | Possible Values | |
---|---|---|---|---|
profile_id | Yes | the profile id in the url path | UUID | |
story _id | Yes | the story id in the url path | UUID | |
limit | No | Pagination limit size of returned snaps. If not specified, default is 10 | Integer that is bigger than 0 | |
cursor | No | Pagination encoded cursor for next page of snaps. Default is empty | ||
created_at | No | Created timestamp of the story | Format of UTC like 2021-03-05T02:33:39.240Z | |
ended_at | No | Ended timestamp of the story | ended_at should be within 24hr range of PST if created_at is provided |
HTTP Response
Field | Description | Possible Values | ||
---|---|---|---|---|
request_id | UUID of the request | UUID | ||
request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
snaps | List of sub responses which contains Snaps | Refer to the Snaps table below | ||
paging | Next page information if exists | |||
debug_message | Debug information string if request_status is ERROR or Partial | |||
display_message | Display information string if request_status is ERROR or Partial | |||
error_code | Error code string if request_status is ERROR or Partial |
Snaps
Field | Description | Possible Values | ||
---|---|---|---|---|
sub_request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
snap | Snap metadata object | |||
sub_request_error_reason | Error reason string if sub_request_status is ERROR or Partial |
Snap
Field | Description | Possible Values | ||
---|---|---|---|---|
id | Unique id of the snap | |||
story_id | UUID of the story the snap belongs to | |||
media_metadata | Unencrypted thumbnail url to render the snaps | |||
created_at | Creation timestamp | |||
caption | Comma separated captions on story. Contains all hashtags and mentions | |||
ml_tags | Machine Learning generated tags on creator content e.g. brand names |
Media Metadata
Field | Description | Possible Values | ||
---|---|---|---|---|
media_type | Media type | MEDIA_TYPE_IMAGE MEDIA_TYPE_VIDEO | ||
media_url | Unencrypted media downloadable url | |||
thumbnail_url | Unencrypted thumbnail url of the snap |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/stories/{id}/snaps?limit=10&cursor=xxxx"
-H "Authorization: <ACCESS_TOKEN>"
Response
{
"request_id": "937e5df1-1db9-477c-8fb4-14ed043e9f44",
"request_status": "SUCCESS",
"snaps": [
{
"sub_request_status": "SUCCESS",
"snap":
{
"id": "4i3kH1nyTcOe9Mww1VgV3wAAgIDQZpWjQNxJ-AXrGLQFTAXrGLP78_____w",
"story_id": "1a24e9dc-dfd2-5e00-871c-9c76ce2b4ac1",
"media_metadata":
{
"media_type": "MEDIA_TYPE_VIDEO",
"media_url": "https://cf-st.sc-cdn.net/d/8Yb8LJ5TWb2yVMSTuF6dg.10.IRZXSOY?mo=GloaChoAGgBIAlAwYAGiATQIChIeChwgAUoYChMmBQUIBQUFBQUFBgUFBAUEBQQFEPQDIhAKAzIBBBIAKgdJUlpYU09ZogEUCAEiEAoOMgEBOgEEQgYI5q7dhwY%3D&uc=48",
"thumbnail_url": "https://s.sc-cdn.net/indef/XwzrXTb45Xf1MCogDC6GI8cYmmv-yKC_b889fj30vFE=/default/thumb/thumb.jpg"
},
"created_at": "2021-07-20T23:07:55.516Z",
"caption": "Caption for this story",
"ml_tags": [
"blue lighting",
"turquoise",
"fabric",
"lighting effects",
"wet",
"colorful lights",
"water",
"bottle",
"gemstones"
]
}
},
{
"sub_request_status": "SUCCESS",
"snap":
{
"id": "4i3kH1nyTcOe9Mww1VgV3wAAg8_ITAOOBJ-7bAXrGLSyMAXrGLSrY_____w",
"story_id": "1a24e9dc-dfd2-5e00-871c-9c76ce2b4ac1",
"media_metadata":
{
"media_type": "MEDIA_TYPE_IMAGE",
"media_url": "https://cf-st.sc-cdn.net/d/bxp6AbXJcodM0bmJAPEGC.400.IRZXSOY?mo=GjsaChoAGgBIAlAwYAGiARUIkAMiEAoDMgEEEgAqB0lSWlhTT1miARQIASIQCg4yAQE6AQRCBgjyrt2HBg%3D%3D&uc=48",
"thumbnail_url": "https://s.sc-cdn.net/indef/wzfqb3GkwDA9Hj9EEWujDQon_2TOw-y7471O39dp3BE=/default/thumb/thumb.jpg"
},
"created_at": "2021-07-20T23:08:06.744Z"
}
},
{
"sub_request_status": "SUCCESS",
"snap":
{
"id": "4i3kH1nyTcOe9Mww1VgV3wAAgxRO5v_LdV6foAXrGLVExAXrGLU-I_____w",
"story_id": "1a24e9dc-dfd2-5e00-871c-9c76ce2b4ac1",
"media_metadata":
{
"media_type": "MEDIA_TYPE_IMAGE",
"media_url": "https://cf-st.sc-cdn.net/d/j0qgaSLgErr86W9f6Nivh.400.IRZXSOY?mo=GjsaChoAGgBIAlAwYAGiARUIkAMiEAoDMgEEEgAqB0lSWlhTT1miARQIASIQCg4yAQE6AQRCBgj7rt2HBg%3D%3D&uc=48",
"thumbnail_url": "https://s.sc-cdn.net/indef/8Rc1_E1wtn72dttx3Vq9zl18OJp3zZG2QH4kAYPTB4Y=/default/thumb/thumb.jpg"
},
"created_at": "2021-07-20T23:08:16.136Z"
}
},
{
"sub_request_status": "SUCCESS",
"snap":
{
"id": "4i3kH1nyTcOe9Mww1VgV3wAAg1h1_n7DpfQC8AXrGLXPVAXrGLXJX_____w",
"story_id": "1a24e9dc-dfd2-5e00-871c-9c76ce2b4ac1",
"media_metadata":
{
"media_type": "MEDIA_TYPE_IMAGE",
"media_url": "https://cf-st.sc-cdn.net/d/lyYXBnkuoOkop7BcrbLmp.400.IRZXSOY?mo=GjsaChoAGgBIAlAwYAGiARUIkAMiEAoDMgEEEgAqB0lSWlhTT1miARQIASIQCg4yAQE6AQRCBgiEr92HBg%3D%3D&uc=48",
"thumbnail_url": "https://s.sc-cdn.net/indef/T3SU3jGhb1MrOakUZkdEBlZZXIASkQSvgM19EF4i4Y4=/default/thumb/thumb.jpg"
},
"created_at": "2021-07-20T23:08:25.047Z"
}
}],
"paging":
{}
}
Post Story to Public Profile
Story posting involves the following steps :
- Step 1 : Create a media object (see create mediadocumentation)
- Step 2 : Upload video or image file (see multipart upload documentation)
- Step 3 : Use this story posting API to post the media as a story to a public profile.
Constraints
The media being used for story posting must adhere to the following constraints :
- Video should be in .mp4 format
- Video Duration : 5-60 seconds
- Video resolution at least 540x960px
HTTP Request
POST https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/stories
Parameters
Field name | Required | Description | Possible Values | |
---|---|---|---|---|
media_id | R | ID of the meda which is to be used for story posting |
HTTP Response
Name | Description | Possible Values | ||
---|---|---|---|---|
request_id | A UUID to identify this request. | |||
request_status | SUCCESS / ERROR | |||
debug_message | A debug message to help debug if there is an error | |||
display_message | Display message if there is an error. | |||
error_code | Error code if there is an error |
Example
curl -X POST \
-d '{"media_id": "123c1688-3725-452e-ade2-d89645cd2486"}' \
-H "Content-Type: application/json" \
-H "Authorization: <ACCESS_TOKEN>" \
https://businessapi.snapchat.com/v1/public_profiles/76da494b-76bc-4bbb-bb27-c5a66fb0d1ab/stories
Response
{
"request_id": "5007083c-cef7-4638-bea7-1b8a6d5b7281",
"request_status": "SUCCESS",
}
Saved Stories
Saved Stories can be retrieved in batch, by profile ID. Snaps contained in the saved stories can be retrieved by the Saved Story ID.
Get Saved Story by Profile ID
This endpoint retrieves all Saved Stories for a given profile.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/saved_stories
Parameters
Parameter | Required | Default | Description | Possible Values |
---|---|---|---|---|
profile_id | R | The profile id in the url path | UUID | |
visibility | O | ALL | Profile owners can choose to save some stories to their profile that do not become visible on the profile. For example, when creating a Spotlight they may save a copy of the Spotlight as a saved story. Setting this parameter to VISIBLE_ON_PROFILE only returns saved stories that are visible on the profile. | ALL, VISIBLE_ON_PROFILE |
limit | O | Pagination limit size of returned saved stories. If not specified, default is 10 | Integers that is bigger than 0 | |
cursor | O | Pagination encoded cursor for next page of saved stories. Default is empty |
HTTP Response
Field | Description | Possible Values | ||
---|---|---|---|---|
request_id | UUID of the request | UUID | ||
request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
saved_stories | List of sub responses which contains Saved Stories | Refer to the Saved Story table below | ||
paging | Next page information if exists | |||
debug_message | Debug information string if request_status is ERROR or Partial | |||
display_message | Display information string if request_status is ERROR or Partial | |||
error_code | Error code string if request_status is ERROR or Partial |
Saved Stories
Field | Description | Possible Values | ||
---|---|---|---|---|
sub_request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
saved_story | Story metadata object | |||
sub_request_error_reason | Error reason string if sub_request_status is ERROR or Partial |
Story
Field | Description | Is Public | Possible Values | |
---|---|---|---|---|
id | UUID of the saved story | Y | ||
profile_id | UUID of the profile the saved story belongs to | Y | ||
thumbnail_url | Unencrypted thumbnail url to render the story | Y | ||
title | Title of the saved story | Y | ||
created_at | Creation timestamp | Y | ||
type | Story type | SAVED_STORY | ||
updated_at | Last updated timestamp | By default, it will be the same as created_at timestamp if not updated |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/saved_stories?limit=10&cursor=xxxx"
-H "Authorization: <ACCESS_TOKEN>"
Response
{
"request_id": "0efe011f-4f91-409b-8329-987d29769c40",
"request_status": "SUCCESS",
"saved_stories": [
{
"sub_request_status": "SUCCESS",
"saved_story":
{
"id": "1ea5a405-85b7-40f0-bcc5-148a29d142c2",
"profile_id": "76da494b-76bc-4bbb-bb27-c5a66fb0d1ab",
"thumbnail_url": "https://cf-st.sc-cdn.net/d/nOyACxG8CUS7VOKjUqSL1.410.IRZXSOY?uc=12",
"created_at": "2021-03-05T02:33:39.240Z",
"type": "SAVED_STORY"
}
}],
"paging":
{
"next_page_id": "ImV5SlFjbTltYVd4bFNVUWlPaUkzTm1SaE5EazBZaTAzTm1KakxUUmlZbUl0WW1JeU55MWpOV0UyTm1aaU1HUXhZV0lpTENKSWFXZG9iR2xuYUhSSlJDSTZJakZsWVRWaE5EQTFMVGcxWWpjdE5EQm1NQzFpWTJNMUxURTBPR0V5T1dReE5ESmpNaUlzSWs5eVpHVnlhVzVuSWpveE5qRTBPVEV4TmpFNU1qUXdMQ0pUYjNWeVkyVlBjbVJsY21sdVp5STZJaUo5Ig",
"next_link": "https://businessapi.snapchat.com/v1/public_profiles/76da494b-76bc-4bbb-bb27-c5a66fb0d1ab/saved_stories%3Flimit=1?limit=1&cursor=ImV5SlFjbTltYVd4bFNVUWlPaUkzTm1SaE5EazBZaTAzTm1KakxUUmlZbUl0WW1JeU55MWpOV0UyTm1aaU1HUXhZV0lpTENKSWFXZG9iR2xuYUhSSlJDSTZJakZsWVRWaE5EQTFMVGcxWWpjdE5EQm1NQzFpWTJNMUxURTBPR0V5T1dReE5ESmpNaUlzSWs5eVpHVnlhVzVuSWpveE5qRTBPVEV4TmpFNU1qUXdMQ0pUYjNWeVkyVlBjbVJsY21sdVp5STZJaUo5Ig"
}
}
Get Snaps by Saved Story ID
This endpoint retrieves a Snaps by the Saved Story ID.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/saved_stories/{id}/snaps
Parameters
Parameter | Required | Description | Possible Values | |
---|---|---|---|---|
profile_id | Yes | the profile id in the url path | UUID | |
limit | No | Pagination limit size of returned snaps. If not specified, default is 10 | Integers that is bigger than 0 | |
cursor | No | Pagination encoded cursor for next page of snaps. Default is empty |
HTTP Response
Field | Description | Possible Values | ||
---|---|---|---|---|
request_id | UUID of the request | UUID | ||
request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
snaps | List of sub responses which contains Snaps | Refer to the Snaps table below | ||
paging | Next page information if exists | |||
debug_message | Debug information string if request_status is ERROR or Partial | |||
display_message | Display information string if request_status is ERROR or Partial | |||
error_code | Error code string if request_status is ERROR or Partial |
Snaps
Field | Description | Possible Values | ||
---|---|---|---|---|
sub_request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
snap | Snap metadata object | |||
sub_request_error_reason | Error reason string if sub_request_status is ERROR or Partial |
Snap
Field | Description | Possible Values | ||
---|---|---|---|---|
id | Unique id of the snap | |||
story_id | UUID of the story the snap belongs to | |||
media_metadata | Unencrypted thumbnail url to render the snaps | |||
created_at | Creation timestamp | |||
title | Title of the snap | |||
caption | Concatenated text created from original overlay text of the story |
Media Metadata
Field | Description | Possible Values | ||
---|---|---|---|---|
media_type | Media type | MEDIA_TYPE_IMAGE MEDIA_TYPE_VIDEO | ||
media_url | Unencrypted media downloadable url | |||
thumbnail_url | Unencrypted thumbnail url of the snap |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/saved_stories/{id}/snaps?limit=10&cursor=xxxx"
-H "Authorization: <ACCESS_TOKEN>"
Response
{
"request_id": "0efe011f-4f91-409b-8329-987d29769c40",
"request_status": "SUCCESS",
"saved_stories": [
{
"sub_request_status": "SUCCESS",
"saved_story": {
"id": "1ea5a405-85b7-40f0-bcc5-148a29d142c2",
"profile_id": "76da494b-76bc-4bbb-bb27-c5a66fb0d1ab",
"thumbnail_url": "https://cf-st.sc-cdn.net/d/nOyACxG8CUS7VOKjUqSL1.410.IRZXSOY?uc=12",
"created_at": "2021-03-05T02:33:39.240Z",
"type": "SAVED_STORY",
"updated_at": "2021-03-05T02:33:39.240Z",
"title": "Title for saved story",
"caption": "Captiontextfromstory",
}
}
],
"paging": {
"next_page_id": "ImV5SlFjbTltYVd4bFNVUWlPaUkzTm1SaE5EazBZaTAzTm1KakxUUmlZbUl0WW1JeU55MWpOV0UyTm1aaU1HUXhZV0lpTENKSWFXZG9iR2xuYUhSSlJDSTZJakZsWVRWaE5EQTFMVGcxWWpjdE5EQm1NQzFpWTJNMUxURTBPR0V5T1dReE5ESmpNaUlzSWs5eVpHVnlhVzVuSWpveE5qRTBPVEV4TmpFNU1qUXdMQ0pUYjNWeVkyVlBjbVJsY21sdVp5STZJaUo5Ig",
"next_link": "https://businessapi.snapchat.com/v1/public_profiles/76da494b-76bc-4bbb-bb27-c5a66fb0d1ab/saved_stories%3Flimit=1?limit=1&cursor=ImV5SlFjbTltYVd4bFNVUWlPaUkzTm1SaE5EazBZaTAzTm1KakxUUmlZbUl0WW1JeU55MWpOV0UyTm1aaU1HUXhZV0lpTENKSWFXZG9iR2xuYUhSSlJDSTZJakZsWVRWaE5EQTFMVGcxWWpjdE5EQm1NQzFpWTJNMUxURTBPR0V5T1dReE5ESmpNaUlzSWs5eVpHVnlhVzVuSWpveE5qRTBPVEV4TmpFNU1qUXdMQ0pUYjNWeVkyVlBjbVJsY21sdVp5STZJaUo5Ig"
}
}
Create A Saved Story
A Saved Story can be created using any of these sources :
- A spotlight
- A snap from a public story
- A media
HTTP Request
POST https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/saved_stories
Parameters
Parameter | Required | Description | Possible Values | |
---|---|---|---|---|
saved_stories | Yes | A list of saved stories to be created. This list should contain only one saved story. Creating multiple saved stories in one request is not supported at the moment | Refer to the Saved Story table below |
Saved Story
Field | Description | Possible Values | ||
---|---|---|---|---|
snap_sources | List of Snap Sources to be used in the saved story. The saved story will contain the snaps in the same order as provided in this list. The duration of all snaps combined cannot exceed 5 minutes. | Refer to the Snap Source table below | ||
title | A title for the saved story. Limited to 45 characters |
Sanp Source
Field | Description | Possible Values | ||
---|---|---|---|---|
snap_id | If the sourced snap is from a public story, then that story snap’s ID should be provided. At least one snap_id, media_id, or spotlight_id should be provided. | |||
media_id | If the sourced snap is uploaded media, then the media ID should be provided. At least one snap_id, media_id, or spotlight_id should be provided. | |||
spotlight_id | If the sourced snap is a spotlight, then that spotlight’s ID should be provided. At least one snap_id, media_id, or spotlight_id should be provided. |
HTTP Response
Field | Description | Possible Values | ||
---|---|---|---|---|
request_id | UUID of the request | UUID | ||
request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
saved_stories | List of sub responses which contains Saved Stories | |||
debug_message | Debug information string if request_status is ERROR or Partial | |||
display_message | Display information string if request_status is ERROR or Partial | |||
error_code | Error code string if request_status is ERROR or Partial |
Example
curl -X POST \
-d '{"saved_stories":[{"title":"My Saved Story", "snap_sources":[{"spotlight_id":"meowmeow"}, {"media_id":"meowmeow"}, {"snap_id":"meowmeow"}]}]}' \
-H 'Authorization: <ACCESS_TOKEN>' \
https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/saved_stories
Response
{
"request_id": "014330f8-fe34-4f0e-89b0-b55bf35b120a",
"request_status": "SUCCESS",
"saved_stories": [
{
"sub_request_status": "SUCCESS",
"saved_story": {
"id": "11290c7c-9c56-4bdd-8848-7ce77fed88a3"
}
}
]
}
Spotlights
Get Spotlights by Profile ID
This endpoint retrieves all Spotlights for a given profile.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/spotlights
Parameters
Parameter | Required | Description | Possible Values | |
---|---|---|---|---|
profile_id | Yes | the profile id in the url path | UUID | |
limit | No | Page size of returned spotlights. If not specified, default is 10 | Integer that is bigger than 0 | |
cursor | No | Cursor for next page of spotlights. Default is empty |
HTTP Response
Field | Description | Possible Values | ||
---|---|---|---|---|
request_id | UUID of the request | UUID | ||
request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
spotlights | List of sub responses. Each sub response contains a Spotlight | Refer to the Spotlights table below | ||
paging | Next page information if exists | |||
debug_message | Debug information string if request_status is ERROR or Partial | |||
display_message | Display information string if request_status is ERROR or Partial | |||
error_code | Error code string if request_status is ERROR or Partial |
Spotlights
Field | Description | Possible Values | ||
---|---|---|---|---|
sub_request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
spotlight | Spotlight metadata object | |||
sub_request_error_reason | Error reason string if sub_request_status is ERROR or Partial |
Spotlight
Field | Description | Is Public | Possible Values | |
---|---|---|---|---|
id | ID of the spotlight | Y | ||
profile_id | UUID of the profile the spotlight belongs to | Y | ||
thumbnail_url | The spotlight’s thumbnail url | Y | ||
media_url | The spotlight’s media url | Y | ||
created_at | Creation timestamp | Y | ||
status | Status of the spotlight. When a spotlight is posted, its initial status is SUBMITTED. A submitted spotlight has to go through an approval process before being made LIVE. If the spotlight is not approved then the status is going to be REJECTED. | SUBMITTED LIVE REJECTED | ||
duration | Duration of the spotlight in seconds | |||
title | The title of the spotlight | Y | ||
caption | The caption of the spotlight. This would also include any mentions. | Y | ||
hashtags | Array of all the hashtags on this spotlight when they are added to the title. Hashtags added as part of captions are captured in the captions field. | Y | ||
sponsor | The Public Profile of the Brand being tagged in the shared_snap and the post is marked as paid partnership. The sponsor field appears before the status hits APPROVED. The possible values of this field are: PENDING : Pending for the brand to review the snap. REJECTED : Rejected by the brand NOT_SPECIFIED : The snap is sponsored without specifying a sponsor explicitly, thus no need to review. AUTO_APPROVED : The snap was auto-approved because the brand has provided certain permissions to the creator | Y | ||
ml_tags | The machine learning generated tags on creator content that can highlight brand names, topics, scenarios etc. | Y |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}spotlights?limit=10&cursor=xxxx"
-H "Authorization: <ACCESS_TOKEN>"
Response
{
"request_id": "0efe011f-4f91-409b-8329-987d29769c40",
"request_status": "SUCCESS",
"spotlights": [
{
"sub_request_status": "SUCCESS",
"spotlight": {
"id": "W7_EDlXWTBiXAEEniNoMPwAAYaWd5d21yeG92AX_7pp00AX_7ppwFAAAAAA",
"profile_id": "76da494b-76bc-4bbb-bb27-c5a66fb0d1ab",
"thumbnail_url": "https://cf-st.sc-cdn.net/d/nOyACxG8CUS7VOKjUqSL1.410.IRZXSOY?uc=12",
"media_url": "https://cf-st.sc-cdn.net/d/C0rSNE5CgyB3gpAVaYC0W.27...",
"created_at": "2021-03-05T02:33:39.240Z",
"title": "A new spotlight",
"hashtags": ["hashtag1", "hashtag2"],
"status": "LIVE"
"sponsor": {
"profile_id": {
"high_bits": "3333118795269425713",
"low_bits": "12035785981443997886"
},
"display_name": "City Boutique",
"sponsor_status": "AUTO_APPROVED"
"ml_tags": [
"sunglasses",
"water music",
"#poolvibes",
"swimwear",
"water",
"pooltime"
]
},
}
}
],
"paging": {
"next_page_id": "ImV5Sl...",
"next_link": "https://businessapi.snapchat.com/v1/public_profiles/76da4.../spotlights%3Flimit=1?limit=1&cursor=ImV5Sl..."
}
}
Get a Spotlight by Spotlight ID
This endpoint retrieves a Spotlight for a given profile and spotlight id.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/spotlights/{spotlight_id}
Parameters
Parameter | Required | Description | Possible Values | |
---|---|---|---|---|
profile_id | Yes | the profile id in the url path | UUID | |
spotlight_id | Yes | the spotlight id in the url path |
HTTP Response
Field | Description | Possible Values | ||
---|---|---|---|---|
request_id | UUID of the request | UUID | ||
request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
spotlights | List of sub responses. Each sub response contains a Spotlight | Refer to the Spotlights table in the “Get Spotlights by Profile ID” section | ||
debug_message | Debug information string if request_status is ERROR or Partial | |||
display_message | Display information string if request_status is ERROR or Partial | |||
error_code | Error code string if request_status is ERROR or Partial |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}spotlights/{spotlight_id}"
-H "Authorization: <ACCESS_TOKEN>"
Response
{
"request_id": "0efe011f-4f91-409b-8329-987d29769c40",
"request_status": "SUCCESS",
"spotlights": [
{
"sub_request_status": "SUCCESS",
"spotlight": {
"id": "W7_EDlXWTBiXAEEniNoMPwAAYaWd5d21yeG92AX_7pp00AX_7ppwFAAAAAA",
"profile_id": "76da494b-76bc-4bbb-bb27-c5a66fb0d1ab",
"thumbnail_url": "https://cf-st.sc-cdn.net/d/nOyACxG8CUS7VOKjUqSL1.410.IRZXSOY?uc=12",
"media_url": "https://cf-st.sc-cdn.net/d/C0rSNE5CgyB3gpAVaYC0W.27...",
"created_at": "2021-03-05T02:33:39.240Z",
"status": "LIVE"
}
}
]
}
Post Spotlight
Spotlight posting involves the following steps :
- Step 1 : Create a media object (see create media documentation)
- Step 2 : Upload video (see multipart upload documentation)
- Step 3 : Use this spotlight posting API to post the video as a spotlight.
Constraints The media being used for spotlight posting must adhere to the following constraints :
- Video should be in .mp4 format
- Video Duration : 5-60 seconds
- Video resolution at least 540x960px
HTTP Request
POST https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/spotlights
Parameters
Field name | Required | Description | Possible Values | |
---|---|---|---|---|
media_id | R | ID of the media which is to be used for spotlight posting | ||
skip_save_to_profile | O | If set to true, the spotlight will not be shown on the public profile. The default value is false. | true false | |
description | O | The spotlight’s description can be up to a 160 characters and can include hashtags | ||
locale | R | Locale indicates the language and country. Example : en_US |
HTTP Response
Name | Description | Possible Values | ||
---|---|---|---|---|
request_id | A UUID to identify this request. | |||
request_status | SUCCESS / ERROR | |||
spotlight_id | The ID of the posted spotlight | |||
debug_message | A debug message to help debug if there is an error | |||
display_message | Display message if there is an error. | |||
error_code | Error code if there is an error |
Example
curl -X POST \
-d '{"media_id":"123c1688-3725-452e-ade2-d89645cd2486", "skip_save_to_profile":false, "description":”hello #world", "locale":"en_US"}' \
-H "Content-Type: application/json" \
-H "Authorization: <ACCESS_TOKEN>" \
https://businessapi.snapchat.com/v1/public_profiles/76da494b-76bc-4bbb-bb27-c5a66fb0d1ab/spotlights
Respnse
{
"request_id": "5007083c-cef7-4638-bea7-1b8a6d5b7281",
"spotlight_id": "W7_EDlXWTBiXAEEniNoMPwAAYZmJ2cHZmeGd6AYKzgDcrAYKzgDaiAAAAAA",
"request_status": "SUCCESS"
}
Social Listening
When trying to identify and understand which creators are talking about which brands on Snapchat, utilizing the content metadata fields provided by the api can be very useful. The content metadata fields can be found to varying degrees under each asset type i.e. Spotlight, Stories and Saved Stories. There are three fields associated with content metadata:
- Title : The title text added on the asset
- Caption : Text added as caption on the asset
- Hashtags : Array of all the hashtags added on the title. Note that hashtags added on captions will be available on caption field not in this field.
These fields are nullable, meaning in cases where relevant text doesnt exist on the asset, these will not be returned in the response.
Spotlight
Content Metadata associated with a spotlight is available on the Get spotlights by profile endpoint. When metadata exists, all the three fields will be returned.
Stories
Since Stories can comprise of multiple snaps, the content metadata fields are available via the Get Snaps by Story Id endpoint. Only the Caption field is returned as Title is not exactly a feature on story.
Saved Stories
Similar to stories, saved stories can have multiple snaps and therefore the content metadata fields are available via the Get snaps by Saved Story Id endpoint. This endpoint can return caption and title. Note that the content on the caption field is concatenated text. We recommend utilizing regex and/or string search to match necessary keywords.
Image Based Content Metadata
Note: This feature is behind an allowlist. To request access, please reach out to your Snap point of contact to request access.
With this API feature we provide machine learning generated tags on creator content that can highlight brand names, topics, scenarios, and more. These content metadata is available in the 'ml_tags' field for spotlights and stories.
- The ml_tags can be retrieved for spotlights using the Get spotlights by profile endpoint.
- The ml_tags can be retrieved for stories using the Get Snaps by Story Id endpoint.
Lenses
Lenses can be retrieved in batch, by profile ID. or individually by the lens ID.
Lens Entity
Field | Description | Is Public | Possible Values | Possible Values |
---|---|---|---|---|
id | UUID of the lens | Y | UUID | |
profile_id | UUID of the profile the lens belongs to | Y | Integers that is bigger than 0 | |
name | Lens name | Y | ||
icon_url | Url for the icon of the lens | Y | ||
status | Status of the lens | LENS_STATUS_UNSET LENS_STATUS_IN_REVIEW LENS_STATUS_INVALID LENS_STATUS_REJECTED LENS_STATUS_LIVE LENS_STATUS_OFFLINE LENS_STATUS_HIDDEN LENS_STATUS_AWAITING_PRODUCT_TAGGING | ||
updated_at | Last updated timestamp | |||
updated_by | Last updated user/app name | |||
snapcode | Snapcode for the lens | Y | Refer to the snapcode table below | |
preview_media | Lens media preview data | Y | Refer to the preview media table below | |
rejection_errors | Optional if lens is no rejected | Refer to the rejection errors table below | ||
created_at | Creation timestamp of the lens | Y |
Snapcode
Field | Description | Is Public | Possible Values | |
---|---|---|---|---|
image_url | Url of the snapcode image | Y | ||
deeplink | Deeplink url | Y | ||
expires_at | Snapcode expire date | |||
status | Status of the snapcode | SNAP_CODE_STATUS_UNSET SNAP_CODE_STATUS_TEMPORARY SNAP_CODE_STATUS_DONE |
Preview Media
Field | Description | Is Public | Possible Values | |
---|---|---|---|---|
thumbnail_media_url | Url of the thumbnail media | Y | ||
thumbnail_media_poster_url | Url of the thumbnail media poster | Y | ||
standard_media_url | Url of the standard media | |||
standard_media_poster_url | Url of the standard media poster | |||
media_status | Status of the media | MEDIA_STATUS_IN_REVIEW MEDIA_STATUS_OK MEDIA_STATUS_INVALID MEDIA_STATUS_REJECTED |
Rejection Errors
Field | Description | Possible Values | ||
---|---|---|---|---|
heading | Rejection’s heading | |||
messages | List of rejection messages | |||
violating_components | List of violating components |
Get Lenses by Profile ID
This endpoint retrieves all lenses for a given profile.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/lenses
Parameters
Parameter | Required | Description | Possible Values | |
---|---|---|---|---|
profile_id | Yes | the profile id in the url path | UUID | |
limit | No | Pagination limit size of returned lenses. If not specified, default is 10 | Integers that is bigger than 0 | |
cursor | No | Pagination encoded cursor for next page of lenses. Default is empty |
HTTP Response
Field | Description | Possible Values | ||
---|---|---|---|---|
request_id | UUID of the request | UUID | ||
request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
lenses | List of sub responses which contains lenses | Refer to the Lenses table below | ||
paging | Next page information if exists | |||
debug_message | Debug information string if request_status is ERROR or Partial | |||
display_message | Display information string if request_status is ERROR or Partial | |||
error_code | Error code string if request_status is ERROR or Partial |
Lenses
Field | Description | Possible Values | ||
---|---|---|---|---|
sub_request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
lens | Lens metadata object | Refer to the Lens entity | ||
sub_request_error_reason | Error reason string if sub_request_status is ERROR or Partial |
Examples
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/lenses?limit=10&cursor=xxxx"
-H "Authorization: <ACCESS_TOKEN>"
Response
{
"request_id": "5fc377d1-86ad-45bb-92d7-b9c1818d8e2c",
"request_status": "SUCCESS",
"lenses": [
{
"sub_request_status": "SUCCESS",
"lens":
{
"id": "0bbc3685-eb68-44b9-8ca0-4fe5747fe6a3",
"profile_id": "76da494b-76bc-4bbb-bb27-c5a66fb0d1ab",
"name": "banana",
"icon_url": "https://lens-storage.storage.googleapis.com/png/1fd1c08ef4744ca79fe177b2e20e732e",
"status": "LENS_STATUS_LIVE",
"updated_at": "2021-05-12T00:39:22.414Z",
"snapcode":
{
"image_url": "https://snapcodes.storage.googleapis.com/png/1cf48f2e-7b7c-31db-b674-49fabf8f5437_320_bb3ecf1e-1938-47ef-9bd9-f24f1f820b8b.png",
"deeplink": "https://www.snapchat.com/unlock/?type=SNAPCODE&uuid=868fa95bf50849dfa250ce0bfe36f595&metadata=01",
"expires_at": "1970-01-01T00:00:00Z",
"status": "SNAP_CODE_STATUS_DONE"
},
"preview_media":
{
"thumbnail_media_url": "https://community-lens.storage.googleapis.com/preview-media/thumbnail/4bdafdc4-67db-4cea-9bcf-f7c0193f0a66.mp4",
"thumbnail_media_poster_url": "https://community-lens.storage.googleapis.com/preview-media/thumbnail_poster/4bdafdc4-67db-4cea-9bcf-f7c0193f0a66.jpg",
"standard_media_url": "https://community-lens.storage.googleapis.com/preview-media/final/4bdafdc4-67db-4cea-9bcf-f7c0193f0a66.mp4",
"standard_media_poster_url": "https://community-lens.storage.googleapis.com/preview-media/final_poster/4bdafdc4-67db-4cea-9bcf-f7c0193f0a66.jpg",
"media_status": "MEDIA_STATUS_OK"
},
"rejection_errors":
{}
}
}],
"paging":
{
"next_page_id": "MQ",
"next_link": "https://businessapi.snapchat.com/v1/public_profiles/76da494b-76bc-4bbb-bb27-c5a66fb0d1ab/lenses%3Flimit=1?limit=1&cursor=MQ"
}
}
Get Lens by Lens ID
This endpoint retrieves a Lens by the Lens ID.
HTTP Request
GET https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/lenses/{lens_id}
Parameters
Parameter | Required | Description | Possible Values | |
---|---|---|---|---|
profile_id | Yes | the profile id in the url path | UUID | |
lens_id | YES | The lens id in the url path | UUID |
HTTP Response
Field | Description | Possible Values | Possible Values | |
---|---|---|---|---|
request_id | UUID of the request | UUID | UUID | |
request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | UUID | |
lenses | List of sub responses which contains lenses | |||
debug_message | Debug information string if request_status is ERROR or Partial | |||
display_message | Display information string if request_status is ERROR or Partial | |||
error_code | Error code string if request_status is ERROR or Partial |
Lenses
Field | Description | Possible Values | ||
---|---|---|---|---|
sub_request_status | String to indicate the request status | SUCCESS ERROR PARTIAL | ||
lens | Lens metadata object | Refer to the Lens entity | ||
sub_request_error_reason | Error reason string if sub_request_status is ERROR or Partial |
Example
curl "https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/lenses/{lens_id}"
-H "Authorization: <ACCESS_TOKEN>"
Response
{
"request_id": "0829f500-066f-4cfb-b750-a5b37cfeea66",
"request_status": "SUCCESS",
"lenses": [
{
"sub_request_status": "SUCCESS",
"lens":
{
"id": "0bbc3685-eb68-44b9-8ca0-4fe5747fe6a3",
"profile_id": "76da494b-76bc-4bbb-bb27-c5a66fb0d1ab",
"name": "banana",
"icon_url": "https://lens-storage.storage.googleapis.com/png/1fd1c08ef4744ca79fe177b2e20e732e",
"status": "LENS_STATUS_LIVE",
"updated_at": "2021-05-12T00:39:22.414Z",
"snapcode":
{
"image_url": "https://snapcodes.storage.googleapis.com/png/1cf48f2e-7b7c-31db-b674-49fabf8f5437_320_bb3ecf1e-1938-47ef-9bd9-f24f1f820b8b.png",
"deeplink": "https://www.snapchat.com/unlock/?type=SNAPCODE&uuid=868fa95bf50849dfa250ce0bfe36f595&metadata=01",
"expires_at": "1970-01-01T00:00:00Z",
"status": "SNAP_CODE_STATUS_DONE"
},
"preview_media":
{
"thumbnail_media_url": "https://community-lens.storage.googleapis.com/preview-media/thumbnail/4bdafdc4-67db-4cea-9bcf-f7c0193f0a66.mp4",
"thumbnail_media_poster_url": "https://community-lens.storage.googleapis.com/preview-media/thumbnail_poster/4bdafdc4-67db-4cea-9bcf-f7c0193f0a66.jpg",
"standard_media_url": "https://community-lens.storage.googleapis.com/preview-media/final/4bdafdc4-67db-4cea-9bcf-f7c0193f0a66.mp4",
"standard_media_poster_url": "https://community-lens.storage.googleapis.com/preview-media/final_poster/4bdafdc4-67db-4cea-9bcf-f7c0193f0a66.jpg",
"media_status": "MEDIA_STATUS_OK"
},
"rejection_errors":
{}
}
}]
}
Sharing Policies
Sharing policies can be used to share access to a resource from one Organization to another Organization, currently the resources that can be shared are pixels and public profiles. To revoke the access the sharing policy can be deleted.
Attributes
sharing_policies entity
Attribute | Description | Required | Possible values |
---|---|---|---|
sharing_policy_id | id of the sharing_policies entity | - | Read-only attribute |
source | resource to be shared | R | see source attribute |
target | entity that resource should be shared with | R | see target attribute |
parent_policy_id | used when sharing resources with an Organization outside of the Organization where the resource lives | O |
source attribute
Attribute | Description | Required | Possible values |
---|---|---|---|
resource_id | the id of the resource | R | id of the entity that is being shared |
resource_type | the type of the resource | R | pixels,public_profiles |
target attribute
Attribute | Description | Required | Possible values |
---|---|---|---|
resource_id | the id of the entity | R | id of the entity that the source is to be shared with |
resource_type | the type of the entity | R | adaccounts,organizations |
List Sharing Policies
This request will list all the resources shared with a specific ad account, it accepts multiple parameters via a comma separated string.
HTTP Request
GET https://businessapi.snapchat.com/v1/adaccounts/{ad_account_id}/sharing_policies?shared_resource_types={resource_type}
Request Parameters
Parameter | Default | Description |
---|---|---|
resource_type | One or multiple; pixels,public_profiles,catalogs |
Example request
This requests fetches all Pixels, Public Profiles and Catalogs shared with the Ad Account
cURL \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
'https://businessapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/sharing_policies?shared_resource_types=public_profiles,pixels,catalogs
Example response
{
"request_id": "5aafcbe4-17b5-4484-affa-5c98af0f5cf2",
"request_status": "SUCCESS",
"paging": {},
"sharing_policies": [
{
"sharing_policy_id": "1138c4d1-d8fd-4c90-94ba-8768b9122a42",
"source": {
"resource_type": "catalogs",
"resource_id": "de4bb295-11c2-40fc-9642-0a976f3ec46e"
}
},
{
"sharing_policy_id": "153a4bc0-3495-447b-badc-91e484c8c9aa",
"source": {
"resource_type": "public_profiles",
"resource_id": "3a36c147-688c-474d-9aa9-76e12676f203"
}
},
{
"sharing_policy_id": "178fbbd3-26c6-4be7-a9af-3877e895ecc2",
"source": {
"resource_type": "pixels",
"resource_id": "cd24c745-44e2-450c-9028-37d937784cb8"
}
},
{
"sharing_policy_id": "1c022ea8-30b5-491b-a063-a6405b4ed82b",
"source": {
"resource_type": "catalogs",
"resource_id": "904b3083-6d52-4f30-beac-4d6bfd142eb3"
}
}
]
}
Create Sharing Policies for Ad Accounts in the Same Organization
HTTP Request
POST https://businessapi.snapchat.com/v1/{resource_type}/{resource_id}/sharing_policies
Request Parameters
Parameter | Default | Description |
---|---|---|
resource_type | One of pixels/public_profiles/catalogs | |
resource_id | the id of the resource |
Body Parameters
Parameter | Default | Description |
---|---|---|
sharing_policies | the sharing_policies needs to include a source attribute specifying a pixel/public profile/catalog and a target attribute specifying the ad account where the resource will be shared |
Example request
This request shares a Public Profile entity to an Ad Account within the same Organization.
cURL -X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
'https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/sharing_policies' \
-D '{
"sharing_policies":[
{
"source" : {
"resource_id" : "f7ef8b72-f826-4ae1-acae-3c5ce40d4c35",
"resource_type" : "public_profiles"
},
"target" : {
"resource_id" : "2ac22383-6e7e-4134-83a3-299f1e2a05db",
"resource_type" : "adaccounts"
}
}
]
}
Example response
{
"request_id": "eb0bf046-5eb9-42e7-99fd-234994d66ce4",
"request_status": "SUCCESS",
"sharing_policies": [
{
"sub_request_status": "SUCCESS",
"sharing_policy": {
"sharing_policy_id": "1ca26f4f-ea3f-43e8-97d8-34a92e5d68cc",
"source": {
"resource_type": "public_profiles",
"resource_id": "f7ef8b72-f826-4ae1-acae-3c5ce40d4c35"
},
"target": {
"resource_type": "adaccounts",
"resource_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
}
}
}
]
}
Create Sharing Policies for an External Organization
To create a sharing policy with an external Organization you will need to carry out an API request specifying the resource to be shared and the Organization it's to be shared with, if the request is successful it will return a sharing_policy_id.
The sharing_policy_id should be stored as it's required to be passed as parent_policy_id once you execute an API request to share the resource to an Ad Account in the external Organization.
HTTP Request
POST https://businessapi.snapchat.com/v1/{resource_type}/{resource_id}/sharing_policies
Request Parameters
Parameter | Default | Description |
---|---|---|
resource_type | One of pixels/public_profiles/catalogs | |
resource_id | the id of the resource |
Body Parameters
Parameter | Default | Description |
---|---|---|
sharing_policies | the sharing_policies needs to include a source attribute specifying a pixel/public profile/catalog to be shared with the Organization, and a target attribute specifying the Organization |
Example Request
This request creates a sharing policy for the Public Profile Id f7ef8b72-f826-4ae1-acae-3c5ce40d4c35 to be shared to the external Organization id dc4cd3c0-0628-4fb1-8c73-54e1f4a69abe , note how the response passes back a sharing_policy_id.
cURL -X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
'https://businessapi.snapchat.com/v1/public_profiles/f7ef8b72-f826-4ae1-acae-3c5ce40d4c35/sharing_policies' \
-D '{
"sharing_policies":[
{
"source" : {
"resource_id" : "f7ef8b72-f826-4ae1-acae-3c5ce40d4c35",
"resource_type" : "public_profiles"
},
"target" : {
"resource_id" : "dc4cd3c0-0628-4fb1-8c73-54e1f4a69abe",
"resource_type" : "organizations"
},
},
{
...
}
],
}'
Example Response A sharing_policy_id is returned by the API response.
The above command returns JSON structured like this:
{
"request_id": "b08b5c1d-b602-44a1-a6f7-b7f796545993",
"request_status": "SUCCESS",
"sharing_policies": [
{
"sub_request_status": "SUCCESS",
"sharing_policy": {
"sharing_policy_id": "2659bdff-24e4-4e8e-b87a-66218c1bbc33",
"source": {
"resource_type": "public_profiles",
"resource_id": "f7ef8b72-f826-4ae1-acae-3c5ce40d4c35"
},
"target": {
"resource_type": "organizations",
"resource_id": "dc4cd3c0-0628-4fb1-8c73-54e1f4a69abe"
}
}
},
{
…
}
]
}
Create Sharing Policies for an Ad Account in an External Organization
Before a resource can be shared with an external Ad Account, the resource must first be shared with the external Organization. Once the resource has been shared with the external Organization the sharing_policy_id of that request needs to be stored and used as parent_policy_id when sharing the resource with individual Ad Accounts in the external Organization.
HTTP Request
POST https://businessapi.snapchat.com/v1/{resource_type}/{resource_id}/sharing_policies
Request Parameters
Parameter | Default | Description |
---|---|---|
resource_type | One of pixels/public_profiles/catalogs | |
resource_id | the id of the resource |
Body Parameters
Parameter | Default | Description |
---|---|---|
parent_policy_id | the sharing_policy_id for the resource established when the resource was shared to the Organization | |
sharing_policies | the sharing_policies needs to include a source attribute specifying a pixel/public profile/catalog to be shared with the Organization, and a target attribute specifying the Organization |
Example Request
The following request shares the Pixel Id ab9e91ac-d1f6-4d73-bce9-473992de27a7 with the Ad Account Id cdaf9982-1de7-4a19-a887-5794c5c9d7ee where the Ad Account lives in an external Organization.
In order to achieve this the parent_policy_id must be provided, this refers to the sharing_policy_id which was created when the resource was shared to the Organization.
cURL -X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
'https://businessapi.snapchat.com/v1/public_profiles/f7ef8b72-f826-4ae1-acae-3c5ce40d4c35/sharing_policies' \
-D '{
"sharing_policies":[
{
"source" : {
"resource_id" : "ab9e91ac-d1f6-4d73-bce9-473992de27a7",
"resource_type" : "pixels"
},
"target" : {
"resource_id" : "cdaf9982-1de7-4a19-a887-5794c5c9d7ee",
"resource_type" : "adaccounts"
},
"parent_policy_id" : "a6d6ce5b-06d0-4632-9c97-1db1599864b2"
}
]
}
Example Response
{
"request_id": "c55e31db-bcd3-46b9-aa65-76cdd993a370",
"request_status": "SUCCESS",
"sharing_policies": [
{
"sub_request_status": "SUCCESS",
"sharing_policy": {
"sharing_policy_id": "7b57fd0d-5b75-4c1c-ac36-35f905cbeccf",
"source": {
"resource_type": "pixels",
"resource_id": "ab9e91ac-d1f6-4d73-bce9-473992de27a7"
},
"target": {
"resource_type": "adaccounts",
"resource_id": "cdaf9982-1de7-4a19-a887-5794c5c9d7ee"
},
"parent_policy_id": "a6d6ce5b-06d0-4632-9c97-1db1599864b2"
}
}
]
}
Delete a Sharing Policy
Deleting a Sharing Policy means the resource will become inaccessible to the target Ad Account or Organization.
HTTP Request
DELETE https://businessapi.snapchat.com/v1/sharing_policies/{sharing_policy_id}
Request Parameters
Parameter | Default | Description |
---|---|---|
sharing_policy_id | The id of the sharing policy to be deleted |
Example Request
This request deletes sharing policy id 7b57fd0d-5b75-4c1c-ac36-35f905cbeccf
cURL -X DELETE \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
'https://businessapi.snapchat.com/v1/sharing_policies/7b57fd0d-5b75-4c1c-ac36-35f905cbeccf'
Example response
{
"request_id": "6c8015bb-ec37-4079-9581-6a0b324088d5",
"request_status": "SUCCESS"
}