API Patterns

The API has a consistent pattern for requests.

Get Many Entities

Pattern:

GET /v1/\{PLURAL_PARENT_ENTITY_NAME}/\{PARENT_ENTITY_ID}/\{PLURAL_ENTITY_NAME}

Example:

GET /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns

Get a Single Entity

Pattern:

GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}

Example:

GET /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca

Pagination

Pattern:

GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}?limit={value between 50 - 1000}

Example:

GET /v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?limit=50

Example Request & Response

curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?limit=50" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b3f92d000ff0943024587937a0001737e616473617069736300016275696c642d33346664346130642d312d3138322d320001010d",
    "paging": {
        "next_link": "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?cursor=CnEKFgoJY3JlYXRlZEF0EgkIoLnp8JLP0QISU2oKc35hZHNhcGlzY3ItCxIDQWRzIiQzMmFkZmYzMC1iNDk0LTQ4NWQtODMwYi04MjZlNDAzZTVkNjgMogEVYWQtbWFuYWdlci1wcm9kdWN0aW9uGAAgAQ&limit=50"
    },
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "8ade8ef7-0cde-4eaa-bde6-990133575229",
                "updated_at": "2018-04-04T00:59:02.774Z",
                "created_at": "2018-04-04T00:56:35.051Z",
                "name": "Test",
                "ad_squad_id": "4c8e53c2-1747-4b50-a8a8-8200fe75aac5",
                "creative_id": "6ad4e432-f679-4a9b-af1d-c5781212dd75",
                "status": "ACTIVE",
                "type": "SNAP_AD",
                "review_status": "APPROVED"
            }.
            {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "32adff30-b494-485d-830b-826e403e5d68",
                "updated_at": "2017-07-31T21:34:50.311Z",
                "created_at": "2017-01-19T21:26:02.020Z",
                "name": "happy time in 910 2",
                "ad_squad_id": "33a7ea1e-6413-4bb7-a4ac-35b0a258681e",
                "creative_id": "9e37d1ee-5f27-45ff-8317-ab35a57a5bf4",
                "status": "PAUSED",
                "type": "SNAP_AD",
                "review_status": "APPROVED"
            }
        }
    ]
}

For calls that fetch many entities we recommend that you use pagination. The limit parameter specifies how many entities should be returned per page.

The returned result will contain a paging attribute, this in turn holds a next_link attribute which holds the API call to fetch the next page. Paginated calls are ordered by the attribute CreatedAt, non-paginated calls are unsorted.

Paginated calls are supported for these requests;

• Get all Ads under an Ad Account/Campaign/Ad Squad
• Get all Ad Squads under an Ad Account/Campaign
• Get all Campaigns under an Ad Account
• Get all Creatives under an Ad Account
• Get all Media under an Ad Account
• Get all Ad Accounts under an Organization
• Get all Audience Segments under an Ad Account
• Get all Mobile Apps under an Organization
• Get all Billing Centers under an Organization
• Get all Pixels under an Organization
• Get all Interaction Zones under an Ad Account
• Get all Dynamic Templates under an Ad Account
• Get Zipcode targeting options
• Get Audit logs

Parameter	Required	Description
limit	O	integer, min 50, max 1000

Entity Request Limits

Whilst the Create and Update endpoints support the creation/editing of several objects in a single POST request there is a limit to the number of entities that can be created/edited in a single request.

Entity type	Create/Update limit per Request
Creative	10
Media	10
Organization	15
Ad Account	15
Segments	15
Campaign	30
Ad Squad	30
Ad	30

Create One or More Entities

The Create endpoints support bulk creation, meaning you can create several objects at the same time as long as they share the same parent. For example, you can create muliple Campaigns within a single Ad Account in a single POST request.

Pattern:

POST /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}

Example:

POST /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns

Update One or More Entities

The Update endpoints support bulk update, meaning you can update several objects at the same time as long as they share the same parent. For example, you can update muliple Campaigns within a single Ad Account in a single PUT request.

Pattern:

PUT /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}

Example:

PUT /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns

IMPORTANT! The API expects the entire object when updating any fields. Omitting attributes that have default values will reset those attributes to the default.

Delete a Single Entity

Pattern:

DELETE /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}

Example:

DELETE /v1/campaigns/0be21d8a-2720-4668-9576-0fa566a6ff55

IMPORTANT! Deleted objects cannot be undeleted.

Sorting parameter

Several entities support a sorting parameter that allows entities to be sorted either by when they were created or when they were most recently updated.

Rather than having to iterate through a big data set to find the last updated entities, this parameter allows you to have entities returned in the created/last updated order, this returned set of data can then be compared to a specific date to find entities that were all created/edited given a specific time frame, eliminating the need to fetch all entities and iterate through every single entity.

Supported entities: Ad Squads, Ads, Creatives and Media.

Parameters: sort=updated_at-desc , sort=created_at-desc

Note: The sort parameter can be used on its own or alongside the limit parameter. The sort parameter cannot be used with the following parameters, type, review_status or read_deleted_entities

Endpoint availability

Name	Entity	Endpoint
Fetch all Ad Squads under an Ad Account	Ad Squad	GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/adsquads
Fetch all Ad Squads under a Campaign	Ad Squad	GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
Fetch all Ads under an Ad Account	Ad	GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads
Fetch all Ads under a Campaign	Ad	GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/ads
Fetch all Ads under an Ad Squad	Ad	GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Fetch all Media under an Ad Account	Media	GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media
Fetch all Creatives under an Ad Account	Creative	GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives