Introduction

Welcome to the REST API docs for https://dynamic-ads.gravityadmin.com.

Authentication

The API uses JSON Web Tokens (referred to as JWT) for authentication.

Unless otherwise noted, ALL ENDPOINTS require an "Authorization" header to be included in the request, or an access denied error will be returned.

Obtaining a Token

fetch('https://api.dynamic-ads.app/auth', {
        method: 'POST',
        body: JSON.stringify({
            username: 'user@example.com',
            password: 'password',
        }),
    })
    .then(response => response.json())
    .then(response => {
        // your code here
    });

curl "https://api.dynamic-ads.app/auth" \
    --data-urlencode '{"username": "user@example.com", "password": "password"}'

The above code returns a response object containing your token.

{
    "token": "0a98b...981cd1a"
}

This endpoint returns an object containing your token. Sending invalid credentials, or attempting to log in as a disabled user, will return an error.

An "Authorization" header is not required in order to access this endpoint.

HTTP Request

POST https://api.dynamic-ads.app/auth

Payload Parameters

Requests to this endpoint must include a JSON body containing all of the following fields.

Parameter	Type	Description
username	String	The user's email address
password	String	The user's password

Response

Provided the credentials passed were correct and the user isn't disabled, this endpoint returns an object containing your token. Tokens obtained this way are valid for 30 minutes, after which it will need to be refreshed.

Refreshing Tokens

fetch('https://api.dynamic-ads.app/auth/refresh')
    .then(response => response.json())
    .then(response => {
        // your code here
    });

curl "https://api.dynamic-ads.app/auth/refresh"

The above code returns an object containing your refreshed token.

{
    "token": "af14cd...0ac1ff"
}

This endpoint returns an object containing your new token. Attempting to refresh with an invalid or expired token will return an error.

HTTP Request

GET https://api.dynamic-ads.app/auth/refresh

Response

This endpoint returns a refreshed token, based on the token provided.

Accounts

Get All Accounts

fetch('https://api.dynamic-ads.app/accounts')
    .then(response => response.json())
    .then(accounts => {
        // your code here
    });

curl "https://api.dynamic-ads.app/accounts"

The above code returns an array of Account objects. Some fields have been truncated for brevity.

[
    {
        "id": 1,
        "name": "Ethan's Autos",
        "createdDate": "2018-08-27T18:22:40+00:00",
        "facebookId": null,
        "createdBy": 1,
        "catalogs": [...],
        "pixels": [...]
    }
]

This endpoint retrieves all accounts that you have access to.

HTTP Request

GET https://api.dynamic-ads.app/accounts

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section
q	No	See the Searching the API section

Response

This endpoint returns an array of accounts. For field information, see the Account Fields section.

Create an Account

fetch('https://api.dynamic-ads.app/accounts', {
        method: 'PUT',
        body: JSON.stringify({
            name: 'Example Account',
        }),
    })
    .then(response => response.json())
    .then(account => {
        // your code here
    });

curl -X PUT https://api.dynamic-ads.app/accounts \
    --data-urlencode '{"name": "Example Account"}'

The above code creates a new Account object. Some fields have been truncated for brevity.

[
    {
        "id": 2,
        "name": "Example Account",
        "createdDate": "2018-08-27T18:22:40+00:00",
        "facebookId": null,
        "createdBy": 1,
        "catalogs": [...],
        "pixels": [...]
    }
]

This endpoint creates a new account and sets you as the sole user that can access it.

HTTP Request

PUT https://api.dynamic-ads.app/accounts

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Payload Parameters

The request body should be a JSON payload. Fields marked as "Required" must be present in the payload.

Parameter	Type	Required	Description
name	String (64)	Yes	The account's name
facebookId	Integer	No	A Facebook ad account ID (must be unique)

Response

This endpoint returns the newly created account object. For field information, see the Account Fields section.

Get a Specific Account

fetch('https://api.dynamic-ads.app/accounts/1')
    .then(response => response.json())
    .then(account => {
        // your code here
    });

curl "https://api.dynamic-ads.app/accounts/1"

The above code returns a single Account object. Some fields have been truncated for brevity.

{
    "id": 1,
    "name": "Test Auto",
    "createdDate": "2018-08-28T16:40:30+00:00",
    "facebookId": 1,
    "createdBy": 1,
    "catalogs": [...],
    "pixels": [...]
}

This endpoint retrieves an account by it's ID. Attempting to retrieve an account that you do not have permission to access will return an access denied error.

HTTP Request

GET https://api.dynamic-ads.app/accounts/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the account to retrieve

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Response

