Skip to main content

Onboarding

This guide covers what's specific to MMM API access: the org-level allowlist requirement, and how an advertiser grants your org access to a shared ad account.

Your org must be enabled for MMM API access by your Snap point of contact. This is separate from (and required in addition to) the per-account sharing described below. If your org isn't enabled, report requests return a 404. Speak to your Snap representative to get your org allowlisted.

Set up your org​

Before you can call the MMM API, you need a Snap Business organization, an OAuth app registered with the snapchat-marketing-api scope, and a valid access/refresh token pair. See Getting Started and Authentication for how to set these up.

One thing specific to MMM: your access token isn't tied to specific ad accounts; access follows the roles assigned to the calling user. When an advertiser shares a new account and your org assigns the Data Analyst role (see below), your existing token gets access immediately, so you don't need to re-authorize.

Once your org is set up and enabled for MMM API access, see Request and download reports to start pulling data as soon as an advertiser has shared an account.

Add an advertiser​

Repeat these steps for each advertiser you onboard.

Step 1: Give your organization ID to the advertiser​

Send your organization_id to the advertiser. A share is between two organizations, not individual users; one share gives access to every member of your org who holds a role on the account.

Step 2: The advertiser shares an ad account​

The advertiser (as an Organization Admin of their own org) does this step in Business Manager. There's no public API for granting a cross-org ad account share; it's UI-only.

Business Details → Ad Accounts → Account Sharing → Share Ad Account → select your organization → select the account(s) and set the access tier to View → submit.

The share is active immediately. View tier is read-only and is the correct tier for the MMM API.

Step 3: Assign the Data Analyst role​

This step happens in your org and is what actually grants your users access. The share alone does not.

UI: In your org, go to Ad Accounts → Account Sharing → Shared In tab → find the advertiser org → Manage → select the member → assign the Data Analyst role.

API: Use the standard Create Ad Account Role endpoint with "type": "reports":

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{"roles": [{"member_id": "{member_id}", "ad_account_id": "{ad_account_id}", "type": "reports"}]}' \
  https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/roles

In the UI this role is labeled Data Analyst; in the API it's the reports role. Both grant exactly the read access the MMM API needs—no more. If no member holds this role on an account, calls against that account return a 403.

Revocation​

If the advertiser removes the share from their Business Details UI, your org's access to that account stops immediately on the next API call. No token rotation is needed on your end.

Was this page helpful?
Yes
No