FAQ

Setting up your app

Can I use this API without a redirect url?

You cannot use this API without a redirect_uri, but this part of the API is only used for authentication. part, it's fully possible for you to carry out the authentication part only once per user of the API.

How can I edit an existing redirect_url

You cannot edit an existing redirect_uri instead you will need to set up a new app with the redirect_uri that you wish to use.

Can I use this API to make server to server requests?

Yes, only the user authorization process of this API requires you to use a client (browser), this is needed in order to obtain the tokens that makes it possible to query the API (Access token and Refresh token). Once you have these two tokens, you can use them alongside your API client specific details in order to query the API in a server to server fashion.

What should the redirect url be? Do you have any rules around it?

The redirect URL should be a SSL hosted URL you control, or that you can set up. The purpose of the URL is to pass the code parameter which you will need in order to set up your first access token and refresh token.

You may choose to just copy the code out of a browser and then set up the tokens using a tool like POSTMan, or you might choose to build an application that is hosted on the redirect_uri itself, where the application will read the GET code parameter and then generate the tokens.

For example, let's say you specify this redirect URL: https://www.example.com/index.html

After successful authentication the code parameter will be attached on the end of the URL the following way: https://www.example.com/index.html?code=1234567890

• If you are building a Web based tool using a UI where several users will log in to fetch data via the API it might make sense to make the redirect URL part of your application, and let the application fetch and read the GET parameter and then automatically proceed to the next step where the Application generates an access and refresh token for the user.
• If you are building a "server to server" application, then you could specify any URL you control and that can display a GET parameter so that you may manually copy and save the code parameter from the URL and then execute the next step manually, using software such as POSTMAN.

A step-by-step instruction for the full Authentication process can be found here: Authentication Guide

I can't see OAuth apps section in Business Manager*

• The user account which you are logged into needs to be an Organization admin
• The URL where the Oauth App Dashboard can be found on the following URL where YOUR_ORGANIZATION_ID needs to be replaced with your Organization ID: https://business.snapchat.com/YOUR_ORGANIZATION_ID/settings/business-details

User Permissions and OAuth

When does the Access token and the Refresh token expire?

The refresh token does not expire, but will cease to function if the user it is tied to has their access removed.

The access token has an attribute expires_in which specifies the duration in seconds, a new access token will be valid for 3600 seconds = 60 minutes.

Do I need to generate a new access token if my user gets added to a new Organization/Ad Accounts?

No, the access token is specific to the Snapchat account used, so if ad accounts are added or removed, it is reflected without the need to generate new tokens. However if you are added to a new Organization you will need to accept the invitation in the Welcome email.

We previously had access to the Ads API but lost access after the user who set it up left

It’s possible that the employee used their own account when setting up the Access and Refresh token. If this is the case you need to generate new tokens, for a user account which you need to maintain and store the details for so that they do not get lost if an employee leaves your company.

• You will need to set up a new Snapchat account for this purpose

• You will need to log in with a user that has the Organisation Admin role at https://business.snapchat.com

• That user will be able to invite the new Snapchat account to the Organization and assign an appropriate Role based on the actions you want to carry out via the Snap Ads API, Roles and Permissions

• Note that if you use the Organisation Admin role for the new Snapchat account this role comes with powerful permissions as it can Create/Edit/Delete entities in any of the Ad accounts under the org.

How do I revoke access for an App?

You need to log in to the Snapchat account which has authorised the OAuth App access in order to revoke the access for that App.

1. Navigate to this URL in a browser https://accounts.snapchat.com
2. Log in as the user that granted access to the OAuth App in question
3. Choose MANAGE APPS from the menu you are presented with https://accounts.snapchat.com/accounts/welcome Alternatively access the page directly by using this url https://accounts.snapchat.com/accounts/oauth2/apps
4. The page will show you a list of all Applications that has been authorised to use your Ads API permissions on your behalf.
5. Delete the app in question from the list.

Making API requests and interpreting responses

Can I use the Python requests library

Yes, however when using the Python requests library to upload Media files you need to remove one of the headers.

When using the Python requests library to upload files you should not include the header Content-Type':'multipart/form-data

When setting the headers in requests this should be sufficient:
headers = {'Authorization': 'Bearer ACCESS_TOKEN'}

Is the updated_at attribute on Ad level affected by Ad Review?

Yes it is, the updated_at attribute is updated when the review status of the Ad changes.

When requesting an entity I get the error message "Resource can not be found - error_code: E3003" what does it mean?

This type of error message (E3003) shows up in two different situations:

• The user/token making the request does not have permission to access the resource.
• The entity requested in the request doesn't exist, this means either the entity was deleted or the entity ID hasn't been entered correctly.

Was the entity deleted or misspelled?

To check if the entity has been deleted you can use the Audit logs for the entity in question. Audit logs are available for Campaigns/AdSquads/Ads/Creatives; Audit Logs

• If you can request the Audit logs successfully for the entity you will be able to see the actions taken on this entity, if the entity has been deleted then the final action on the entity will be; "action": "DELETED"

• If the Audit log request was successful, but all you get is an empty array, there is a possibility that the entity was deleted before audit logs were made available.