This endpoint returns a single account. For field information, see the Account Fields section.

Update an Account

fetch('https://api.dynamic-ads.app/accounts/1', {
        method: 'PATCH',
        body: JSON.stringify({
            name: 'New Account Name',
        }),
    })
    .then(response => response.json())
    .then(account => {
        // your code here
    });

curl -X PATCH "https://api.dynamic-ads.app/accounts/1" \
    --data-urlencode '{"name": "New Account Name"}'

The above code returns the modified Account object. Some fields have been truncated for brevity.

{
    "id": 1,
    "name": "New Account Name",
    "createdDate": "2018-08-28T16:40:30+00:00",
    "facebookId": 1,
    "createdBy": 1,
    "catalogs": [...],
    "pixels": [...]
}

This endpoint updates fields on an account. Attempting to update an account that you do not have permission to access will return an access denied error.

HTTP Request

PATCH https://api.dynamic-ads.app/accounts/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the account to update

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Payload Parameters

Requests to this endpoint should have the request body set to a JSON payload containing one or more of the following fields to update.

Parameter	Type	Description
name	String	The account's name
facebookId	Integer	The Facebook ad account ID

Response

This endpoint returns the modified account object. For field information, see the Account Fields section.

Delete an Account

fetch('https://api.dynamic-ads.app/accounts/1', {
        method: 'DELETE'
    })
    .then(() => {
        // your code here
    });

curl -X DELETE "https://api.dynamic-ads.app/accounts/1"

The above code deletes an account, and returns a 204 No Content response.

This endpoint deletes an account. Attempting to delete an account that you do not have permission to access will return an access denied error.

HTTP Request

DELETE https://api.dyanmic-ads.gravityadmin.com/accounts/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the account to delete

Response

This endpoint deletes an account, and returns a 204 No Content response.

Account Fields

{
    "id": 3,
    "name": "Test Account",
    "createdDate": "2018-10-30T17:56:08+00:00",
    "facebookId": "act_1191551014340628",
    "createdBy": 1,
    "catalogs": [
        {
            "id": 4,
            "name": "Test Catalog",
            "createdDate": "2018-11-07T16:13:04+00:00"
        }
    ],
    "pixels": []
}

A sample Account object.

Field	Type	Description
id	Integer	The account's ID
name	String	The account's name
createdDate	DateTime	The timestamp of the account's creation
createdBy	Integer	The ID of the user that created the account
facebookId	Integer	The ID of the Facebook ad account
catalogs	Array<Catalog>	An array of catalogs that belong to the account
pixels	Array<Pixel>	An array of tracking pixels that belong to the account

Catalogs

Get All Catalogs

fetch('https://api.dynamic-ads.app/catalogs')
    .then(response => response.json())
    .then(catalogs => {
        // your code here
    });

curl "https://api.dynamic-ads.app/catalogs"

The above code returns an array of Catalog objects. Some fields have been truncated for brevity.

[
    {
        "id": 1,
        "name": "Demo Catalog",
        "createdDate": "2018-08-27T18:22:40+00:00",
        "facebookId": 12345,
        "createdBy": 1,
        "account": 1,
        "feeds": [...]
    }
]

This endpoint returns all catalogs that you have access to.

HTTP Request

GET https://api.dynamic-ads.app/catalogs

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section
q	No	See the Searching the API section

Response

This endpoint returns an array of catalog objects. For field information, see the Catalog Fields section.

Create a Catalog

fetch('https://api.dynamic-ads.app/catalogs', {
        method: 'PUT',
        body: JSON.stringify({
            account: 1,
            name: 'Test Catalog',
        }),
    })
    .then(response => response.json())
    .then(catalog => {
        // your code here
    });

curl -X PUT "https://api.dynamic-ads.app/catalogs" \
    --data-urlencode '{"account":1,"name":"Test Catalog"}'

The above code creates a new Catalog object. Some fields have been truncated for brevity.

{
    "id": 9,
    "name": "Test Catalog",
    "createdDate": "2018-09-06T21:20:05+00:00",
    "facebookId": 1536268805628,
    "createdBy": 1,
    "account": 2,
    "feeds": [...]
}

This endpoint creates a new catalog. Attempting to create a catalog on an account you do not have permission to access will return an access denied error.

HTTP Request

PUT https://api.dynamic-ads.app/catalogs

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Payload Parameters

The request body should be a JSON payload. Fields marked as "Required" must be present in the payload.

Parameter	Type	Required	Description
account	Integer	Yes	The ID of the account to attach the catalog to
name	String	Yes	The display name of the catalog

Get a Specific Catalog

fetch('https://api.dynamic-ads.app/catalogs/1')
    .then(response => response.json())
    .then(catalog => {
        // your code here
    });

curl "https://api.dynamic-ads.app/catalogs/1"

The above code returns a single Catalog object. Some fields have been truncated for brevity.

{
    "id": 1,
    "name": "Demo Catalog",
    "createdDate": "2018-08-27T18:22:40+00:00",
    "facebookId": 12345,
    "createdBy": 1,
    "account": 1,
    "feeds": [...]
}

This endpoint retrieves a catalog by it's ID. Attempting to retrieve a catalog that you do not have access to will result in an access denied error.

HTTP Request

GET https://api.dynamic-ads.app/catalogs/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the catalog to retrieve

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Response

This endpoint returns a single catalog. For field information, see the Catalog Fields section.

Update a Catalog

fetch('https://api.dynamic-ads.app/catalogs/1', {
        method: 'PATCH',
        body: JSON.stringify({
            name: 'New Catalog Name',
        }),
    })
    .then(response => response.json())
    .then(catalog => {
        // your code here
    });

curl -X PATCH "https://api.dynamic-ads.app/catalogs/1" \
    --data-urlencode '{"name": "New Catalog Name"}'

The above code returns the modified Catalog object. Some fields have been truncated for brevity.

{
    "id": 1,
    "name": "New Catalog Name",
    "createdDate": "2018-08-27T18:22:40+00:00",
    "facebookId": 12345,
    "createdBy": 1,
    "account": 1,
    "feeds": [...]
}

This endpoint updates fields on a catalog. Attempting to update a catalog that you do not have permission to access will return an access denied error.

HTTP Request

PATCH https://api.dynamic-ads.app/catalogs/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the catalog to update

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Payload Parameters

Requests to this endpoint should have the request body set to a JSON payload containing one or more of the following fields to update.

Parameter	Type	Description
name	String	The catalog's name

Delete a Catalog

fetch('https://api.dynamic-ads.app/catalogs/1', {
        method: 'DELETE',
    })
    .then(() => {
        // your code here
    });

curl -X DELETE "https://api.dynamic-ads.app/catalogs/1"

The above code deletes a catalog, and returns a 204 No Content response.

This endpoint deletes a catalog. Attempting to delete a catalog that you do not have permission to access will return an access denied error.

HTTP Request

DELETE https://api.dynamic-ads.app/catalogs/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the catalog to delete

Response

This endpoint deletes a catalog, and returns a 204 No Content response.

Catalog Fields

{
    "id": 4,
    "name": "Test Catalog",
    "createdDate": "2018-11-07T16:13:04+00:00",
    "facebookId": 992659950937869,
    "createdBy": 1,
    "account": 3,
    "feeds": [
        {
            "id": 7,
            "name": "Test Feed",
            "url": "http://example.com/feed.csv",
            "createdDate": "2018-12-17T15:43:32+00:00",
            "facebookId": 123456,
            "settings": {
                "updateFrequency": "hourly",
                "deleteMissingProducts": true
            },
            "fieldMappings": [
                {
                    "id": 189,
                    "feed": 7,
                    "targetField": "address",
                    "type": "address",
                    "translations": [],
                    "street": "123 Main Street",
                    "city": "Orlando",
                    "region": "Florida",
                    "postalCode": "32828",
                    "country": "USA"
                }
            ]
        }
    ]
}

A sample Catalog object.

Field	Type	Description
id	Integer	The catalog's ID
name	String	The catalog's name
createdDate	DateTime	The timestamp of the catalog's creation
createdBy	Integer	The ID of the user that created the catalog
facebookId	Integer	The Facebook ID of the catalog
feeds	Array<Feed>	An array of Feed objects belonging to the catalog

Facebook

Get All Facebook Ad Accounts

fetch('https://api.dynamic-ads.app/facebook/accounts')
    .then(response => response.json())
    .then(adAccounts => {
        // your code here
    });

curl "https://api.dynamic-ads.app/facebook/accounts"

The above code returns an array of AdAccount objects. Some fields have been truncated for brevity.

[
    {
        "id": "act_1191551014340628",
        "name": "Test Ad Account"
    }
]

This endpoint returns an array containing the ID and name of all ad accounts in our Facebook business manager that aren't currently assigned to any accounts in the Dynamic Ads app.

HTTP Request

GET https://api.dynamic-ads.app/facebook/accounts

Response

This endpoint returns an array of ad account objects. For field information, see the AdAccount Fields section.

AdAccount Fields

{
    "id": "act_1191551014340628",
    "name": "Test Ad Account"
}

A sample AdAccount object.

Field	Type	Description
id	String	The Facebook ID of the ad account
name	String	The name of the ad account

Feeds

Get All Feeds

fetch('https://api.dynamic-ads.app/feeds')
    .then(response => response.json())
    .then(feeds => {
        // your code here
    });

curl "https://api.dynamic-ads.app/feeds"

The code above returns an array of Feed objects. Some fields have been truncated for brevity.

[
    {
        "id": 4,
        "name": "Test Feed",
        "createdDate": "2018-11-08T15:41:34+00:00",
        "url": "https://example.com/feed.csv",
        "facebookId": 328746191013827,
        "catalog": 4,
        "settings": {...},
        "fields": {...}
    }
]

This endpoint returns all feeds that you have access to.

HTTP Request

GET https://api.dynamic-ads.app/feeds

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section
q	No	See the Searching the API section

Response

This endpoint returns an array of feed objects. For field information, see the Feed Fields section.

Create a Feed

fetch('https://api.dynamic-ads.app/feeds', {
        method: 'PUT',
        body: JSON.stringify({
            catalog: 1,
            name: 'Test Feed',
            url: 'https://example.com/feed.csv',
        }),
    })
    .then(response => response.json())
    .then(feed => {
        // your code here
    });

curl -X PUT "https://api.dynamic-ads.app/feeds" \
    --data-urlencode '{"catalog": 1, "name": "Test Feed", "url": "https://example.com/feed.csv"}'

The above code creates a new Feed object. Some fields have been truncated for brevity.

{
    "id": 5,
    "name": "Test Feed",
    "createdDate": "2018-11-08T16:27:08+00:00",
    "url": "https://example.com/feed.csv",
    "facebookId": 328746191018871,
    "catalog": 1,
    "settings": {...},
    "fieldMappings": {...}
}

This endpoint creates a new feed. Attempting to create a feed on a catalog you do not have permission to access will return an access denied error.

HTTP Request

PUT https://api.dynamic-ads.app/feeds

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Payload Parameters

The request body should be a JSON payload. Fields marked as "Required" must be present in the payload.

Parameter	Type	Required	Description
catalog	Integer	Yes	The ID of the catalog to attach the feed to
name	String	Yes	The display name of the feed
url	String	Yes	The URL of the source feed
fieldMappings	FeedMappingFields	No	Field mapping information for the feed
settings	FeedSettings	No	Settings for the feed

Get a Specific Feed

fetch('https://api.dynamic-ads.app/feeds/1')
    .then(response => response.json())
    .then(feed => {
        // your code here
    });

curl "https://api.dynamic-ads.app/feeds/1"

The above code returns a single Feed object. Some fields have been truncated for brevity.

{
    "id": 4,
    "name": "Test Feed",
    "createdDate": "2018-11-08T15:41:34+00:00",
    "url": "https://example.com/feed.csv",
    "facebookId": 328746191013827,
    "catalog": 4,
    "settings": {...},
    "fieldMappings": {...}
}

This endpoint retrieves a feed by it's ID. Attempting to retrieve a feed that you do not have access to will result in an access denied error.

HTTP Request

GET https://api.dynamic-ads.app/feeds/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the feed to retrieve

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Response

This endpoint returns a single feed. For field information, see the Feed Fields section.

Update a Feed

fetch('https://api.dynamic-ads.app/feeds/1', {
        method: 'PATCH',
        body: JSON.stringify({
            name: 'New Feed Name',
        }),
    })
    .then(response => response.json())
    .then(feed => {
        // your code here
    });

curl -X PATCH "https://api.dynamic-ads.app/feeds/1" \
    --data-urlencode '{"name": "New Feed Name"}'

The above code returns the modified Feed object. Some fields have been truncated for brevity.

{
    "id": 4,
    "name": "New Feed Name",
    "createdDate": "2018-11-08T15:41:34+00:00",
    "url": "https://example.com/feed.csv",
    "facebookId": 328746191013827,
    "catalog": 4,
    "settings": {...},
    "fieldMappings": {...}
}

This endpoint updates fields on a feed. Attempting to update a feed that you do not have permission to access will return an access denied error.

HTTP Request

PATCH https://api.dynamic-ads.app/feeds/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the feed to update

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Payload Parameters

Requests to this endpoint should have the request body set to a JSON payload containing one or more of the following fields to update. Fields whose value is an object (such as settings) must contain at least one field to update.

Parameter	Type	Description
name	String	The name of the feed
url	String	The URL where the feed is located
settings	FeedSettings	The feed's settings
fieldMappings	FeedMappingFields	Field mapping information for the feed

Delete a Feed

fetch('https://api.dynamic-ads.app/feeds/1', {
        method: 'DELETE',
    })
    .then(() => {
        // your code here
    });

curl -X DELETE "https://api.dynamic-ads.app/feeds/1"

The above code deletes a feed, and returns a 204 No Content response.

This endpoint deletes a feed. Attempting to delete a feed that you do not have permission to access will return an access denied error.

HTTP Request

DELETE https://api.dynamic-ads.app/feeds/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the feed to delete

Response

This endpoint deletes a feed, and returns a 204 No Content response.

Download a Feed

fetch('https://api.dynamic-ads.app/feeds/1/download.json')
    .then(response => response.json())
    .then(feed => {
        // your code here
    });

curl "https://api.dynamic-ads.app/feeds/1/download.json"

The above code returns a mapped feed in JSON format. Some fields have been truncated for brevity.

[
    {
        "address": "...",
        "latitude": "29.567910",
        "longitude": "-81.230950",
        "url": "https://www.adventurecars.com/",
        "image": "[]",
        "mileage": "{\"unit\":\"MI\",\"value\":\"192\"}",
        "body_style": "4D Passenger Van",
        "description": " Price includes: $500 - Chrysler Capital 2019 Bonus Cash **CK5...",
        "exterior_color": "Velvet",
        "make": "Chrysler",
        "model": "Pacifica",
        "price": "30285",
        "state_of_vehicle": "New",
        "title": "2019 Chrysler Pacifica",
        "transmission": "9-Speed 948TE Automatic",
        "vehicle_id": "2C4RC1CG6KR533394",
        "vin": "2C4RC1CG6KR533394",
        "year": "2019"
    }
]

This endpoint returns the mapped feed. It does NOT require an "Authorization" header.

HTTP Request

GET https://api.dynamic-ads.app/feeds/<id>/download.<format>

Path Parameters

Parameter	Type	Description
id	Integer	The feed's ID
format	String	The format to export the feed in (supported formats are "json" and "csv"; omitting the format will export in "json" format)

Query Parameters

Parameter	Type	Description
limit	Integer	Limits the number of items from the source feed to the first X items

Response

This endpoint returns a source feed mapped to a JSON or CSV document. If the specified format is "csv", the document is ready for consumption by Facebook's Dynamic Ads system.

Feed Fields

{
    "id": 7,
    "name": "Test Feed",
    "createdDate": "2018-12-17T15:43:32+00:00",
    "url": "https://example.com/feed.csv",
    "facebookId": 1234567890,
    "catalog": 5,
    "settings": {
        "updateFrequency": "hourly",
        "deleteMissingProducts": true
    },
    "fieldMappings": [
        {
            "id": 189,
            "feed": 7,
            "targetField": "address",
            "type": "address",
            "translations": [],
            "street": "123 Main Street",
            "city": "Orlando",
            "region": "Florida",
            "postalCode": "32828",
            "country": "USA"
        },
        {
            "id": 173,
            "feed": 7,
            "targetField": "latitude",
            "type": "constant",
            "translations": [],
            "fieldValue": "29.567910"
        },
        {
            "id": 176,
            "feed": 7,
            "targetField": "image",
            "type": "image",
            "translations": [],
            "maxItems": 2,
            "sourceDelimiter": "|",
            "sourceField": "Photo Url List"
        },
        {
            "id": 172,
            "feed": 7,
            "targetField": "mileage",
            "type": "mileage",
            "translations": [],
            "sourceField": "Odometer",
            "unit": "MI"
        },
        {
            "id": 183,
            "feed": 7,
            "targetField": "state_of_vehicle",
            "type": "template",
            "translations": [
                {
                    "source": "N",
                    "value": "New"
                },
                {
                    "source": "U",
                    "value": "Used"
                }
            ],
            "template": "{{NewUsed}}"
        }
    ]
}

A sample Feed object.

Field	Type	Description
id	Integer	The feed's ID
catalog	Integer	The ID of the catalog that the feed belongs to
name	String	The name of the feed
url	String	The URL where the feed's source CSV can be found
createdDate	DateTime	The timestamp that the feed was created
createdBy	Integer	The ID of the user that created the feed
facebookId	Integer	The Facebook ID of the feed
settings	Settings	A dictionary of Feed Settings for the feed
fieldMappings	Array<FieldMapping>	See Feed Field Mappings

Feed Settings

Field	Type	Description
defaultImageUrl	String	The URL of the image to use if an item in a catalog has no image URL(s), or null if items without images should be skipped
updateFrequency	Enum("daily", "hourly")	The frequency at which Facebook should poll the API for catalog updates
deleteMissingProducts	Boolean	Whether or not products in the Facebook catalog should be deleted if they're no longer present in the feed

Feed Field Mappings

Feeds are mapped using an array of field mapping objects that describe how to map certain values from the source CSV to a target field in Facebook. The app supports several different types of field mappings, which can be differentiated by using the type field as a discriminator. The table below describes the fields that are common between every type of mapping (including the aforementioned type field).

Field	Type	Description
id	Integer	The ID of the mapping
feed	Integer	The ID of the feed that the mapping belongs to
targetField	String	The Facebook feed field that the mapping maps to
type	String	A string used to differentiate between types of field mappings (see below)
translations	Array<FieldTranslation>	An array of field translations

Possible values for the type field are listed below.

• address
• constant
• image
• mileage
• template

Field Translations

The translations array describes a set of values that, if the mapped field is equal to, should be converted to something else. For example, some source feeds may use "N" and "U" for "New" and "Used". Facebook requires the latter, which you could achieve with translations.

Only one translation can trigger for each mapped field. If a field has 10 translations but matches on the first translation, the other 9 will not be checked.

Field	Type	Description
source	String	The value to match in order to trigger the translation
value	String	The value to translate the field to if source matches

Address Mapping Type

Address mapping types are similar to the constant type in that they don't actually pull values from the CSV and map them to a Facebook feed field. Instead, the different parts of the dealership's address are assembled into the format required by Facebook.

Refer to Feed Field Mappings for a list of fields common to each mapping type.

Field	Type	Description
street	String	The street portion of the address
city	String	The city portion of the address
region	String	The region portion of the address (i.e. state or province)
postalCode	String	The postal code portion of the address
country	String	The country portion of the address

Constant Mapping Type

Constant mapping types add values to the output feed that aren't present in the source feed. For example, you could add the currency field to the Facebook feed using a constant type, even if "currency" isn't a field present in your source feed.

Refer to Feed Field Mappings for a list of fields common to each mapping type.

Field	Type	Description
fieldValue	String	The value of the field

Image Mapping Type

Image mapping types take a delimited field and convert it to the image list format expected by Facebook. For example, if your source feed has an "images" field containing a comma-delimited list of image URLs, you would use the image type to split the field on every comma and map the resulting items to Facebook's image list format.

Refer to Feed Field Mappings for a list of fields common to each mapping type.

Field	Type	Description
maxItems	Integer	The maxmimum number of items to include the resulting image list (0 indicates an unlimited number)
sourceDelimiter	String	The delimiter to split the source field on (i.e. a pipe or comma character)
sourceField	String	The name of the field in the source feed

Mileage Mapping Type

Mileage mapping types are used to map distance values in a source feed to the distance format used by Facebook.

Refer to Feed Field Mappings for a list of fields common to each mapping type.

Field	Type	Description
sourceField	String	The name of the field in the source feed
unit	Enum("MI", "KM")	The unit to use for that distance value

Template Mapping Type

Template mapping types are used to map an arbitrary combination of text and values from a source feed to a single field in the output feed. Text in the template string surrounded by double curly brackets are searched for in the field list of the source feed and, if they're found, are interpolated into the resulting string.

Refer to Feed Field Mappings for a list of fields common to each mapping type.

Field	Type	Description
template	String	The template string

Feed Templates

Get All Templates

fetch('https://api.dynamic-ads.app/feed-templates')
    .then(response => response.json())
    .then(templates => {
        // your code here
    });

curl "https://api.dynamic-ads.app/feed-templates"

The above code returns an array of FeedTemplate objects.

[
    {
        "id": 1,
        "name": "Example Template",
        "fields": [...]
    }
]

This endpoint returns all feed templates.

HTTP Request

GET https://api.dynamic-ads.app/feed-templates

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section
q	No	See the Searching the API section

Response

This endpoint returns an array of feed templates. For field information, see the FeedTemplate Field section.

Create a Template

fetch('https://api.dynamic-ads.app/feed-templates', {
        method: 'PUT',
        body: JSON.stringify({
            name: 'Example Template',
            fields: [
                // truncated
            ],
        }),
    })
    .then(response => response.json())
    .then(template => {
        // your code here
    });

curl -X PUT "https://api.dynamic-ads.app/feed-templates" \
    --data-urlencode '{"name": "Example Template", "fields: []}'

The above code creates a new FeedTemplate object. Some fields have been truncated for brevity.

{
    "id": 1,
    "name": "Example Template",
    "fields": [...]
}

This endpoint creates a new feed template.

HTTP Request

PUT https://api.dynamic-ads.app/feed-templates

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Payload Parameters

The request should contain a JSON payload. Fields marked as "Required" must be present in the payload.

Parameter	Type	Required	Description
name	String	Yes	The template's name
fields	Array<FeedTemplateField>	No	An array of fields belonging to the template

Response

This endpoint returns the newly created template object. For field information, see the FeedTemplate Fields section.

Get a Specific Template

fetch('https://api.dynamic-ads.app/feed-templates/1')
    .then(response => response.json())
    .then(template => {
        // your code here
    });

curl "https://api.dynamic-ads.app/feed-templates/1"

The above code returns a single FeedTemplate object. Some fields have been truncated for brevity.

{
    "id": 1,
    "name": "Example Template",
    "fields": [...]
}

This endpoint retrieves a template by it's ID.

HTTP Request

GET https://api.dynamic-ads.app/feed-templates/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the template to retrieve

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Response

This endpoint returns a single template. For field information, see the FeedTemplate Fields section.

Update a Template

fetch('https://api.dynamic-ads.app/feed-templates/1', {
        method: 'PATCH',
        body: JSON.stringify({
            name: 'New Example Template',
        }),
    })
    .then(response => response.json())
    .then(template => {
        // your code here
    });

curl -X PATCH "https://api.dynamic-ads.app/feed-templates/1" \
    --data-urlencode '{"name": "New Template Name"}'

The above code returns the modified FeedTemplate object. Some fields have been truncated for brevity.

    "id": 1,
    "name": "New Example Template",
    "fields": [...]
}

HTTP Request

PATCH https://api.dynamic-ads.app/feed-templates/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the template to update

Query Parameters

Parameter	Required	Description
p	No	See the Projecting Results section

Payload Parameters

The request should contain a JSON payload. One or more of the fields below must be included in the payload.

Parameter	Type	Description
name	String	The template's name
fields	Array<FeedTemplateField>	An array of fields belonging to the template

Response

This endpoint returns the modified template object. For field information, see the FeedTemplate Fields section.

Delete a Template

fetch('https://api.dynamic-ads.app/feed-templates/1', {
        method: 'DELETE',
    })
    .then(() => {
        // your code here
    });

curl -X DELETE "https://api.dynamic-ads.app/feed-templates/1"

The above code deletes a template, and returns a 204 No Content response.

This endpoint deletes a template.

HTTP Request

DELETE https://api.dynamic-ads.app/feed-templates/<id>

Path Parameters

Parameter	Type	Description
id	Integer	The ID of the template to delete

Response

This endpoint deletes a template, and returns a 204 No Content response.

FeedTemplate Fields

{
    "id": 1,
    "name": "Example Template",
    "fields": [
        {
            "arguments": {
                "template": "{{bodystyle}}"
            },
            "targetField": "body_style",
            "template": 4,
            "type": "template",
            "translations": [
                {
                    "source": "4dr Car",
                    "value": "SEDAN"
                },
                {
                    "source": "2dr Car",
                    "value": "COUPE"
                },
                {
                    "source": "Mini-van, Passenger",
                    "value": "MINIVAN"
                },
                {
                    "source": "3dr Car",
                    "value": "HATCHBACK"
                },
                {
                    "source": "Sport Utility",
                    "value": "SUV"
                }
            ]
        }
    ]
}

A sample FeedTemplate object.

Field	Type	Description
id	Integer	The template's ID
name	String	The template's name
fields	Array<FeedTemplateField>	An array of fields belonging to the template (see below)

Template Fields

Templates contain an array of templated fields (confusing terminology, I know) that describe how the template translates to a real feed. Different types of templated fields are differentiated by their type field (similar to field mappings on feeds). They also share a set of common fields, which are detailed below.

Field	Type	Description
targetField	String	The Facebook feed field that the field maps to
template	Integer	The ID of the feed template that the field belongs to
type	String	A string used to differentiate between types of templated fields (see below)
translations	Array<FieldTranslation>	An array of field translations

Possible values for the type field are listed below.

• address
• constant
• image
• mileage
• template

Address Template Field Type

Refer to Template Fields for a list of fields common to each mapping type.

Field	Type	Description
street	String	The street portion of the address
city	String	The city portion of the address
region	String	The region portion of the address (i.e. state or province)
postalCode	String	The postal code portion of the address
country	String	The country portion of the address

Constant Template Field Type

Refer to Template Fields for a list of fields common to each mapping type.

Field	Type	Description
fieldValue	String	The value of the field

Image Template Field Type

Refer to Template Fields for a list of fields common to each mapping type.

