Skip to main content

Ad Accounts

An Ad Account is owned by an Organization and contains Ad Campaigns. Ad Accounts have one or more Funding Sources (Credit card, Paypal, Lines of Credit etc).

Attributes

AttributeDescriptionRequiredPossible Values
advertiserName of the AdvertiserRUser input
currencyAccount currencyRAUD, DKK, CAD, EUR, GBP, NOK, SEK, USD
funding_source_idsArray of Funding Source IDsR
billing_typeType of billingRIO, REVOLVING
nameAccount nameRUser input
organization_idOrganization IDR
testIndicates Ad Account is a test ad account, test ad accounts can never serve live adsOtrue
timezoneAccount timezone, remember to take the time differences into account when you set up your application. All our timings are stored in UTC which means you are required to add/remove hours to make up a full 24 hours when using the DAY granularity in the APIRAfrica/Cairo, Africa/Johannesburg, America/Anchorage, America/Cancun, America/Chicago, America/Dawson, America/Dawson_Creek, America/Denver, America/Edmonton, America/Halifax, America/Hermosillo, America/Los_Angeles, America/Mazatlan, America/Mexico_City, America/Montevideo, America/New_York, America/Phoenix, America/Rainy_River, America/Regina, America/Tijuana, America/Toronto, America/Vancouver, Asia/Amman, Asia/Beirut, Asia/Dubai, Asia/Hong_Kong, Asia/Irkutsk, Asia/Jerusalem, Asia/Kamchatka, Asia/Krasnoyarsk, Asia/Magadan, Asia/Nicosia, Asia/Omsk, Asia/Qatar, Asia/Riyadh, Asia/Shanghai, Asia/Singapore, Asia/Vladivostok, Asia/Yakutsk, Asia/Yekaterinburg, Atlantic/Canary, Australia/Perth, Australia/Sydney, Europe/Amsterdam, Europe/Berlin, Europe/Brussels, Europe/Dublin, Europe/Helsinki, Europe/Istanbul, Europe/Kaliningrad, Europe/London, Europe/Luxembourg, Europe/Madrid, Europe/Malta, Europe/Moscow, Europe/Oslo, Europe/Paris, Europe/Rome, Europe/Samara, Europe/Stockholm, Europe/Vienna, Europe/Vilnius, Europe/Warsaw, Europe/Zurich, Pacific/Auckland, Pacific/Honolulu, UTC
typeAccount typeRDIRECT, PARTNER
lifetime_spend_cap_microRequired if billing_type is set to IO, the lifetime spend cap of the account in micro currencyO
advertiser_organization_idOrganization ID of the Advertiser selectedread-only
paying_advertiser_nameName of the paying advertiser/political entity, required if the Ad Account will contain political/advocacy adsOmax 32 characters
regulationsRequired if the Ad Account will contain ads for Credit, Housing or Employment, this attribute is immutable once set to trueO{ "restricted_delivery_signals": true }
agency_representing_clientAccount nameRtrue/false
client_based_in_countryRequired if agency_representing_client is true and if Advertiser is based in France or targeting Ads to audiences in FranceOFR
client_paying_invoicesRequired if agency_representing_client is true and if Advertiser is based in France or targeting Ads to audiences in FranceOtrue/false
agency_client_metadataClient metadata is required if agency_representing_client is true and if the Advertiser is based in France or is targeting Ads to audiences in FranceOJSON object containing the attributes; name, email, address_line_1, city,administrative_district_level_1, country, zipcode, tax_id
delivery_statusDelivery statusRead-onlySee Delivery status

