NAV Navbar
ruby
  • Topics
  • Introduction
  • Formats
  • Authorization
  • Pagination
  • Test Account
  • Resources
  • Inventory Items
  • Ad Accounts beta
  • Campaigns beta
  • Ad Sets beta
  • Ads beta
  • Errors
  • Configurations
  • Facebook Ads beta
  • Google AdWords beta
  • Introduction

    APISync's RESTful API enables you to synchronize your system with our database, from where records are sent to external services for marketing automation.

    We follow the JSON:API standard in all endpoints.

    The API's host is https://api.apisync.io

    In case your language or framework is listed below, we recommend using it.

    URLs and domains

    The API's host is at https://api.apisync.io. This host will be omitted from the examples below for brevity. For example, GET /inventory-items means an HTTP GET request to https://api.apisync.io/inventory-items.

    IDs and Reference Id

    UUID has the format in the id attribute below:

    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "attributes": {
          "reference_id": "your-own-id"
        }
      }
    }
    

    Every record sent by you will receive a unique ID in the UUID format.

    You can also send your own customized id with the reference_id attribute. When a POST request has a reference_id equal to an already existing record, such record will be updated. If such record doesn't exist yet, a new one will be created.

    Formats

    Attributes

    {
      "custom_attributes": [{
        "label": "Custom attribute",
        "identifier": "custom-attribute",
        "value": "Some value"
      }]
    }
    

    All JSON keys must use snake_case (underscores).

    Currencies

    Currency is specified with ISO 4217. For instance, specify BRL for brazilian Real.

    Dates

    {
      "created_at": "2017-10-12T10:12:00Z"
    }
    

    All dates are in the ISO 8601 format (except where specified).

    Authorization

    To authenticate a request, send your API token in the header:

    curl -H "Authorization: ApiToken $API_TOKEN" \
         "https://api.apisync.io/inventory-items"
    

    Every customer has a unique API token to access endpoints. You can find yours in the dashboard.

    You must include your API token in every request you make using the Authorization header in the format Authorization: ApiToken $API_TOKEN.

    Without this, we cannot know who's using the API and you won't be able to access your data.

    Pagination

    GET /campaigns will return a response which contains links such as these:

    {
      "data": {
        ...
      },
      "links": {
        "next": "https://api.apisync.io/campaigns?page[starting_after]=1539174610449"
        ...
      }
    }
    

    APISync uses the cursor strategy for pagination and all top-level API resources that return lists have support for it. These API methods share a common structure, returning a maximum of 25 records in chronological order and a links object with URLs to subsequent pages in the response body. Use these URLs from the links for fetching further data.

    A query looks like /campaigns?page[starting_after]=1539174610449

    The ?page[starting_after] query string is used as condition to return only resources that were created after the passed in value. This parameter accepts milliseconds since Unix time.

    Test Account

    All customers have a test account. This account has a lower rate limit, doesn't synchronize with 3rd-party services and doesn't count towards your paid plan quota. For that reason this account is recommended for development and tests.

    To utilize your test account, use its respective API token. It's visible in your dashboard. In production, use your main API token.

    Resources

    Inventory Items

    An Inventory Item represents a product. These are the attributes for this resource.

    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "attributes": {
          "ad_template_type": "vehicle",
          "available": true,
          "brand": "Volkswagen",
          "condition": "new",
          "content_language": "pt-br",
          "custom_attributes": [{
            "name": "Custom attribute",
            "identifier": "custom-attribute",
            "value": "Some value"
          }, {
            "name": "manufacturer",
            "identifier": "make",
            "value": "Volkswagen"
          }, {
            "name": "city",
            "identifier": "city",
            "value": "New York"
          }],
          "description": "Jetta",
          "images": [{
            "url": "https://example.com/house.jpg",
            "order": 1
          }, {
            "url": "https://example.com/bike.jpg",
            "order": 2
          }],
          "link": "https://mywebsite.com/products/volkswagen-jetta-2018",
          "model": "Jetta",
          "reference_id": "my-custom-id",
          "price": {
            "amount": 2117990,
            "currency": "BRL",
          }
          "title": "Jetta 2018, only R$21.179,90",
          "year":  2018
        }
      }
    }
    
    Attributes  
    ad_template_type required string Free to identify the type of item. Ads are generated respective to this type.

    You can only use letters, numbers, hiphens and underscores. Accents aren't allowed (eg. ç, ú).
    available required boolean Indicates product's availability. Accepted values:
    • true: when item on sale
    • false: when item is not on sale
    content_language required string Language for this product. Only accepted value is pt-br.
    brand string, optional Name of the product of manufacturer, ex: Google, Apple, Nike, Ford.
    condition string, optional Accepted values:
    • new
    • used
    • refurbished
    Don't use this for abstract or digital products.
    custom_attributes object list, optional List of object with customized attributes that describe the item with additional details. These are the accepted keys:
    • identifier: a value of your choice that identifies this attribute. For example, if your attribute is called "Delivery Method", use delivery_method. That way you can reference this later in your ads as <delivery_method>.
    • label: human name for this attribute, to be used in forms in your dashboard, e.g. "Delivery method".
    • value: actual value, e.g. "Standard".
    If you specify an ad template that uses a custom attribute, use the identifier as reference.
    description string, optional Product description. Use one or two paragraphs describing the item. You can use \n.
    images objects list, optional Object containing URLs to the product's images. Contains the keys:
    • url (string): image URL, starts with http.
    • order (integer): define the order in which item will be showed in the image gallery. Image with order equal to 1 is considered the cover image.
    link string, optional Specify the item's URL. When users interact with ads they will be redirected to this page.

    It has to start with http.
    model string, optional Item's name or model, e.g. Mustang in Ford Mustang, 3/4 in 3/4 hose, Airmax in Nike Airmax.
    price object, optional Object with these keys:
    • amount: price in cents, e.g. 1012 for R$10,12. It can't be 0 (zero). to avoid settings a price, just leave it null.
    • currency, e.g. BRL, USD.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.
    title string, optional Product's title. This is used in generic sales screens (in case you don't have a page and need one).
    year integer, optional Manufacturing year when the item was launched to market, 4 digits, e.g. 1994, 2017.
    fingerprint string, read-only Unique hash (signature, HMAC) generated automatically representing the sum of values in brand, model, year, reference_id, like a fingerprint. This is used to identify duplicated products.

    During creation (POST), if a the same value already exists, the pre-existing object will be updated, not created.
    sold_out_at date, read-only Generated automatically when available is set to false.
    created_at string, read-only Date when resource was created in the ISO-8601 format, e.g. 2017-10-12T10:12:00Z.

    More details

    ad_template_type: this value identifies the type of product and is used for generating specific ads. For example, we have templates for vehicle, real-estate.

    Besides the existing templates, you can set your own ones. In the dashboard you can create templates for a specific type of product. This is useful for creating targetted ads depending on the category of the product. You could, for example, define cabernet-sauvignon-wine and merlot-wine for different types of wines, and then different types of ads will be created for each.

    Creating items

    Definition
    POST /inventory-items

    To create a new item in your inventory, use this endpoint.

    When id is omitted, the item is created.

    client = Apisync.new(api_key: token)
    client.inventory_items.save({
      attributes: {
        ad_template_type: "vehicle",
        available: true,
        brand: "Volkswagen",
        condition: "new",
        content_language: "pt-br",
        custom_attributes: [{
          name: "My attribute",
          identifier: "custom-attribute",
          value: "Some value"
        }, {
          name: "Manufacturer",
          identifier: "make",
          value: "Volkswagen"
        }, {
          name: "City",
          identifier: "city",
          value: "New York"
        }],
        description: "This car can be yours.",
        images: [{
          url: "https://example.com/jetta1.jpg",
          order: 1
        }, {
          url: "https://example.com/jetta2.jpg",
          order: 2
        }],
        link: "https://mywebsite.com/products/volkswagen-jetta-2018",
        model: "Jetta",
        reference_id: "my-custom-id",
        price: {
          amount: 2117990,
          currency: "BRL",
        },
        title: "Jetta 2018 for only R$21.179,90",
        year: 2018
      }
    })
    
    Parameters  
    ad_template_type required string Free to identify the type of item. Ads are generated respective to this type.

    You can only use letters, numbers, hiphens and underscores. Accents aren't allowed (eg. ç, ú).
    available required boolean Indicates product's availability. Accepted values:
    • true: when item on sale
    • false: when item is not on sale
    content_language required string Language for this product. Only accepted value is pt-br.
    brand string, optional Name of the product of manufacturer, ex: Google, Apple, Nike, Ford.
    condition string, optional Accepted values:
    • new
    • used
    • refurbished
    Don't use this for abstract or digital products.
    custom_attributes object list, optional List of object with customized attributes that describe the item with additional details. These are the accepted keys:
    • identifier: a value of your choice that identifies this attribute. For example, if your attribute is called "Delivery Method", use delivery_method. That way you can reference this later in your ads as <delivery_method>.
    • label: human name for this attribute, to be used in forms in your dashboard, e.g. "Delivery method".
    • value: actual value, e.g. "Standard".
    If you specify an ad template that uses a custom attribute, use the identifier as reference.
    description string, optional Product description. Use one or two paragraphs describing the item. You can use \n.
    images objects list, optional Object containing URLs to the product's images. Contains the keys:
    • url (string): image URL, starts with http.
    • order (integer): define the order in which item will be showed in the image gallery. Image with order equal to 1 is considered the cover image.
    link string, optional Specify the item's URL. When users interact with ads they will be redirected to this page.

    It has to start with http.
    model string, optional Item's name or model, e.g. Mustang in Ford Mustang, 3/4 in 3/4 hose, Airmax in Nike Airmax.
    price object, optional Object with these keys:
    • amount: price in cents, e.g. 1012 for R$10,12. It can't be 0 (zero). to avoid settings a price, just leave it null.
    • currency, e.g. BRL, USD.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.
    title string, optional Product's title. This is used in generic sales screens (in case you don't have a page and need one).
    year integer, optional Manufacturing year when the item was launched to market, 4 digits, e.g. 1994, 2017.

    In case of success, you will receive the entity JSON back. Otherwise, you will receive an error message.

    Important:

    Updating items

    Include the id to execute an update.

    client = Apisync.new(api_key: token)
    client.inventory_items.save({
      id: "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
      attributes: {
        ad_template_type: "vehicle",
        available: true,
        brand: "Volkswagen",
        condition: "new",
        content_language: "pt-br",
        custom_attributes: [{
          name: "My attribute",
          identifier: "custom-attribute",
          value: "Some value"
        }, {
          name: "Manufacturer",
          identifier: "make",
          value: "Volkswagen"
        }, {
          name: "City",
          identifier: "city",
          value: "New York"
        }],
        description: "This car can be yours.",
        images: [{
          url: "https://example.com/jetta1.jpg",
          order: 1
        }, {
          url: "https://example.com/jetta2.jpg",
          order: 2
        }],
        link: "https://mywebsite.com/products/volkswagen-jetta-2018",
        model: "Jetta",
        reference_id: "my-custom-id",
        price: {
          amount: 2117990,
          currency: "BRL",
        },
        title: "Jetta 2018 for only R$21.179,90",
        year: 2018
      }
    })
    

    PATCH /inventory-items/:id

    You must replace :id with the record's unique ID you to update.

    These are the attributes that can be used.

    Parameters  
    ad_template_type required string Free to identify the type of item. Ads are generated respective to this type.

    You can only use letters, numbers, hiphens and underscores. Accents aren't allowed (eg. ç, ú).
    available required boolean Indicates product's availability. Accepted values:
    • true: when item on sale
    • false: when item is not on sale
    content_language required string Language for this product. Only accepted value is pt-br.
    brand string, optional Name of the product of manufacturer, ex: Google, Apple, Nike, Ford.
    condition string, optional Accepted values:
    • new
    • used
    • refurbished
    Don't use this for abstract or digital products.
    custom_attributes object list, optional List of object with customized attributes that describe the item with additional details. These are the accepted keys:
    • identifier: a value of your choice that identifies this attribute. For example, if your attribute is called "Delivery Method", use delivery_method. That way you can reference this later in your ads as <delivery_method>.
    • label: human name for this attribute, to be used in forms in your dashboard, e.g. "Delivery method".
    • value: actual value, e.g. "Standard".
    If you specify an ad template that uses a custom attribute, use the identifier as reference.
    description string, optional Product description. Use one or two paragraphs describing the item. You can use \n.
    images objects list, optional Object containing URLs to the product's images. Contains the keys:
    • url (string): image URL, starts with http.
    • order (integer): define the order in which item will be showed in the image gallery. Image with order equal to 1 is considered the cover image.
    link string, optional Specify the item's URL. When users interact with ads they will be redirected to this page.

    It has to start with http.
    model string, optional Item's name or model, e.g. Mustang in Ford Mustang, 3/4 in 3/4 hose, Airmax in Nike Airmax.
    price object, optional Object with these keys:
    • amount: price in cents, e.g. 1012 for R$10,12. It can't be 0 (zero). to avoid settings a price, just leave it null.
    • currency, e.g. BRL, USD.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.
    title string, optional Product's title. This is used in generic sales screens (in case you don't have a page and need one).
    year integer, optional Manufacturing year when the item was launched to market, 4 digits, e.g. 1994, 2017.

    Important:

    In case of success, you will receive the entity JSON back. Otherwise, you will receive an error message.

    Reading items

    client = Apisync.new(api_key: token)
    client.inventory_items.find(id: "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2")
    

    The command above will return an structured JSON like this:

    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "attributes": {
          "ad_template_type": "vehicle",
          "available": true,
          "brand": "Volkswagen",
          "condition": "new",
          "content_language": "pt-br",
          "custom_attributes": [{
            "name": "Custom attribute",
            "identifier": "custom-attribute",
            "value": "Some value"
          }, {
            "name": "manufacturer",
            "identifier": "make",
            "value": "Volkswagen"
          }, {
            "name": "city",
            "identifier": "city",
            "value": "New York"
          }],
          "description": "Jetta",
          "images": [{
            "url": "https://example.com/house.jpg",
            "order": 1
          }, {
            "url": "https://example.com/bike.jpg",
            "order": 2
          }],
          "link": "https://mywebsite.com/products/volkswagen-jetta-2018",
          "model": "Jetta",
          "reference_id": "my-custom-id",
          "price": {
            "amount": 2117990,
            "currency": "BRL",
          }
          "title": "Jetta 2018, only R$21.179,90",
          "year":  2018
        }
      }
    }
    

    GET /inventory-items/:id

    You must replace :id with the record's unique ID you to read.

    Examples

    GET /inventory-items/35b87e73-3fec-4f2c-86dd-6afe36a0dbd2

    This will return the item with id 35b87e73-3fec-4f2c-86dd-6afe36a0dbd2.

    Deleting items

    To remove an inventory item, you need to update the available attribute to false.

    Ad Accounts beta

    An Ad Account represents ad accounts on Facebook and customers on Google. When you create a campaign, you have to specify an ad account.

    This endpoint is readonly and return only the data we have access to. Before using this endpoint, you must login to the admin dashboard and give us access to you Facebook/Google accounts.

    To create campaigns, you need to associate them with an ad account.

    Below are the descriptions of the attributes for this resource.

    {
      "data": {
        "id": "ad-account-unique-id",
        "type": "ad-accounts",
        "attributes": {
          "service": "facebook-ads",
          "name": "Summer Campaign"
        }
      }
    }
    
    Attributes  
    id string, readonly This id is not an UUID like on the other endpoints. This is the id directly from the upstream service. For example, for Google customers this will be the 10-digit AdWords Customer ID. For Facebook, this is in the format act_{ad_account_id}.
    name string, readonly Name of this account, either on Google or Facebook.
    service string, readonly What service this ad account belongs to, either google-ads or facebook-ads.

    Reading ad accounts

    All resources: to get all resources, use,

    GET /ad-accounts

    Filters: you can filter these resources by using the filter query string, such as:

    GET /ad-accounts?filter[attribute]=value

    where attribute refers to one of the accepted attributes to be filtered.

    Filters  
    filter[service]=value Return only accounts belonging to the passed in filter. Accepted values are facebook-ads and google-ads.

    Campaigns beta

    A campaign defines how ads are going to be run. This is synchronized with 3rd-party services like Facebook Ads and Google Ads.

    Daily Budget: Facebook requires a daily budget per ad set, whereas Google, on the other hand, is not as granular and requires it on the entire campaign. To see how to define a budget, see the Configurations section for details.

    Below are the descriptions of the attributes for this resource.

    {
      "data": {
        "id": "49c23f61-2fec-5f1c-86dd-6afe36a1aef7",
        "type": "ads",
        "attributes": {
          "service": "facebook-ads",
          "state": "active",
          "description": "Campaign to run on Christmas",
          "reference_id": "my-custom-id",
          "title": "Xmas Campaign",
          "service_configurations": {}
        },
        "relationships": {
          "ad_account": {
            "data": {
              "type": "ad_accounts",
              "id": "49c23f61-2fec-5f1c-86dd-6afe36a1aef7"
            }
          }
        }
      }
    }
    
    Attributes  
    service required string The service we will synchronize this campaign with. Accepted values:
    • facebook-ads: we'll send it to Facebook.
    • google-ads: we'll send it to Google Ads, previously AdWords.
    state required string Define the entity state, whether it's running or not. Accepted values:
    • active: this means the entity will be synchronized with other services (e.g Facebook, Google).
    • paused: entity is not running.
    • removed: entity is removed and becomes invisible.
    description string, optional The admin dashboard will display this description.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.
    service_configurations object, optional Facebook and Google work differently. This object defines configuration on a per-service basis, such as Location, Language and Targetting.

    See the Configurations section for details.
    title string, optional Item's title. This will show up on the admin dashboard.
    created_via string, read-only Defines how this resource was created. Accepted values:
    • api
    • autogenerated: when it was created automatically.
    • admin: when created via admin by a user.
    created_at string, read-only Date when resource was created in the ISO-8601 format, e.g. 2017-10-12T10:12:00Z.
    Relationships  
    ad_account required The ad account this resource belongs to. Remember that Facebook ids start with act_{ad_account_id} whereas Google's are 10 digit numbers.

    Creating campaigns

    Definition
    POST /campaigns

    Use this endpoint to create new campaigns.

    Attributes  
    service required string The service we will synchronize this campaign with. Accepted values:
    • facebook-ads: we'll send it to Facebook.
    • google-ads: we'll send it to Google Ads, previously AdWords.
    state required string Define the entity state, whether it's running or not. Accepted values:
    • active: this means the entity will be synchronized with other services (e.g Facebook, Google).
    • paused: entity is not running.
    • removed: entity is removed and becomes invisible.
    description string, optional The admin dashboard will display this description.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.
    service_configurations object, optional Facebook and Google work differently. This object defines configuration on a per-service basis, such as Location, Language and Targetting.

    See the Configurations section for details.
    title string, optional Item's title. This will show up on the admin dashboard.

    In case of success, you will receive the entity JSON back. Otherwise, you will receive an error message.

    Important:

    Updating campaigns

    PUT /campaigns/:id

    Definition
    PUT /campaigns/:id

    Replace :id for the ID of the record you want to update.

    Attributes  
    state required string Define the entity state, whether it's running or not. Accepted values:
    • active: this means the entity will be synchronized with other services (e.g Facebook, Google).
    • paused: entity is not running.
    • removed: entity is removed and becomes invisible.
    description string, optional The admin dashboard will display this description.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.
    service_configurations object, optional Facebook and Google work differently. This object defines configuration on a per-service basis, such as Location, Language and Targetting.

    See the Configurations section for details.
    title string, optional Item's title. This will show up on the admin dashboard.

    Important:

    In case of success, you will receive the entity JSON back. Otherwise, you will receive an error message.

    Reading campaigns

    All resources: to get all resources, use,

    GET /campaigns

    Individual resource: to read a particular resource, specify the ID of the item you want to see.

    GET /campaigns/:id

    For example, GET /campaigns/35b87e73-3fec-4f2c-86dd-6afe36a0dbd2 will return the element with ID 35b87e73-3fec-4f2c-86dd-6afe36a0dbd2.

    Filters: you can filter these resources by using the filter query string, such as:

    GET /ad-accounts/:ad-account-id/campaigns?filter[attribute]=value

    where attribute refers to one of the accepted attributes to be filtered.

    Filters  
    filter[service]=value Return only accounts belonging to the passed in filter. Accepted values are facebook-ads and google-ads.

    Deleting campaigns

    To remove a campaign, you need to update the state attribute.

    Ad Sets beta

    An ad set groups together multiple ads. On Google it's called Ad Groups.

    Daily Budget: Facebook requires a daily budget per ad set, whereas Google, on the other hand, is not as granular and requires it on the entire campaign. To see how to define a budget, see the Configurations section for details.

    Below are the descriptions of the attributes for this resource.

    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "type": "ad-sets",
        "attributes": {
          "state": "active",
          "bids": {
            "cpc": {
              "amount": 123
            },
            "impressions": {
              "amount": 123
            }
          },
          "reference_id": "my-custom-id",
          "service": "facebook-ads",
          "title": "Ad Set for Houses",
          "service_configurations": {}
        },
        "relationships": {
          "campaign": {
            "data": {
              "type": "campaigns",
              "id": "unique-id"
            }
          }
        }
      }
    }
    
    Attributes  
    state required string Define the entity state, whether it's running or not. Accepted values:
    • active: this means the entity will be synchronized with other services (e.g Facebook, Google).
    • paused: entity is not running.
    • removed: entity is removed and becomes invisible.
    bids required object The bid will define how much you will pay for clicks, views and so on.

    You can define cpc for Google and impressions (see the Facebook specs).

    - amount (integer):

    value in cents. For $12.99, use 1299. On Facebook, the bid amount's unit is cents for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW.

    On Google, they expect a microamount format. For those cases, we multiply what is passed on amount with 10000, e.g $12.99 is set as 1299 and will be sent to Google as 12990000.

    service‑configurations required object Facebook and Google work differently. This object defines configuration on a per-service basis, such as Location, Language and Targetting.

    For Facebook ad sets, for instance, you are required to define a location.

    See the Configurations section for details.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.
    title string, optional Item's title. This will show up on the admin dashboard.
    service string, read-only Name of the service this object was created on (e.g adwords, facebook-ads)
    created_via string, read-only Defines how this resource was created. Accepted values:
    • api
    • autogenerated: when it was created automatically.
    • admin: when created via admin by a user.
    created_at string, read-only Date when resource was created in the ISO-8601 format, e.g. 2017-10-12T10:12:00Z.
    Relationships  
    campaign required The campaign this resource belongs to.

    Creating ad sets

    Definition
    POST /ad-sets

    Use this endpoint to create new ad sets.

    Attributes  
    state required string Define the entity state, whether it's running or not. Accepted values:
    • active: this means the entity will be synchronized with other services (e.g Facebook, Google).
    • paused: entity is not running.
    • removed: entity is removed and becomes invisible.
    bids required object The bid will define how much you will pay for clicks, views and so on.

    You can define cpc for Google and impressions (see the Facebook specs).

    - amount (integer):

    value in cents. For $12.99, use 1299. On Facebook, the bid amount's unit is cents for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW.

    On Google, they expect a microamount format. For those cases, we multiply what is passed on amount with 10000, e.g $12.99 is set as 1299 and will be sent to Google as 12990000.

    service‑configurations required object Facebook and Google work differently. This object defines configuration on a per-service basis, such as Location, Language and Targetting.

    For Facebook ad sets, for instance, you are required to define a location.

    See the Configurations section for details.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.
    title string, optional Item's title. This will show up on the admin dashboard.

    In case of success, you will receive the entity JSON back. Otherwise, you will receive an error message.

    Important:

    Updating ad sets

    PUT /ad-sets/:id

    Definition
    PUT /ad-sets/:id

    Replace :id for the ID of the record you want to update.

    Attributes  
    state required string Define the entity state, whether it's running or not. Accepted values:
    • active: this means the entity will be synchronized with other services (e.g Facebook, Google).
    • paused: entity is not running.
    • removed: entity is removed and becomes invisible.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.
    title string, optional Item's title. This will show up on the admin dashboard.

    Important:

    In case of success, you will receive the entity JSON back. Otherwise, you will receive an error message.

    Reading ad sets

    All resources: to get all resources, use,

    GET /ad-sets

    Individual resource: to read a particular resource, specify the ID of the item you want to see.

    GET /ad-sets/:id

    For example, GET /ad-sets/35b87e73-3fec-4f2c-86dd-6afe36a0dbd2 will return the element with ID 35b87e73-3fec-4f2c-86dd-6afe36a0dbd2.

    Resource within campaign: to get ad sets that belong to one campaign,

    GET /campaigns/:campaign-id/ad-sets

    Removing ad sets

    To remove a campaign, you need to update the state attribute.

    Ads beta

    An ad defines what is shown to users on platforms.

    {
      "data": {
        "id": "81b26e41-1fec-3f4c-86dd-6afe36a2adc3",
        "type": "ads",
        "attributes": {
          "ad-type": "expanded-text-ad",
          "creative": {
            "headline_part1": "Beach House in Miami",
            "headline_part2": "This amazing home can be yours",
            "description": "For only $400,000"
          }
          "destination-url": "https://apisync.io",
          "service": "facebook-ads",
          "state": "active",
          "reference-id": "my-custom-id"
        },
        "relationships": {
          "ad-set": {
            "data": {
              "type": "ad-sets",
              "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2"
            }
          }
        }
      }
    }
    
    Attributes  
    ad‑type required string Define the type of ad, which will dictate the creative attributes.

    Google Ads:
    • expanded-text-ad
    Facebook:
    • image_with_link
    • video
    creative required object The keys in this object depend on the ad-type value. For example, Google's expanded-text-ad will require headlines and description while a Facebook's video ad will require a video URL.

    See Creative Per Ad Type to know what are the creative attributes for each ad type.
    destination‑url required string The URL the user will be redirected to when they click on the ad. You have to specify a protocol (e.g https://).
    state required string Define the entity state, whether it's running or not. Accepted values:
    • active: this means the entity will be synchronized with other services (e.g Facebook, Google).
    • paused: entity is not running.
    • removed: entity is removed and becomes invisible.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.
    created_via string, read-only Defines how this resource was created. Accepted values:
    • api
    • autogenerated: when it was created automatically.
    • admin: when created via admin by a user.
    created_at string, read-only Date when resource was created in the ISO-8601 format, e.g. 2017-10-12T10:12:00Z.
    Relationships  
    ad‑set required The ad set in which this ad belongs to.

    Creative per ad type

    Each service (Google, Facebook etc) provides different features. Define them on an ad-by-ad basis.

    For example, Google's expanded text ad requires a headline, a second headline and a description body, whereas Facebook's image ad requires images, a body, a title. For each ad-type a different set of data needs to be used. This data is called Creative.

    If you need a different type of ad or banner which is not available below, get in touch with us.

    Below you will find what you have to pass as creative depending on the ad-type value you chose.

    Google Ads

    These are the supported ad types and creative for Google.

    {
      "data": {
        "headline-part1": "Beautiful Beach House",
        "headline-part2": "This incredible beach house can be yours today! Amazing conditions.",
        "description": "Beautiful Beach House"
      }
    }
    

    expanded-text-ad

    These are the keys you have to provide.

    Facebook Ads

    These are the supported ad types and creative for Facebook.

    image

    {
      "data": {
        "story": {
          "link_data": {
            "link": "https://example.com",
            "message": "The main body of the post, above the image.",
            "picture": "https://example.com/ad-picture.png",
            "description": "Link description below the image's title.",
            "call_to_action": {
              "type": "OPEN_LINK",
              "value": {
                "link_caption": "example.com/subscribe"
              }
            }
          }
        }
      }
    }
    

    These are the keys you have to provide, as shown in the example.

    Facebook image

    video

    {
      "data": {
        "story": {
          "video_data": {
            "link": "https://example.com",
            "message": "The main body of the post, above the image.",
            "image_url": "https://example.com/ad-picture.png",
            "video_url": "http://example.com/video.avi",
            "link_description": "Link description below the video.',
            "call_to_action": {
              "type": "OPEN_LINK",
              "value": {
                "link_caption": "example.com/subscribe"
              }
            }
          }
        }
      }
    }
    

    These are the keys you have to provide.

    Facebook video

    Creating ads

    Use this endpoint to create new ads.

    Definition
    POST /ads

    Attributes  
    ad‑type required string Define the type of ad, which will dictate the creative attributes.

    Google Ads:
    • expanded-text-ad
    Facebook:
    • image_with_link
    • video
    creative required object The keys in this object depend on the ad-type value. For example, Google's expanded-text-ad will require headlines and description while a Facebook's video ad will require a video URL.

    See Creative Per Ad Type to know what are the creative attributes for each ad type.
    destination‑url required string The URL the user will be redirected to when they click on the ad. You have to specify a protocol (e.g https://).
    state required string Define the entity state, whether it's running or not. Accepted values:
    • active: this means the entity will be synchronized with other services (e.g Facebook, Google).
    • paused: entity is not running.
    • removed: entity is removed and becomes invisible.
    reference_id string, optional Identifier in the client's database and can be used instead of id for updating resources.

    In case of success, you will receive the entity JSON back. Otherwise, you will receive an error message.

    Important:

    Updating ads

    This is how you can update an ad. We describe below what attributes can be updated.

    PATCH /ads/:id

    Definition
    PATCH /ads/:id

    Replace :id for the ID of the record you want to update.

    Attributes  
    state required string Define the entity state, whether it's running or not. Accepted values:
    • active: this means the entity will be synchronized with other services (e.g Facebook, Google).
    • paused: entity is not running.
    • removed: entity is removed and becomes invisible.

    Important:

    In case of success, you will receive the entity JSON back. Otherwise, you will receive an error message.

    Reading ads

    Individual resource: to read a particular resource, specify the ID of the item you want to see.

    GET /ads/:id

    For example, GET /ads/35b87e73-3fec-4f2c-86dd-6afe36a0dbd2 will return the element with ID 35b87e73-3fec-4f2c-86dd-6afe36a0dbd2.

    Resource within ad set: to get ads that belong to one ad set,

    GET /ad-sets/:ad-set-id/ads

    Filters: you can filter these resources by using the filter query string, such as:

    GET /ad-sets/:ad-set-id/ads?filter[attribute]=value

    where attribute refers to one of the accepted attributes to be filtered.

    Filters  
    filter[ad‑type]=value Return only ads where ad-type equals the passed in value.

    Removing ads

    To remove a campaign, you need to update the state attribute.

    Errors

    These are the errors we return when a request goes wrong.

    HTTP Code Meaning
    400 Incorrect request.
    401 Invalid API key.
    403 You don't have permission to see this resource.
    404 Resource can't be found.
    405 The method you used isn't supported.
    406 Request format is not supported.
    410 Resource doesn't exist anymore.
    422 Request is good but can't be processed due to semantic errors.
    429 You are doing too many requests, slow down.
    500 Temporary server problem. Try again.
    503 We're in maintenance.

    Configurations

    Different services support different functionalities. Below we describe how to configure your campaigns, ad sets and other resources for specific services.

    Facebook Ads beta

    Find below specific instructions for Facebook Ads.

    Budget

    POST /ad-sets
    
    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "type": "ad-sets",
        "attributes": {
          "state": "active",
          "bids": {
            "cpc": {
              "amount": 123
            },
            "impressions": {
              "amount": 123
            }
          },
          "reference_id": "my-custom-id",
          "service": "facebook-ads",
          "title": "Ad Set for Houses",
          "service-configurations": {
            "daily-budget": {
              "amount": 1299,
              "billing-event": "CLICKS"
            }
          }
        }
      }
    }
    

    Facebook specifies a daily budget and it needs to be defined on each ad set. If you want to spend $60 per month, your daily budget will be $2.

    Use the service-configurations key to set the daily budget for that ad set.

    Targeting by Location

    Required

    POST /ad-sets
    
    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "type": "ad-sets",
        "attributes": {
          "state": "active",
          "bids": {
            "cpc": {
              "amount": 123
            },
            "impressions": {
              "amount": 123
            }
          },
          "reference_id": "my-custom-id",
          "service": "facebook-ads",
          "title": "Ad Set for Houses",
          "service-configurations": {
            "geo-locations": {
              "countries": [
                "US"
              ],
              "regions": [{
                "key": "3847"
              }],
              "cities": [{
                "key": "2418956",
              }]
              "zips": [{
                "key": "US:90028"
              }, {
                "key": "US:94110"
              }],
              "custom-locations": [{
                "latitude": 36,
                "longitude": -121.0,
                "radius": 5,
                "distance-unit": "kilometer"
              }, {
                "address-string": "1601 Willow Road, Menlo Park, CA",
                "radius": 5
              }],
              "excluded_geo_locations": {
                "regions": [{
                  "key": "3847"
                }]
              }
            }
          }
        }
      }
    }
    

    You are required by Facebook to specify a geographical targeting location for every ad set. It is based on country, region, city or zipcode by using the service-configurations key. See the example on the right.

    All values described below can be found with Facebook's API: https://developers.facebook.com/docs/marketing-api/targeting-search#geo.

    Countries

    Use the countries key and pass a list of country keys, as in the example.

    For instance, on Facebook the key for United Kingdom is {"key": "GB"} according to the docs above. They use 2 char for all countries, so US stands for United States, BR for Brazil and so on.

    Regions

    Use the regions key and pass a list of region keys, as in the example.

    For instance, the documentation above states that region with key 3844 ({"key": "3847"}) stands for the state of Alaska, US. Likewise, you will pass this key in the format of the example on the right. Use Facebook's location search to figure what is the region's key you have to use for your use case.

    Cities

    Use the cities key and pass a list of city keys, as in the example.

    The same rules as above are applied to cities. For example, the key 2418956 stands for the city of Dublin, California. Use Facebook's location search to figure what is the city's key you have to use for your use case.

    Zipcodes

    Use the zips key and pass a list of zipcode keys, as in the example.

    The documentation, for instance, states that the zipcode 90028 has key US:90028 is within Los Angeles. Therefore, as the example on the right shows, {"zips": [{"key": "US:90028"}]} will target that zipcode.

    For US based zipcode, they're numerical only so it's easy to guess and form what the key would be (e.g US:some-number). For other countries, though, we recommend use Facebook's location search to figure what is the region's key you have to use for your use case.

    Custom Locations: Latitude and Longitude and Addresses

    Use the custom-locations key and pass a list of lat/lons or addresses, as in the example on the right. Whatever you pass here will be transmitted to Facebook.

    The values that can be used can be seen on https://developers.facebook.com/docs/marketing-api/buying-api/targeting/#location.

    radius defines how far away from the center people can be to be targeted. distance-unit could be kilometer or miles.

    Excluded Geolocations

    Use the excluded_geo_locations key and pass a list of keys and their values, as in the example.

    You can nest all the objects stated above inside this object key to exclude them. In the example on the right, we don't want our ads to show up for region with key 3847, that is, the region of Alaska, therefore we use the regions key. The same applies to countries, cities and zips.

    Google AdWords beta

    Find below specific instructions for Google AdWords.

    Budget

    POST /campaigns
    
    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "type": "campaigns",
        "attributes": {
          "service": "facebook-ads",
          "state": "active",
          "description": "Campaign to run on Christmas",
          "reference_id": "my-custom-id",
          "title": "Xmas Campaign",
          "service-configurations": {
            "daily-budget": {
              "amount": 1299
            }
          }
        }
      }
    }
    

    Google specifies a daily budget on the campaign level. If you want to spend $60 per month, your daily budget will be $2. Note that your actual spending could vary on a daily basis.

    Use the service-configurations key to set the daily budget for that campaign.

    Targeting by Location

    POST /campaigns
    
    {
      "data": {
        "id": "35b87e73-3fec-4f2c-86dd-6afe36a0dbd2",
        "type": "ad-sets",
        "attributes": {
          "service": "facebook-ads",
          "state": "active",
          "description": "Campaign to run on Christmas",
          "reference_id": "my-custom-id",
          "title": "Xmas Campaign",
          "service-configurations": {
            "geo-locations": {
              [
                "21137"
              ],
              "regions": [{
                "key": "3847"
              }],
              "cities": [{
                "key": "2418956",
              }]
              "zips": [{
                "key": "US:90028"
              }, {
                "key": "US:94110"
              }],
              "custom-locations": [{
                "latitude": 36,
                "longitude": -121.0,
                "radius": 5,
                "distance-unit": "kilometer"
              }, {
                "address-string": "1601 Willow Road, Menlo Park, CA",
                "radius": 5
              }],
              "excluded_geo_locations": {
                "regions": [{
                  "key": "3847"
                }]
              }
            }
          }
        }
      }
    }
    

    On Google you can specify geographical location targeting on campaigns (not on ad sets, as Facebook requires) based on country, region, state and city by using the service-configurations object. See the example on the right.

    Each location has an ID defined by Google, called Criteria ID and needs to be used in our API.

    Geolocations available

    For example, if you want to target California, you have to pass in its Criteria ID which is 21137.

    Postal Codes/Zipcodes

    You can use the link above to search for postal codes. Beware that only a handful of countries are supported by Google. You can use United States, Canada, France postal codes, but not for countries like Brazil or China.

    Custom Locations: Latitude and Longitude and Addresses

    As of this writing, Google doesn't support passing lat/lon or addresses.