Field	Type	Description
maxItems	Integer	The maxmimum number of items to include the resulting image list (0 indicates an unlimited number)
sourceDelimiter	String	The delimiter to split the source field on (i.e. a pipe or comma character)
sourceField	String	The name of the field in the source feed

Mileage Template Field Type

Refer to Template Fields for a list of fields common to each mapping type.

Field	Type	Description
sourceField	String	The name of the field in the source feed
unit	Enum("MI", "KM")	The unit to use for that distance value

Template Template Field Type

No that's not a typo and yes, I know the phrasing is confusing. I'm sorry.

Refer to Template Fields for a list of fields common to each mapping type.

Field	Type	Description
template	String	The template string

Projecting Results

const url = new URL('https://api.dynamic-ads.gravityadmin.com/accounts');

url.searchParams.set('p', JSON.stringify({
    id: true,
    name: true,
    deletedDate: true,
    'users.id': true,
}));

fetch(uri)
    .then(response => response.json())
    .then(accounts => {
        // your code here
    });

curl -G "https://api.dynamic-ads.gravityadmin.com/accounts" \
    -d 'p={"id": true, "name": true, "deletedDate": true, "users.id": true}'

The above command returns an array of partial Account objects, whose fields are defined by the p query parameter.

[
    {
        "id": 1,
        "name": "Ethan's Autos",
        "deletedDate": null,
        "users": [
            {
                "id": 1
            }
        ]
    }
]

You can specify which fields the API should return, called "projecting", by providing the p query parameter.

The value of p should be a JSON object, where the key is the field path to project, and the value is a boolean indicating whether or not the field should be included (either true if the field should be included, or false if it should be excluded). Please note that you cannot mix inclusions and exclusions in a single projection.

Field paths should be the dot-notation identifier of a field. For example, accounts have a users field, which in turn contains an id field. It's dot-notation form would be users.id. When projecting fields, any unrecognized field name will be silently ignored.

Searching the API

Any endpoint can be searched by passing a q parameter in the URL, i.e. /accounts?q=.... The value of q should be a MongoDB-style query document. For those that are not familiar with MongoDB query documents, a short explanation can be found below.

Query Document

A "query document" is simply a JSON object that defines fields and values to search by. For example, a request to /accounts?q={"name": "Primary"} would return a collection containing all accounts that you have access to, whose name matched the string "Primary" exactly.

You can enhance your searches by using operators in your document, a list of which can be found here. For example, a request to /accounts?q={"users.length": {"$gte":4}} would return a collection containing any account you have access to that is accessible by 4 or more users.

Related Objects

{
    "users.length": {
        "$gt": 1
    }
}

Applied to /accounts, returns any account you have acccess to that has 2 or more users in it.

Any field whose value is an array of related objects (such as Account.users) can be filtered by it's length by adding .length after the field name in your search. This will work for ANY array of objects in the API, and supports filtering using any operator.

Operators

An operator starts with a dollar sign, and allows you to perform more than just equality checks on data.

You can find a full list of supported operators in the library's GitHub repository.

Data Types

Scalar Data Types

Type	Description
String	Text of any length
String (n)	Text with a maximum length of n
Boolean	A normal boolean
Decimal	A normal decimal
Enum(...)	One of any value listed between the parenthesis
Integer	A normal integer
Array<T>	An array containing zero or more values of type T
DateTime	A timestamp in ISO 8601 date time format

Error Codes

Error codes are sorted by status code, followed by name.

Code	Status	Description
api.create_failed	400	A PUT request could not be completed due to a client error
api.generic	400	An unspecified or unexpected error ocurred
api.facebook_id_required	400	Your request cannot be completed without a parent object (such as Account for catalogs) being given a Facebook ID
api.invalid_parameter	400	A value in your payload was not of the correct type
api.invalid_payload	400	The payload you provided was malformed, or could not be understood
api.missing_parameters	400	The payload you provided was missing one or more required parameters
api.payload_empty	400	The endpoint you called requires that you provide at least one value in your payload
api.payload_required	400	The endpoint you called requires that you provide a payload
api.unsupported_fields	400	The payload you provided contained one or more fields that are not supported by the endpoint
api.update_failed	400	A PATCH request could not be completed due to a client error
entity_not_found	400	An entity referenced in your payload could not be found
query.bad_projection	400	The projection object you provided was malformed, or could not be understood
query.bad_query	400	The query object you provided was malformed, or could not be understood
unique_field_violation	400	A value in your payload (such as email on Users) already exists
access_denied	403	You do not have sufficient permissions to access the object your requested
not_found	404	No object could be found with the ID provided