Skip to main content

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:

  1. Encrypt the media file to be used for media upload
  2. If the file is larger than 32MB then split it into smaller chunks
  3. Create a container media object using the Create Media API.
  4. 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

  1. 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
  1. 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 nameRequiredDescriptionPossible Values
typeRType of media.VIDEO, IMAGE
nameRHuman readable name for the media
keyR32 byte key with which the media is encrypted. Should be base64 encoded.
ivR16 byte Initial vector used to encrypt the media. Should be base64 encoded.

HTTP Response

NameDescriptionPossible Values
request_idA UUID to identify this request.
request_statusSUCCESS / ERROR
media_idMedia id which can be used for uploading the media.
debug_messageA debug message to help debug if there is an error
display_messageDisplay message if there is an error.
error_codeError 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 nameRequiredDescriptionPossible Values
actionRADD
fileRThe file part to upload
part_numberRFile part number, used during reassembly of fileCan be between 1 to 35

HTTP Request - FINALIZE

POST https://businessapi.snapchat.com/{finalize_path}

Parameters

Field nameRequiredDescriptionPossible Values
actionFINALIZE

HTTP Response ADD & FINALIZE

NameDescriptionPossible Values
request_idA UUID to identify this request.
request_statusSUCCESS / ERROR
debug_messageA debug message to help debug if there is an error
display_messageDisplay message if there is an error.
error_codeError 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

ParameterRequiredDescriptionPossible Values
profile_idYesthe profile id in the url pathUUID
limitNoPagination limit size of returned stories. If not specified, default is 10Integers that is bigger than 0
cursorNoPagination encoded cursor for next page of stories. Default is empty

HTTP Response

FieldDescriptionPossible Values
request_idUUID of the requestUUID
request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
storiesList of sub responses which contains StoriesRefer to the Story table below
pagingNext page information if exists
debug_messageDebug information string if request_status is ERROR or Partial
display_messageDisplay information string if request_status is ERROR or Partial
error_codeError code string if request_status is ERROR or Partial

Stories

FieldDescriptionPossible Values
sub_request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
storyStory metadata object
sub_request_error_reasonError reason string if sub_request_status is ERROR or Partial

Story

FieldDescriptionPossible Values
idUUID of the story
profile_idUUID of the profile the story belongs to
thumbnail_urlUnencrypted thumbnail url to render the story
created_atCreation timestamp
ended_atEnded timestamp
typeStory typePUBLIC_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

ParameterRequiredDescriptionPossible Values
profile_idYesthe profile id in the url pathUUID
story _idYesthe story id in the url pathUUID
limitNoPagination limit size of returned snaps. If not specified, default is 10Integer that is bigger than 0
cursorNoPagination encoded cursor for next page of snaps. Default is empty
created_atNoCreated timestamp of the storyFormat of UTC like 2021-03-05T02:33:39.240Z
ended_atNoEnded timestamp of the storyended_at should be within 24hr range of PST if created_at is provided

HTTP Response

FieldDescriptionPossible Values
request_idUUID of the requestUUID
request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
snapsList of sub responses which contains SnapsRefer to the Snaps table below
pagingNext page information if exists
debug_messageDebug information string if request_status is ERROR or Partial
display_messageDisplay information string if request_status is ERROR or Partial
error_codeError code string if request_status is ERROR or Partial

Snaps

FieldDescriptionPossible Values
sub_request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
snapSnap metadata object
sub_request_error_reasonError reason string if sub_request_status is ERROR or Partial

Snap

FieldDescriptionPossible Values
idUnique id of the snap
story_idUUID of the story the snap belongs to
media_metadataUnencrypted thumbnail url to render the snaps
created_atCreation timestamp
captionComma separated captions on story. Contains all hashtags and mentions
ml_tagsMachine Learning generated tags on creator content e.g. brand names

Media Metadata

FieldDescriptionPossible Values
media_typeMedia typeMEDIA_TYPE_IMAGE MEDIA_TYPE_VIDEO
media_urlUnencrypted media downloadable url
thumbnail_urlUnencrypted 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 nameRequiredDescriptionPossible Values
media_idRID of the meda which is to be used for story posting

HTTP Response

NameDescriptionPossible Values
request_idA UUID to identify this request.
request_statusSUCCESS / ERROR
debug_messageA debug message to help debug if there is an error
display_messageDisplay message if there is an error.
error_codeError 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

ParameterRequiredDefaultDescriptionPossible Values
profile_idRThe profile id in the url pathUUID
visibilityOALLProfile 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
limitOPagination limit size of returned saved stories. If not specified, default is 10Integers that is bigger than 0
cursorOPagination encoded cursor for next page of saved stories. Default is empty

HTTP Response

FieldDescriptionPossible Values
request_idUUID of the requestUUID
request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
saved_storiesList of sub responses which contains Saved StoriesRefer to the Saved Story table below
pagingNext page information if exists
debug_messageDebug information string if request_status is ERROR or Partial
display_messageDisplay information string if request_status is ERROR or Partial
error_codeError code string if request_status is ERROR or Partial