• If the Audit log request was rejected with a "error_code": "E3002" response it means you do not have permissions to access the Audit logs for the given entity.

This response means you do not have permission to access the Audit logs for the given entity

{
  "request_status": "ERROR",
  "request_id": "UNIQUE_ID",
  "debug_message": "None of the requested actions READ_CHANGE_LOG_RECORDS can be authorized. Current user principal: MEMBER_ID",
  "display_message": "We're sorry, but the requested resource is not available at this time",
  "error_code": "E3002"
}

• If the Audit log request was rejected with a "error_code": "E3003" response it means the entity ID is incorrect, in other words there has never been an entity with that ID.

This response means the entity ID is incorrect, there has never been an entity with this ID

{
  "request_status": "ERROR",
  "request_id": "UNIQUE_ID",
  "debug_message": "Resource can not be found",
  "display_message": "We're sorry, but the requested resource is not available at this time",
  "error_code": "E3003"
}

Do you have permission to the Ad Account where the entity lives?

Assuming you know the Ad Account that you are attempting to access, you can carry out the following checks.

This request shows which user the token represents, and the Organizations that the User is a Member of, the request is fully described in the User section.
GET https://developers.snapchat.com./user

This request will show you the Ad Accounts and the roles the user has within those Ad Accounts.
GET https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts?true

The User permission request is explained in our section on fetching all Organizations with Ad Accounts.

If the user doesn’t have access to the Ad Account they are attempting to access it's possible for an Organization Admin to add them via Snap Business Manager.

If the user in question has access to the Ad Account already, but has got incorrect permissions, you can amend their Role to match the permissions they need to carry out the intended task.

Fetching Reporting via the API

What Role do I need to fetch Campaign reporting from an Ad Account?

• The user in question needs to be a Member of the Organization where the Ad Account lives, this also means they have to accept the invitation which is sent to the Member email
• The user also needs to be a Member of the Ad Account
• The user also needs to have the Role type reports in the Ad Account

This can be managed by using the API for Members and Roles, or it can be handled within Snap Business Manager where the role is referred to as Data Manager.

Is there a way to get dummy data from the API whilst developing my reporting App?

Yes, you can get dummy data if you add test=true to any reporting API request, that will return dummy data.

My daily reporting job has started failing.

If your reporting was working, and then suddenly started failing, there is a possibility that daylight savings are the cause of this.

When you make your request to the API you need to take into account that we save all our timings in UTC, so you will need to add/subtract hours in order to make up a 24 hour period that corresponds to the setting in your Ad Account.

If we assume an account is set to Europe/Berlin (Central European Time). During daylight savings Europe/Berlin will be +1 hour ahead of UTC, prior to Daylight savings Europe/Berlin will be +2 hours ahead of UTC.

This means that if you added 2 hours to your start_time and end_time during the daylight savings period, you will now need to add just 1 hour to the start_time and end_time once daylight savings are

In the situation that you request a report where the start_time is in a period when daylight savings were active, and where the end_time is in the period where daylight savings ended you will need to +2 hours to the start_time and +1 hour to the end_time.

You should take daylight savings into account for your application when structuring reporting requests.

How do metrics in the Snap Ads Manager map to fields in the Snap Marketing API?

The following table shows how some of the common metrics in the Snap Ads Manager translate to fields in the Marketing API. Calculated Metrics in the Snap Ads Manager do not directly map to fields in the Marketing API. A description of how these metrics are calculated in the Ad Manager can be found in the Notes column.

Ads Manager Metric	Marketing API Field	Metric Type	Notes
Start Time	start_time	Entity Attribute	Ad squad attribute
End Time	end_time	Entity Attribute	Attribute in campaign and ad squad object
ID	id	Entity Attribute	The entity ID for a campaign, ad squad or ad object
Campaign/Ad Squad/Ad Name	name	Entity Attribute	The entity name for a campaign, ad squad, or ad object.
Status	status	Entity Attribute	The entity status for a campaign, ad squad, or ad object.
Spend	spend	Raw Metric
Paid Reach	uniques	Raw Metric
Paid Impressions	impressions	Raw Metric
Paid Frequency	frequency	Raw Metric
Paid eCPM	-	Calculated Metric	Effective cost per thousand impressions. Calculated by taking the average cost for every 1,000 impressions.
Swipe Ups	swipes	Raw Metric
Swipe Up Rate	-	Calculated Metric	The average number of swipes per impression. Shows as a percentage.
eCPSU	-	Calculated Metric	Effective cost per swipe up. Calculated by taking the average cost per each swipe up.
Video Views	video_views	Raw Metric
eCPV	-	Calculated Metric	Effective cost per video view. Calculated by taking the average cost per qualified video view.
Completions	view_completion	Raw Metric
Avg Screen Time	-	Calculated Metric	The average number of seconds spent watching your ad across all paid impressions.
ROAS	-	Calculated Metric	Return on ad spend. The value of generated sales relative to your media spend.
Attachment Frequency	attachment_frequency	Raw Metric
Attachment Reach	attachment_uniques	Raw Metric
Purchases Value	conversion_purchases_value	Raw Metric
Purchases	conversion_purchases	Raw Metric