Get Started
Requirements
- Step 1 - Activate access to the Snap Marketing API
Follow the instructions to create a business account and then create an OAuth app. - Step 2 - Activate access to the Public Profile API
The Public Profile API is currently allowlist only. Once you have created your OAuth app. Send just the client ID to your Snap contact and they will coordinate allowlisting your app. - Step 3 - Receive Official Public Profile IDs
The endpoint to retrieve all official public profiles is not yet available. However, once you complete Step 2 we can provide a static dump of all Public Official Creator Profile IDs. Additionally, we can continue to provide delta files on an agreed upon interval until the endpoint to retrieve all official public profiles becomes available. - Step 4 - Utilize the released discovery endpoints with the Public Profiles IDs that were provided in the static dump.
Access Request
This API requires allow listing to access. Once you have obtained app credentials, send an email to bpp-api-access@snapchat.com with your OAuth client id and a description of your intended use. Please do not send your client secret.
Authentication
The Snapchat Marketing API uses access tokens to control access and authenticate requests, the access token will reflect the user permissions when used in API requests. The access token should be included in all API requests to the server in the Authorization header in the following way:
Authorization: <ACCESS_TOKEN>
OAuth Set Up Steps
This section provides comprehensive instructions on setting up and using the Public Profile API, designed to help you maximize your engagement and effectiveness on Snapchat.
Public vs Authorized Endpoints
Public Endpoints : These endpoints do not require profile owner authorization and are crucial for accessing basic metadata and stats about any Public Profile on Snapchat. They return only a subset of publicly available information. These endpoints share a common public prefix, such as /public/v1/[PLURAL_PARENT_ENTITY_NAME]. Authorized Data Sharing: Partners can access detailed data about creators through two ways:
- Creator OAuth: Creators authorize data sharing via OAuth, allowing API partners to access a subset of endpoints specific to their profiles without requiring individual authorization.
- Opt-in Data Sharing: Creators may choose to share their insights publicly, facilitating access to authorized data without individual profile owner authorization.
Prerequisites For Using The Public Profile API
To use the Public Profile API effectively, you will need an access token for every API request. This token represents the user making the request.
Setting Up the Access Token: Required Items
- The Public Profile API is currently allowlist only. Once you have created your OAuth app. Send just the client ID to your Snap contact and they will coordinate allowlisting your app.
- A Snapchat Account: This should be an account where credentials are shared across your development team. If you use a personal account, you run the risk of the application ceasing to work if the associated user leaves your company.
- A Business Account (Organization) with Snap: This account is necessary for managing API access at a corporate level.
- An OAuth App: Set up within your organization: It is advisable to read this complete guide before setting up the OAuth App, as you will need to decide on a redirect_uri to use.
- A Software Tool: Such as Postman, Fiddler, or any application that allows you to send HTTP requests to our API servers.
Setting up the OAuth App
- Create a Snapchat user by downloading the mobile iOS or Android application from here.
- Visit account center and log in with your new user credentials.
- Navigate to the Ads Manager and create a business account.
- Once logged into the Ads Manager, click on "Business Dashboard" in the top menu.
- Select Business Details from the side panel to generate an OAuth App as shown below:
- Substitute the client_id and redirect_uri in the this link, and open it in your browser.
- Click on Continue. You will then be redirected to the redirect_uri as shown below:
- Copy the code from the url in the browser as shown below:
At this stage, you should have obtained a client_id, client_secret, code, and redirect_uri, which are necessary to generate access tokens.
Generating an Access Token
Please follow the following steps to generate an access token that can be used to query the public endpoints of the Public Profile API.
Example Request
curl -X POST \
-d "grant_type=authorization_code" \
-d "client_id=7eacd8be-d6ac-41df-9129-c0f75a2c642d" \
-d "client_secret={your_client_secret}" \
-d "code=9-fpi16xIN8JNZCv2ZeAxR95jE94YTqvdJ8kqmXCJTc" \
-d "redirect_uri=https://www.example.com/" \
https://accounts.snapchat.com/login/oauth2/access_token
Example Response
{
"access_token": "eyJpc3MiOiJodHRwczpcL1...TruHKTAUIh2XMxWvapkbyw",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "hCgwKCjE3MTAxODAwMTUS...JWAer2MQWUbHiyItFSav-M",
"scope": "snapchat-profile-api"
}
Make sure to store the access token and refresh token in your backend and use it in your backend to make calls to the endpoints of our API.
Refreshing an Access Token
Maintaining continuous access to Snapchat's Public Profile API is crucial for ongoing operations and data retrieval without interruption. This section details the process for refreshing an access token once it expires. Access tokens are designed with a limited lifespan to enhance security, requiring a refresh to extend their validity. By following these instructions, you can ensure that your application retains active and authorized access to both public and authorized endpoints, allowing uninterrupted management and analysis of Public Profile data.
Example Request
curl -X POST \
-d "refresh_token={refresh_token}" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "grant_type=refresh_token" \
https://accounts.snapchat.com/login/oauth2/access_token
Example Response
{
"access_token": "eyJpc3MiOiJodHRwczpcL1...upvJnQSoQ",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "hCgwKCjE3MTAxODA...wMTUSowFTK173WIy",
"scope": "snapchat-profile-api"
}
More information on refreshing access tokens can be found here.
Querying Public Profile API /Public Endpoints
The /public endpoints of the Public Profile API do not require authentication from individual users. Please follow the steps in the “Setting up the OAuth App” section if you only want to interact with public endpoints.
An example of a public endpoint is the Get Profile by Profile ID, which can be accessed without user authorization.
Example Request
curl "https://businessapi.snapchat.com/public/v1/public_profiles/76da494b-76bc-4bbb-bb27-c5a66fb0d1ab" \
-H "Authorization: Bearer eyJpc3MiOiJodHRwczpcL1...upvJnQSoQ"
Example Response
{
"request_id": "e52d33c1-73e4-48d4-bbaa-aa24a2afd2e2",
"request_status": "SUCCESS",
"public_profiles": [
{
"sub_request_status": "SUCCESS",
"public_profile": {
"id": "76da494b-76bc-4bbb-bb27-c5a66fb0d1ab",
"display_name": "Daily Question",
"category": "CATEGORY_V3_PEOPLE",
"subcategory": "SUBCATEGORY_V3_SCIENTIST",
"logo_urls": {
"original_logo_url": "https://cf-st.sc-cdn.net/d/vPpycEULnWA2vZK4mFVcJ?bo=Eg0aABoAMgEESAJQGWAB&uc=25",
"discover_feed_logo_url": "https://cf-st.sc-cdn.net/aps/bolt/aHR0cHM6Ly9jZi1zdC5zYy1jZG4ubmV0L2QvdlBweWNFVUxuV0EydlpLNG1GVmNKP2JvPUVnMGFBQm9BTWdFRVNBSlFHV0FCJnVjPTI1._RS0,72_FMjpeg",
"mega_profile_logo_url": "https://cf-st.sc-cdn.net/aps/bolt/aHR0cHM6Ly9jZi1zdC5zYy1jZG4ubmV0L2QvdlBweWNFVUxuV0EydlpLNG1GVmNKP2JvPUVnMGFBQm9BTWdFRVNBSlFHV0FCJnVjPTI1._RS0,90_FMjpeg",
"manage_profile_logo_url": "https://cf-st.sc-cdn.net/aps/bolt/aHR0cHM6Ly9jZi1zdC5zYy1jZG4ubmV0L2QvdlBweWNFVUxuV0EydlpLNG1GVmNKP2JvPUVnMGFBQm9BTWdFRVNBSlFHV0FCJnVjPTI1._RS0,640_FMjpeg"
},
"country": "US",
"snap_user_name": "dailyquestion1",
"profile_tier": "TIER_PUBLIC",
"internal_profile_category": "BUSINESS",
"subscriber_count": "409"
}
}
]
}
More on the API can be found here.
Querying Public Profile API Authorized Endpoints
To access public profile data about creators and brands through authorized endpoints, partners must first obtain authorization from these creators. This process involves sending a specific authorization URL to creators, which they must visit to grant permissions.
- Generate the Authorization URL:
- Similar to what we did in the “Setting up the OAuth App” section, construct the authorization URL with the necessary parameters such as client_id, redirect_uri, response_type='code', and scope. Include a unique state parameter to safeguard against CSRF attacks.
Example
https://accounts.snapchat.com/login/oauth2/authorize?response_type=code&client_id={your_client_id}&redirect_uri={your_redirect_uri}&scope=snapchat-profile-api&state={unique_state}
- Send the Authorization URL to the Creator
- Communicate this URL to the creator using a secure method, ensuring they understand the need to authorize your application to access specific data.
- Note: you can also follow these steps to add a Snapchat login button on your web application.
- Creator Grants Authorization
- Upon visiting the URL, the creator will authenticate and be prompted to authorize your application. Upon consent, Snapchat redirects them to your specified redirect_uri, including an authorization code in the URL.
- Capture the Authorization Code
- Your application must capture this code from the redirect URI to proceed with obtaining the access token from the user.
- Request an Access Token
- Similar to the steps in the “Setting up the OAuth App” section, exchange the authorization code for an access token by making a POST request to Snapchat's token endpoint. This access token is essential for making requests to the authorized endpoints.
Example POST request
curl -X POST \
-d "grant_type=authorization_code&code={authorization_code}&redirect_uri={your_redirect_uri}&client_id={your_client_id}&client_secret={your_client_secret}" \
https://accounts.snapchat.com/login/oauth2/token
- Use the Access Token
- With the access token, your application can now query authorized endpoints to retrieve or interact with the protected data, leveraging the capabilities for comprehensive insights into creator activities and audience metrics.
This process ensures secure and authorized access to sensitive creator data, supporting your application's needs for analytics and content management from Snapchat.
Troubleshooting Set Up
-
Why am I receiving an Internal Server Error 500 when trying to retrieve snaps by story ID?
The error occurs because the request is processing too much data, leading to a timeout. You can resolve this issue by specifying the created_at and ended_at parameters in your request. This approach limits the data range, ensuring the query is manageable and efficient. For example, to access Snaps from May 1st to May 15th, 2024, your request would look like this:GET https://businessapi.snapchat.com/v1/public_profiles/c3aa5dcf-8538-4f4f-8f00-117466b8cfda/stories/8e85d9b8-fd14-593c-9df5-2deb5c9d4566/snaps?created_at=2024-05-01T00:00:00Z&ended_at=2024-05-15T00:00:00Z
Incorporating these parameters helps prevent timeouts by focusing the search within a specific timeframe.
-
Why am I receiving a 403 "AUTHORIZATION_PERMISSION_DENIED" error when accessing the API?
The AUTHORIZATION_PERMISSION_DENIED error indicates that your request lacks the necessary permissions or access rights. Here are a few steps to resolve this issue:- Check Allowlist Status: Ensure that your client ID is allowlisted for the Public Profile API. If it's not, you'll need to request allowlisting by contacting support
- Endpoint Access: Verify whether you are accessing a public or authorized endpoint. Public endpoints generally do not require additional permissions, whereas authorized endpoints need specific access rights or an OAuth token.
- Data Sharing and OAuth Token: For authorized endpoints, check if the creator has enabled data sharing or if you need an OAuth token. Ensure that the OAuth token is correctly included in your request if required.