Create an Ad Account

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name": "Example Ad Account","type": "PARTNER","status": "ACTIVE","organization_id": "7fdeefec-f502-4ca8-9a84-6411e0a51058","funding_source_ids": ["6ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "USD","billing_type": "IO","billing_center_id": "9b8db2a8-2b48-42f0-858a-88901a782b27","lifetime_spend_cap_micro": "200000000000","timezone": "America\/Los_Angeles","advertiser": "Example Advertiser Inc"}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "5e7b42c900ff0e76f111031c2c0001737e616473617069736300016275696c642d62313763613636652d312d3333372d3200010122",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "7c6d2e91-3a7c-4230-b048-f724bf217a82",
"updated_at": "2020-03-25T11:38:50.273Z",
"created_at": "2020-03-25T11:38:50.273Z",
"name": "Example Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"funding_source_ids": ["6ca1687a-f2b4-437d-8554-a85403a714c5"],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Example Advertiser Inc",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"billing_center_id": "9b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "IO",
"lifetime_spend_cap_micro": 200000000000,
"agency_representing_client": false,
"client_paying_invoices": false
}
}
]
}

This endpoint creates an Ad Account within the specified Organization. When setting up new Ad Accounts it's important to take the below factors into account, not following these points may cause the Ad Account to be suspended.

  • If the ad account will be used for housing, credit or employment advertising it needs to have the attribute regulations.restricted_delivery_signals set to true

  • If the ad account will be used for political advertising the attribute paying_advertiser_name needs to be filled out with the political organization or advocacy group who is paying for the ad (32 character limit)

  • If the Ad Account is owned by an agency buying ads on behalf of an advertiser the attribute agency_representing_client needs to be set to true

  • If the Ad Account is owned by an agency buying ads on behalf of an advertiser, and the Advertiser is based in France, or will target ads to an audience in France, the following settings will apply:

    • The attribute agency_representing_client needs to be set to true
    • The attribute client_paying_invoices needs to be set to true if the agency is paying the invoices, or false if the advertiser they represent is paying the invoices
    • The attribute client_based_in_country needs to be set to fr
    • The attribute agency_client_metadata needs to be set using the attributes name, email, address_line_1 , city, administrative_district_level_1, country, zipcode and tax_id

HTTP Request

POST https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts

Parameters

ParameterDefaultDescription
organization_idOrganization ID

Get All Ad Accounts

curl "https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts" \
-H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
"request_status": "success",
"request_id": "57b0015e00ff07d5c0c38928ad0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"adaccounts": [
{
"sub_request_status": "success",
"adaccount": {
"id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Hooli Test Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": ["e703eb9f-8eac-4eda-a9c7-deec3935222d"],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Hooli"
}
},
{
"sub_request_status": "success",
"adaccount": {
"id": "81cf9302-764c-429a-8561-e3bc329cf987",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Awesome Ad Account",
"type": "DIRECT",
"status": "ACTIVE",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": ["7abfb9c6-0258-4eee-9898-03a8c099695d"],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Hooli"
}
}
]
}

This endpoint retrieves all ad accounts for the specified Organization.

HTTP Request

GET https://adsapi.snapchat.com/v1/organizations/{organization-id}/adaccounts

Parameters

ParameterDefaultDescription
organization_idOrganization ID

Get a Specific Ad Account

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

The above command returns JSON structured like this:

{
"request_status": "success",
"request_id": "57b0021900ff06bbfeb44f77240001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010e",
"adaccounts": [
{
"sub_request_status": "success",
"adaccount": {
"id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Hooli Test Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": ["e703eb9f-8eac-4eda-a9c7-deec3935222d"],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Hooli"
}
}
]
}

This endpoint retrieves a specific Ad Account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}

URL Parameters

ParameterDescription
ad_account_idAd Account ID of the ad account to retrieve

Update Ad Account

curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adaccounts": [{"type": "PARTNER","advertiser": "Example Advertiser Inc","advertiser_organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd","billing_type": "IO","currency": "USD","id": "7c6d2e91-3a7c-4230-b048-f724bf217a82","lifetime_spend_cap_micro": 200000000000,"name": "Example Ad Account","organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"status": "ACTIVE","timezone": "America/Los_Angeles","agency_representing_client": false,"client_paying_invoices": false}]}'
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "5eac3e0c00ff07836d9acd3b2a0001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010137",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "7c6d2e91-3a7c-4230-b048-f724bf217a82",
"updated_at": "2020-05-01T15:19:41.536Z",
"created_at": "2020-03-25T11:38:50.273Z",
"name": "Example Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Example Advertiser Inc",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"billing_type": "IO",
"lifetime_spend_cap_micro": 200000000000,
"agency_representing_client": false,
"client_paying_invoices": false
}
}
]
}

This endpoint updates a specific Ad Account.

Attributes that can be updated

AttributeRequired
nameR
advertiserR
billing_center_idR
lifetime_spend_cap_microR
regulations.restricted_delivery_signalsR
agency_representing_clientR
paying_advertiser_nameO
client_paying_invoicesO
client_based_in_countryO
agency_client_metadataO

HTTP Request

PUT https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts

URL Parameters

ParameterDescription
organization_idOrganization ID of the Organization to which the Ad Account belongs

Update an Ad Account's Lifetime Spend Cap

curl -X PUT \
-H 'Authorization: Bearer meowmeowmeow' \
-H 'Content-Type: application/json' \
-d '{"adaccounts": [{"id":"123b9ca6-92f2-49c3-a3ed-0ea58afb467e","name":"Hooli Ad Account","type":"PARTNER","status":"ACTIVE","organization_id":"40c6719b-da09-410b-9185-0cc9c0dfed1d","funding_source_ids":["cdc67eba-a774-4954-9b94-9502bbdac1bc"],"currency":"USD","timezone":"America/Los_Angeles","brand_name":"Hooli","lifetime_spend_cap_micro":1500000000
}]}' \
https://adsapi.snapchat.com/v1/organizations/40c6719b-da09-410b-9185-0cc9c0dfed1d/adaccounts

The above command returns JSON structured like this:

{
"request_status": "success",
"request_id": "57b0021900ff06bbfeb44f77240001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010e",
"adaccounts": [
{
"sub_request_status": "success",
"adaccount": {
"id": "123b9ca6-92f2-49c3-a3ed-0ea58afb467e",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Hooli Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "40c6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": ["e703eb9f-8eac-4eda-a9c7-deec3935222d"],
"currency": "USD",
"timezone": "America/Los_Angeles",
"brand_name": "Hooli",
"lifetime_spend_cap_micro": 1500000000
}
}
]
}

This endpoint updates the Lifetime Spend Limit of a specific ad account, this can only be updated for Ad Accounts where the billing_type is set to IO. Please note that once the Lifetime Spend Limit is set for a specific ad account, it can only be increased or decreased but not removed.

Assign Funding Source

Assigning funding sources to ad accounts can be done in Business Manager. Please reach out to your partner manager for further assistance.

Ad Account creation - Example 1

Ad Account - Used for Political advertising

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name": "Votes for Dogs Account","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "GBP","timezone": "Europe/London","advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": false,"client_paying_invoices": false,"paying_advertiser_name": "The Pugs & Poodle Alliance","regulations": {"restricted_delivery_signals": false}}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "5eac0cdb00ff06d4845e8997c40001737e616473617069736300016275696c642d38653566343030352d312d3334382d300001015f",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "2b0efb26-973b-4085-aef1-bd0bef429b91",
"updated_at": "2020-05-01T11:49:48.045Z",
"created_at": "2020-05-01T11:49:48.045Z",
"name": "Votes for Dogs Account",
"type": "PARTNER",
"status": "PENDING",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],
"currency": "GBP",
"timezone": "Europe/London",
"paying_advertiser_name": "The Pugs & Poodle Alliance",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "REVOLVING",
"agency_representing_client": false,
"client_paying_invoices": false,
"regulations": {
"restricted_delivery_signals": false
}
}
}
]
}

This request creates an Ad account that will be used for Political or Advocacy Ads, it contains the attribute paying_advertiser_name.

Ad Account creation - Example 2

Ad Account - Used for Credit, Housing, Employment Ads

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name": "Account for Credit Housing Employment Ads","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "EUR","timezone": "Europe/Paris","advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": false,"client_paying_invoices": false,"regulations": {"restricted_delivery_signals": true}}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "5eac0e1600ff0abfa792ff005a320001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010153",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "f249cfe1-973f-4a04-899a-c1f65b9070a0",
"updated_at": "2020-05-01T11:55:03.343Z",
"created_at": "2020-05-01T11:55:03.343Z",
"name": "Account for Credit Housing Employment Ads",
"type": "PARTNER",
"status": "PENDING",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],
"currency": "EUR",
"timezone": "Europe/Paris",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "REVOLVING",
"agency_representing_client": false,
"client_paying_invoices": false,
"regulations": {
"restricted_delivery_signals": true
}
}
}
]
}

