Skip to main content

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
ParameterRequiredDescription
limitOinteger, 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 typeCreate/Update limit per Request
Creative10
Media10
Organization15
Ad Account15
Segments15
Campaign30
Ad Squad30
Ad30

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

Delete a Single Entity​

Pattern:

DELETE /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}

Example:

DELETE /v1/campaigns/0be21d8a-2720-4668-9576-0fa566a6ff55
Was this page helpful?
Yes
No