Saved Stories

FieldDescriptionPossible Values
sub_request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
saved_storyStory metadata object
sub_request_error_reasonError reason string if sub_request_status is ERROR or Partial

Story

FieldDescriptionIs PublicPossible Values
idUUID of the saved storyY
profile_idUUID of the profile the saved story belongs toY
thumbnail_urlUnencrypted thumbnail url to render the storyY
titleTitle of the saved storyY
created_atCreation timestampY
typeStory typeSAVED_STORY
updated_atLast updated timestampBy 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

ParameterRequiredDescriptionPossible Values
profile_idYesthe profile id in the url pathUUID
limitNoPagination limit size of returned snaps. If not specified, default is 10Integers that is bigger than 0
cursorNoPagination encoded cursor for next page of snaps. Default is empty

HTTP Response

FieldDescriptionPossible Values
request_idUUID of the requestUUID
request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
snapsList of sub responses which contains SnapsRefer to the Snaps table below
pagingNext page information if exists
debug_messageDebug information string if request_status is ERROR or Partial
display_messageDisplay information string if request_status is ERROR or Partial
error_codeError code string if request_status is ERROR or Partial

Snaps

FieldDescriptionPossible Values
sub_request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
snapSnap metadata object
sub_request_error_reasonError reason string if sub_request_status is ERROR or Partial

Snap

FieldDescriptionPossible Values
idUnique id of the snap
story_idUUID of the story the snap belongs to
media_metadataUnencrypted thumbnail url to render the snaps
created_atCreation timestamp
titleTitle of the snap
captionConcatenated text created from original overlay text of the story

Media Metadata

FieldDescriptionPossible Values
media_typeMedia typeMEDIA_TYPE_IMAGE MEDIA_TYPE_VIDEO
media_urlUnencrypted media downloadable url
thumbnail_urlUnencrypted 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 :

  1. A spotlight
  2. A snap from a public story
  3. A media

HTTP Request

POST https://businessapi.snapchat.com/v1/public_profiles/\{profile_id}/saved_stories

Parameters

ParameterRequiredDescriptionPossible Values
saved_storiesYesA 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 momentRefer to the Saved Story table below

Saved Story

FieldDescriptionPossible Values
snap_sourcesList 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
titleA title for the saved story. Limited to 45 characters

Sanp Source

FieldDescriptionPossible Values
snap_idIf 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_idIf 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_idIf 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

FieldDescriptionPossible Values
request_idUUID of the requestUUID
request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
saved_storiesList of sub responses which contains Saved Stories
debug_messageDebug information string if request_status is ERROR or Partial
display_messageDisplay information string if request_status is ERROR or Partial
error_codeError 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

ParameterRequiredDescriptionPossible Values
profile_idYesthe profile id in the url pathUUID
limitNoPage size of returned spotlights. If not specified, default is 10Integer that is bigger than 0
cursorNoCursor for next page of spotlights. Default is empty

HTTP Response

FieldDescriptionPossible Values
request_idUUID of the requestUUID
request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
spotlightsList of sub responses. Each sub response contains a SpotlightRefer to the Spotlights table below
pagingNext page information if exists
debug_messageDebug information string if request_status is ERROR or Partial
display_messageDisplay information string if request_status is ERROR or Partial
error_codeError code string if request_status is ERROR or Partial

Spotlights

FieldDescriptionPossible Values
sub_request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
spotlightSpotlight metadata object
sub_request_error_reasonError reason string if sub_request_status is ERROR or Partial

Spotlight

FieldDescriptionIs PublicPossible Values
idID of the spotlightY
profile_idUUID of the profile the spotlight belongs toY
thumbnail_urlThe spotlight’s thumbnail urlY
media_urlThe spotlight’s media urlY
created_atCreation timestampY
statusStatus 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
durationDuration of the spotlight in seconds
titleThe title of the spotlightY
captionThe caption of the spotlight. This would also include any mentions.Y
hashtagsArray 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
sponsorThe 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_tagsThe 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

ParameterRequiredDescriptionPossible Values
profile_idYesthe profile id in the url pathUUID
spotlight_idYesthe spotlight id in the url path

HTTP Response

FieldDescriptionPossible Values
request_idUUID of the requestUUID
request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
spotlightsList of sub responses. Each sub response contains a SpotlightRefer to the Spotlights table in the “Get Spotlights by Profile ID” section
debug_messageDebug information string if request_status is ERROR or Partial
display_messageDisplay information string if request_status is ERROR or Partial
error_codeError 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 nameRequiredDescriptionPossible Values
media_idRID of the media which is to be used for spotlight posting
skip_save_to_profileOIf set to true, the spotlight will not be shown on the public profile. The default value is false.true false
descriptionOThe spotlight’s description can be up to a 160 characters and can include hashtags
localeRLocale indicates the language and country. Example : en_US

HTTP Response