This request creates an Ad account that can be used for housing, credit and employment ads, the restricted_delivery_signals within the regulations attribute has been set to true.

Ad Account creation - Example 3

Ad Account - Agency representing client, client based in France or targeting France

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{ "adaccounts": [{"name": "délicieux aliments pour chiens","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "EUR","timezone": "Europe/Paris","advertiser_organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": true,"client_based_in_country": "FR","client_paying_invoices": false,"agency_client_metadata": {"name": "Madamemoiselle Poodle","email": "poodle_client@example.com","address_line_1": "101 Boulevard la Fayette","city": "Paris","administrative_district_level_1": "FR-O","country": "FR","zipcode": "62100","tax_id": "FR12345678900"},"regulations": {"restricted_delivery_signals": false}}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "5eab157200ff07dcbf0737d8790001737e616473617069736300016275696c642d63386238336332372d312d3334372d3100010128",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "cdfc6dbd-9ac6-416a-b386-d473dd6e6d64",
"updated_at": "2020-04-30T18:14:11.150Z",
"created_at": "2020-04-30T18:14:11.150Z",
"name": "Délicieux aliments pour chiens",
"type": "PARTNER",
"status": "PENDING",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],
"currency": "EUR",
"timezone": "Europe/Paris",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "REVOLVING",
"agency_representing_client": true,
"client_based_in_country": "FR",
"client_paying_invoices": false,
"agency_client_metadata": {
"name": "Madamemoiselle Poodle",
"email": "poodle_client@example.com",
"address_line_1": "101 Boulevard la Fayette",
"city": "Paris",
"administrative_district_level_1": "FR-O",
"country": "FR",
"zipcode": "62100",
"tax_id": "FR12345678900"
},
"regulations": {
"restricted_delivery_signals": false
}
}
}
]
}

This request creates an Ad Account that is owned by an Agency representing a client, where the Advertiser is paying the invoices and where the Advertiser is based in France, or where the Ad Account will target ads to audience in France.

  • agency_representing_client has been set to true
  • client_based_in_country has been set to FR
  • client_paying_invoices has been set to false as the Advertiser is paying the invoices (note that this should be set to true if the Agency pays the invoices)
  • agency_client_metadata has been filled out with the address of the Advertiser and their French Tax ID

Ad Account creation - Example 4

Ad Account - Setting up a test Ad Account

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name":"The Dalmatian Test Account","type":"PARTNER","status":"ACTIVE","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058","currency": "EUR","timezone": "Europe\/London","advertiser":"Dalmatian Retail", "billing_type":"REVOLVING","billing_center_id":"7b8db2a8-2b48-42f0-858a-88901a782b27","agency_representing_client":false, "client_paying_invoices": false,"test":true}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "5f68d35200ff0864c8d10ae0dd0001737e616473617069736300016275696c642d35373264613164312d312d3338362d300001013d",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "a54ccc44-12fa-4952-b813-95f5dcfc27e7",
"updated_at": "2020-09-21T16:22:43.094Z",
"created_at": "2020-09-21T16:22:43.094Z",
"name": "The Dalmatian Test Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"currency": "EUR",
"timezone": "Europe/London",
"advertiser": "Dalmatian Retail",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"billing_center_id": "7b8db2a8-2b48-42f0-858a-88901a782b27",
"test": true,
"billing_type": "REVOLVING",
"agency_representing_client": false,
"client_paying_invoices": false
}
}
]
}

This request creates an Ad Account with the test parameter set to true, the resulting Ad Account never will be able to serve ads. The intention of setting up such an Ad Account is to be able to execute write requests without risking that ads will go live.

Was this page helpful?
Yes
No

AI-Powered Search