POST /ad

POST /ad/ v5 | POST /ad v3 | POST /ad v2

Warning

POST /ad v3 is now officially deprecated and scheduled for removal on May, 1st 2023. Please move to use POST /ad/ v5.

POST /ad v2 is now officially deprecated and scheduled for removal on May, 1st 2023. Please move to use POST /ad/ v5.

This URL creates a new ad for the current user.

If the ad was successfully created then a 201 Created is returned and the Location header contains the URL to the newly created ad. The optional query parameter _body with value true or false can be used to influence whether the response body contains the ad in the body (or not) in case of success. By default, this value is true. If the ad contains errors then the server returns 400 Bad Request with a list of errors.

For a new ad the id attribute must be omitted or set to zero. The title and description must be set and will be trimmed. The salutation contains either MALE, FEMALE, COMPANY or FAMILY. The sellerName contains the name of the seller as displayed on the site.

The categoryId must be an existing category id from a category which has a status ACTIVE. If the status of the ad is ACTIVE and the current number of active ads for the same user in this category exceeds maxNumberOfActiveAds as defined in the category then an error is returned. Ads with status equals to PAUSED do not have this restriction.

The price.priceType must be one of the valid types listed in Price Types. If the priceType is either FIXED_PRICE or BIDDING_FROM then a price in the interval of (0,10000000000] must be specified. For all other price types price must be omitted.

A new ad must have a status which can be either ACTIVE or PAUSED. An active ad is shown on the site whereas a paused ad is not. See Ad Status for the list of valid ad status values.

The budgets.total and budgets.daily are mandatory fields whose value depend on the category, or they can be set to UNLIMITED. The category configuration which can be retrieved through the category URL GET /category/{id} contains the valid bounds for these fields once filled in. The bidMicros is a mandatory field whose value depends on the category, or can be set to AUTOMATIC to allow the system to optimize the bid. Note that when selecting AUTOMATIC the seller is required to either have a budgets.daily set to a value, not being UNLIMITED OR have a campaign daily budget (see budgets.daily) that is not UNLIMITED

All monetary units (from V5 onward) are named such that it is clear whether the integer value is in cents or in micros. For example, a price.amountCents of 10,50 EUR must be specified as 1050, whereas a bidMicros of 0,02 EUR must be defined as 20000.

The price.originalAmountCents field is optional, and will only be usable by enabled sellers. If a seller is not enabled, but will use this field, an error will be thrown.

The postCode is optional. In case it is not specified, its value is set to a value representing the entire country.

The images field is optional and can contain a list of up to 8 Image Objects which contain either the URL of the image or a unique identifier provided by POST /image.

The attributes field is optional and can contain a list of User-Defined Attributes.

POST /ad/ v5

Scope	api_rw or console_rw
Accept	application/sellside.ad-v5+json, application/json
Content-Type	application/sellside.ad-v5+json; charset=utf-8

Note

Ads created with POST Ad V5 have a slightly different structure than GET /ad/{id} v3. It is correct that V4 is skipped.

The fields related to price are consolidated into one mandatory price object.

The field campaignId is added.

The daily and total budgets are now consolidated in one mandatory budgets object.

CPC is no longer, it has changed into mandatory bidMicros.

bidMicros, budgets.daily.limitMicros, budgets.daily.spentMicros, budgets.total.limitMicros and budgets.total.spentMicros are now all in micro currencies.

several other fields are removed. See Fields for details.

Example

POST /ad
Accept: application/sellside.ad-v5+json, application/json
Content-Type: application/sellside.ad-v5+json; charset=utf-8

{
    "title": "Brother Fax voor 99,99",
    "description": "<b>NU extra voordelig op ourshop.com.</b> Fax nu voor slechts <b>99,99!</b>",
    "categoryId": 826,
    "status": "ACTIVE",
    "price": {
        "priceType": "FIXED_PRICE",
        "priceUnit": "per_sqm",
        "amountCents": 5600,
        "originalAmountCents": 6500
    },
    "bidMicros": "10000",
    "budgets": {
        "daily": {
            "limitMicros": "UNLIMITED",
        },
        "total": {
            "limitMicros": "350000000",
        }
    },
    "campaignId": 54212,
    "salutation": "COMPANY",
    "sellerName": "My Shop",
    "postcode": "1097DN",
    "regionId": 1700195,
    "phoneNumber": "0207894561",
    "allowContactByEmail": true,
    "vendorId": "OURSHOP-1423453-34",
    "links": {
        "displayUrl": "www.ourshop.com/Faxes",
        "url": "http://www.ourshop.com/index.php?param1=value1&amp;param2=value2&amp;param3=value3"
    },
    "images": [
        {
            "src": "http://www.ourshop.com/img/brother_fax_big.jpg",
        },
        {
            "src": "http://www.ourshop.com/img/brother_fax_side.jpg",
        }
    ],
    "attributes": [
        {
            "key": "color",
            "label": "Kleur",
            "locale": "nl",
            "type": "STRING",
            "value": "Zwart",
        },
        {
            "key": "size",
            "label": "Maat",
            "locale": "nl",
            "type": "NUMBER",
            "value": 6,
        },
        {
            "key": "software",
            "label": "Software",
            "locale": "nl",
            "type": "LIST",
            "value": [
                "Apple OSX",
                "Microsoft Windows 7"
            ],
        }
    ],
    "shippingOptions": [
        {
            "type": "SHIP",
            "costCents": 495,
            "time": "2d-5d"
        },
        {
            "type": "PICKUP",
            "pickupLocation": "1097DN"
        }
    ]
}

Example with Automatic bidding

POST /ad
Accept: application/sellside.ad-v5+json, application/json
Content-Type: application/sellside.ad-v5+json; charset=utf-8

{
    "title": "Brother Fax voor 99,99",
    "description": "<b>NU extra voordelig op ourshop.com.</b> Fax nu voor slechts <b>99,99!</b>",
    "categoryId": 826,
    "status": "ACTIVE",
    "price": {
        "priceType": "FIXED_PRICE",
        "priceUnit": "per_sqm",
        "amountCents": 5600,
        "originalAmountCents": 6500
    },
    "bidMicros": "AUTOMATIC",
    "budgets": {
        "daily": {
            "limitMicros": "30000000",
        },
        "total": {
            "limitMicros": "UNLIMITED",
        }
    },
    "campaignId": 54212,
    "salutation": "COMPANY",
    "sellerName": "My Shop",
    "postcode": "1097DN",
    "regionId": 1700195,
    "phoneNumber": "0207894561",
    "allowContactByEmail": true,
    "vendorId": "OURSHOP-1423453-34",
    "links": {
        "displayUrl": "www.ourshop.com/Faxes",
        "url": "http://www.ourshop.com/index.php?param1=value1&amp;param2=value2&amp;param3=value3"
    },
    "images": [
        {
            "src": "http://www.ourshop.com/img/brother_fax_big.jpg",
        },
        {
            "src": "http://www.ourshop.com/img/brother_fax_side.jpg",
        }
    ],
    "attributes": [
        {
            "key": "color",
            "label": "Kleur",
            "locale": "nl",
            "type": "STRING",
            "value": "Zwart",
        },
        {
            "key": "size",
            "label": "Maat",
            "locale": "nl",
            "type": "NUMBER",
            "value": 6,
        },
        {
            "key": "software",
            "label": "Software",
            "locale": "nl",
            "type": "LIST",
            "value": [
                "Apple OSX",
                "Microsoft Windows 7"
            ],
        }
    ],
    "shippingOptions": [
        {
            "type": "SHIP",
            "costCents": 495,
            "time": "2d-5d"
        },
        {
            "type": "PICKUP",
            "pickupLocation": "1097DN"
        }
    ]
}

POST /ad v3

Scope	api_rw or console_rw
Accept	application/sellside.ad-v3+json, application/json
Content-Type	application/sellside.ad-v3+json; charset=utf-8

Version 3 works just like POST /ad v2, except the response body contains an additional field statusReasons. This field is currently used to indicate the reason why a certain ad might be set to a certain status by our system. This could be due to, for example, an action (like new website domain approval) pending from the user, which is a mechanism used to prevent account takeovers from setting the website URL to a malicious one.

Example

POST /ad
Accept: application/sellside.ad-v3+json, application/json
Content-Type: application/sellside.ad-v3+json; charset=utf-8

{
    "title": "Brother Fax voor 99,99",
    "description": "<b>NU extra voordelig op ourshop.com.</b> Fax nu voor slechts <b>99,99!</b>",
    "categoryId": 826,
    "externalId": "OURSHOP-1423453-34",
    "status": "PAUSED",
    "currency": "EUR",
    "priceType": "FIXED_PRICE",
    "priceUnit": "per_sqm",
    "price": 9999,
    "cpc": 10,
    "totalBudget": 5000,
    "dailyBudget": 2000,
    "salutation": "COMPANY",
    "sellerName": "My Shop",
    "postcode": "1097DN",
    "regionId": 1700195,
    "phoneNumber": "0207894561",
    "allowContactByEmail": true,
    "allowPaypal": true,
    "links": {
        "url": "http://www.ourshop.com/index.php?param1=value1&amp;param2=value2&amp;param3=value3",
        "displayUrl": "www.ourshop.com/Faxes"
    },
    "images": [
        {
            "src": "http://images.ourshop.com/source1.jpg"
        },
        {
            "src": "http://images.ourshop.com/source2.jpg"
        },
        {
            "src": "http://images.ourshop.com/source3.jpg"
        }
    ],
    "attributes": [
        {
            "key": "color",
            "label": "Kleur",
            "locale": "nl_NL",
            "type": "STRING",
            "value": "Zwart"
        },
        {
            "key": "color",
            "label": "Color",
            "locale": "en_US",
            "type": "STRING",
            "value": "Black"
        },
        {
            "key": "size",
            "label": "Maat",
            "locale": "nl_NL",
            "type": "NUMBER",
            "value": 6
        },
        {
            "key": "software",
            "label": "Software",
            "type": "LIST",
            "locale": "nl_NL",
            "value": [
                "Apple OSX",
                "Microsoft Windows 7"
            ]
        }
    ],
    "shippingOptions": [],
    "statusReasons": [
        "DOMAIN_PENDING"
    ]
}

POST /ad v2

Scope	api_rw or console_rw
Accept	application/sellside.ad-v2+json, application/json
Content-Type	application/sellside.ad-v2+json; charset=utf-8

Parameters

Name	Type	Default	Description
_body	boolean	true	Include the created ad in the response body on success. Disabling this will speed up the call.
_include	string	“”	Comma-separated-list of fields to include.
_exclude	string	“”	Comma-separated-list of fields to omit.
_validate	boolean	false	Validate the request without executing it.

Errors

Field	Code	Error message	Description
allowContactByEmail	2001	invalid argument	must be true or false
allowPaypal	2001	invalid argument	must be true or false
attribute.name	2000	missing argument	one of the attributes is wrong: missing the field ‘name’
attribute.name	2004	value too short	one of the attributes is wrong: need at least 1 non-space character
attribute.name	2005	value too long	one of the attributes is wrong: max. length is 32 characters
attribute.type	2000	missing argument	one of the attributes is wrong: missing the field ‘type’
attribute.type	1006	type mismatch	one of the attributes is wrong: unknown type
attribute.value	2000	missing argument	one of the attributes is wrong: missing the field ‘value’
attribute.value	2004	value too short	one of the attributes is wrong: need at least 1 non-space character
attribute.value	2005	value too long	one of the attributes is wrong: max. length is 512 characters
attribute.value	2001	invalid argument	one of the attributes has a wrong value type for provided ‘type’
categoryId	1006	type mismatch	not an integer number
categoryId	2000	missing argument	mandatory field
categoryId	2001	invalid argument	not a valid category id
categoryId	2022	category not active	category is not active and will not allow creation of ads
categoryId	2023	category deleted	category is deleted and will not allow creation/updating of ads
cpc	1006	type mismatch	not an integer number
cpc	2000	missing argument	mandatory field
cpc	2002	out of range	value not between category.minCpc and category.maxCpc
currency	2000	missing argument	mandatory field
currency	2001	invalid argument	not “EUR” or “CAD”
dailyBudget	1006	type mismatch	not an integer number
dailyBudget	2002	out of range	value lower than category.minDailyBudget or higher than totalBudget
description	2000	missing argument	mandatory field
description	2002	out of range	too short or too long; see Categories about the constraints.
externalId	2005	value too long	too short or too long; see Categories about the constraints.
id	1006	type mismatch	not an integer number
id	2001	invalid argument	id must be omitted or set to zero
images.size	2002	out of range	too many image URLs
images.url	2006	invalid url	invalid image URL
links.displayUrl	2005	value too long	max. length is 255
links.url	2005	value too long	max. length is 2048
links.url	2006	invalid url	is not a valid url
phoneNumber	2005	value too long	max. length is 32
phoneNumber	2010	invalid phone number	not a valid phone number
postcode	2005	value too long	max. length is 6
price	1006	type mismatch	not an integer number
price	2000	missing argument	not specifying a price for a priceType which requires a price
price	2001	invalid argument	specifying a price for a priceType without a price
price	2002	out of range	price is not in the interval of (0,10000000000] while priceType requires a valid price
priceType	2001	invalid argument	not a valid price type
salutation	2001	invalid argument	not a valid salutation
sellerName	2000	missing argument	must not be empty
sellerName	2005	value too long	max. length is 60
status	2000	missing argument	mandatory field
status	2001	invalid argument	must be either ACTIVE or PAUSED
title	2000	missing argument	mandatory field
title	2002	out of range	max. length is 60
totalBudget	1006	type mismatch	not an integer number
totalBudget	2002	out of range	value too low/high
vendorId	2005	value too long	max. length is 64 characters

Example

POST /ad
Accept: application/sellside.ad-v2+json, application/json
Content-Type: application/sellside.ad-v2+json; charset=utf-8

{
    "title": "Brother Fax voor 99,99",
    "description": "<b>NU extra voordelig op ourshop.com.</b> Fax nu voor slechts <b>99,99!</b>",
    "categoryId": 826,
    "externalId": "OURSHOP-1423453-34",
    "status": "ACTIVE",
    "currency": "EUR",
    "priceType": "FIXED_PRICE",
    "priceUnit": "per_sqm",
    "price": 9999,
    "cpc": 10,
    "totalBudget": 5000,
    "dailyBudget": 2000,
    "salutation": "COMPANY",
    "sellerName": "My Shop",
    "postcode": "1097DN",
    "regionId": 1700195,
    "phoneNumber": "0207894561",
    "allowContactByEmail": true,
    "allowPaypal": true,
    "links": {
        "url": "http://www.ourshop.com/index.php?param1=value1&amp;param2=value2&amp;param3=value3",
        "displayUrl": "www.ourshop.com/Faxes"
    },
    "images": [
        {
            "src": "http://images.ourshop.com/source1.jpg"
        },
        {
            "src": "http://images.ourshop.com/source2.jpg"
        },
        {
            "src": "http://images.ourshop.com/source3.jpg"
        }
    ],
    "attributes": [
        {
            "key": "color",
            "label": "Kleur",
            "locale": "nl_NL",
            "type": "STRING",
            "value": "Zwart"
        },
        {
            "key": "color",
            "label": "Color",
            "locale": "en_US",
            "type": "STRING",
            "value": "Black"
        },
        {
            "key": "size",
            "label": "Maat",
            "locale": "nl_NL",
            "type": "NUMBER",
            "value": 6
        },
        {
            "key": "software",
            "label": "Software",
            "type": "LIST",
            "locale": "nl_NL",
            "value": [
                "Apple OSX",
                "Microsoft Windows 7"
            ]
        }
    ],
    "shippingOptions": [
        {
            "type": "SHIP",
            "cost": 0,
            "time": "2d-5d"
        },
        {
            "type": "PICKUP",
            "pickupLocation": "1097DN"
        }
    ],
    "paypalEmail": "test@example.com"
}