NameDescriptionPossible Values
request_idA UUID to identify this request.
request_statusSUCCESS / ERROR
spotlight_idThe ID of the posted spotlight
debug_messageA debug message to help debug if there is an error
display_messageDisplay message if there is an error.
error_codeError 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.

Lenses

Lenses can be retrieved in batch, by profile ID. or individually by the lens ID.

Lens Entity

FieldDescriptionIs PublicPossible ValuesPossible Values
idUUID of the lensYUUID
profile_idUUID of the profile the lens belongs toYIntegers that is bigger than 0
nameLens nameY
icon_urlUrl for the icon of the lensY
statusStatus of the lensLENS_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_atLast updated timestamp
updated_byLast updated user/app name
snapcodeSnapcode for the lensYRefer to the snapcode table below
preview_mediaLens media preview dataYRefer to the preview media table below
rejection_errorsOptional if lens is no rejectedRefer to the rejection errors table below
created_atCreation timestamp of the lensY

Snapcode

FieldDescriptionIs PublicPossible Values
image_urlUrl of the snapcode imageY
deeplinkDeeplink urlY
expires_atSnapcode expire date
statusStatus of the snapcodeSNAP_CODE_STATUS_UNSET SNAP_CODE_STATUS_TEMPORARY SNAP_CODE_STATUS_DONE

Preview Media

FieldDescriptionIs PublicPossible Values
thumbnail_media_urlUrl of the thumbnail mediaY
thumbnail_media_poster_urlUrl of the thumbnail media posterY
standard_media_urlUrl of the standard media
standard_media_poster_urlUrl of the standard media poster
media_statusStatus of the mediaMEDIA_STATUS_IN_REVIEW MEDIA_STATUS_OK MEDIA_STATUS_INVALID MEDIA_STATUS_REJECTED

Rejection Errors

FieldDescriptionPossible Values
headingRejection’s heading
messagesList of rejection messages
violating_componentsList 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

ParameterRequiredDescriptionPossible Values
profile_idYesthe profile id in the url pathUUID
limitNoPagination limit size of returned lenses. If not specified, default is 10Integers that is bigger than 0
cursorNoPagination encoded cursor for next page of lenses. Default is empty

HTTP Response

FieldDescriptionPossible Values
request_idUUID of the requestUUID
request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
lensesList of sub responses which contains lensesRefer to the Lenses table below
pagingNext page information if exists
debug_messageDebug information string if request_status is ERROR or Partial
display_messageDisplay information string if request_status is ERROR or Partial
error_codeError code string if request_status is ERROR or Partial

Lenses

FieldDescriptionPossible Values
sub_request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
lensLens metadata objectRefer to the Lens entity
sub_request_error_reasonError 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

ParameterRequiredDescriptionPossible Values
profile_idYesthe profile id in the url pathUUID
lens_idYESThe lens id in the url pathUUID

HTTP Response

FieldDescriptionPossible ValuesPossible Values
request_idUUID of the requestUUIDUUID
request_statusString to indicate the request statusSUCCESS ERROR PARTIALUUID
lensesList of sub responses which contains lenses
debug_messageDebug information string if request_status is ERROR or Partial
display_messageDisplay information string if request_status is ERROR or Partial
error_codeError code string if request_status is ERROR or Partial

Lenses

FieldDescriptionPossible Values
sub_request_statusString to indicate the request statusSUCCESS ERROR PARTIAL
lensLens metadata objectRefer to the Lens entity
sub_request_error_reasonError 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

AttributeDescriptionRequiredPossible values
sharing_policy_idid of the sharing_policies entity-Read-only attribute
sourceresource to be sharedRsee source attribute
targetentity that resource should be shared withRsee target attribute
parent_policy_idused when sharing resources with an Organization outside of the Organization where the resource livesO

source attribute

AttributeDescriptionRequiredPossible values
resource_idthe id of the resourceRid of the entity that is being shared
resource_typethe type of the resourceRpixels,public_profiles

target attribute

AttributeDescriptionRequiredPossible values
resource_idthe id of the entityRid of the entity that the source is to be shared with
resource_typethe type of the entityRadaccounts,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

ParameterDefaultDescription
resource_typeOne 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

ParameterDefaultDescription
resource_typeOne of pixels/public_profiles/catalogs
resource_idthe id of the resource

Body Parameters

ParameterDefaultDescription
sharing_policiesthe 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

ParameterDefaultDescription
resource_typeOne of pixels/public_profiles/catalogs
resource_idthe id of the resource

Body Parameters

ParameterDefaultDescription
sharing_policiesthe 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

ParameterDefaultDescription
resource_typeOne of pixels/public_profiles/catalogs
resource_idthe id of the resource

Body Parameters

ParameterDefaultDescription
parent_policy_idthe sharing_policy_id for the resource established when the resource was shared to the Organization
sharing_policiesthe 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

ParameterDefaultDescription
sharing_policy_idThe 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"
}
Was this page helpful?
Yes
No

AI-Powered Search