> This page is for Advertising Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# Submit a creative for ad quality review

POST https://{HUMAN-API-URL}/api-v2/gw/push
Content-Type: application/json

HUMAN will provide the `HUMAN-API-URL` and `X-API-KEY` during the integration process.

You can integrate the HUMAN Ad Quality Platform via all Ad Formats Creative Submission and Responses. You can submit creatives for Ad Quality analysis using this endpoint, then retrieve the results via the [Pulling API](/advertising/reference/get-all-creatives) or [Push Result API](/advertising/reference/push-result-api-overview).

Reference: https://docs.humansecurity.com/advertising/reference/submit-request

## Authentication

- `X-API-KEY` header (required) — Your unique Ad Quality API key.

## Request

### Body (application/json)

This endpoint expects an object.

- `ad` (ad, required) — An object that contains details about a single creative.

## Response

### 200

Creative submitted properly

## Errors

### 400 Bad Request Error

There were one or more issues with the request

- `any`

### 401 Unauthorized Error

Authorization denied

- `any`

## Types

### ad

An object that contains details about a single creative.

- `id` (string, required) — The unique ID associated with the creative, as defined by your ad platform.
- `ad_format` (enum, required) — The detected media type of the creative. Possible values are `HTML5_DISPLAY`, `VAST`, `MRAID`, and `NATIVE`.
  - Allowed values: `HTML5_DISPLAY`, `VAST`, `MRAID`, `NATIVE`
- `custom_account_ids` (custom_account_ids, optional) — An object containing IDs that correspond to the creative. Ideally, you should provide as many of these IDs as you can, but a full list is not required.
- `name` (string, optional) — A descriptive name for the creative.
- `adomain` (list of string, optional) — The top-level domain(s) of the advertiser who owns the creative.
- `brand` (string, optional) — The brand name of the advertiser behind the creative.
- `cat` (list of string, optional) — A list of IAB categories associated with the creative.
- `cattax` (integer, optional) — The [IAB taxonomy](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#list_categorytaxonomies) used to define the creative’s categories.
- `landing_page` (string, optional) — The URL where users will land if they click on the ad.
- `iurl` (string, optional) — A direct link (without cache busting) to an image of the ad creative.
- `adm` (string, optional) — If the `ad_format` is **NATIVE**, do not include `adm`. Use the [`native`](#request.body.ad.native) object described below instead. Either `adm` or `native` is **required**. The full ad markup of the creative. * **For HTML5 creatives:** This may include HTML/JS code (i.e. `"<img src='https://...'><br />Enjoy yourself"`) * **For VAST creatives:** This should include the full VAST XML (i.e. `"<VAST xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-..."`)
- `native` (AdNative, optional) — This is applicable only for **NATIVE** creatives. The `ad.native` object replaces [`adm`](#request.body.ad.adm). Either `adm` or `native` is **required**. **At least one** of the following parameters is **required**.

### custom_account_ids

- `seat_id` (string, optional) — An identifier for the buying seat.
- `organization_id` (string, optional) — An identifier for the owning organization.
- `agency_id` (string, optional) — The ID of the ad agency who represents the advertiser associated with the creative.
- `advertiser_id` (string, optional) — The ID of the advertiser associated with the creative.
- `publisher_id` (string, optional) — The ID of the publisher where the creative is intended to be displayed.
- `site_id` (string, optional) — The ID of the website where the creative is intended to be displayed.
- `campaign_id` (string, optional) — The ID of the campaign associated with the creative.
- `bidder_id` (string, optional) — The ID of the bidder associated with the creative.

### AdNative

This is applicable only for **NATIVE** creatives. The `ad.native` object replaces [`adm`](#request.body.ad.adm). Either `adm` or `native` is **required**. **At least one** of the following parameters is **required**.

- `title` (string, optional) — The headline or title text of the native ad.
- `desc` (string, optional) — A description or body text for the native ad.
- `image` (string, optional) — A URL to the image asset displayed in the native ad.
- `link` (string, optional) — The clickthrough URL for the native ad.

## Examples

**Request**

```json
{
  "ad": {
    "id": "123-creative-ID",
    "ad_format": "VAST",
    "custom_account_ids": {
      "seat_id": "123",
      "organization_id": "123123"
    },
    "name": "Test - wine",
    "adomain": [
      "adomain.com"
    ],
    "brand": "my-cool-brand",
    "cat": [
      "IAB3"
    ],
    "cattax": 5,
    "landing_page": "http://landingpage.com",
    "iurl": "http://iurl.com",
    "adm": "<VAST xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-..."
  }
}
```

**Response**

```json
{}
```

**SDK Code**

```python
import requests

url = "https://{human-api-url}/api-v2/gw/push"

payload = { "ad": {
        "id": "123-creative-ID",
        "ad_format": "VAST",
        "custom_account_ids": {
            "seat_id": "123",
            "organization_id": "123123"
        },
        "name": "Test - wine",
        "adomain": ["adomain.com"],
        "brand": "my-cool-brand",
        "cat": ["IAB3"],
        "cattax": 5,
        "landing_page": "http://landingpage.com",
        "iurl": "http://iurl.com",
        "adm": "<VAST xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-..."
    } }
headers = {
    "X-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{human-api-url}/api-v2/gw/push';
const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"ad":{"id":"123-creative-ID","ad_format":"VAST","custom_account_ids":{"seat_id":"123","organization_id":"123123"},"name":"Test - wine","adomain":["adomain.com"],"brand":"my-cool-brand","cat":["IAB3"],"cattax":5,"landing_page":"http://landingpage.com","iurl":"http://iurl.com","adm":"<VAST xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-..."}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{human-api-url}/api-v2/gw/push"

	payload := strings.NewReader("{\n  \"ad\": {\n    \"id\": \"123-creative-ID\",\n    \"ad_format\": \"VAST\",\n    \"custom_account_ids\": {\n      \"seat_id\": \"123\",\n      \"organization_id\": \"123123\"\n    },\n    \"name\": \"Test - wine\",\n    \"adomain\": [\n      \"adomain.com\"\n    ],\n    \"brand\": \"my-cool-brand\",\n    \"cat\": [\n      \"IAB3\"\n    ],\n    \"cattax\": 5,\n    \"landing_page\": \"http://landingpage.com\",\n    \"iurl\": \"http://iurl.com\",\n    \"adm\": \"<VAST xmlns:xsi=\\\"http://www.w3.org/2001/XMLSchema-...\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://{human-api-url}/api-v2/gw/push")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"ad\": {\n    \"id\": \"123-creative-ID\",\n    \"ad_format\": \"VAST\",\n    \"custom_account_ids\": {\n      \"seat_id\": \"123\",\n      \"organization_id\": \"123123\"\n    },\n    \"name\": \"Test - wine\",\n    \"adomain\": [\n      \"adomain.com\"\n    ],\n    \"brand\": \"my-cool-brand\",\n    \"cat\": [\n      \"IAB3\"\n    ],\n    \"cattax\": 5,\n    \"landing_page\": \"http://landingpage.com\",\n    \"iurl\": \"http://iurl.com\",\n    \"adm\": \"<VAST xmlns:xsi=\\\"http://www.w3.org/2001/XMLSchema-...\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://{human-api-url}/api-v2/gw/push")
  .header("X-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"ad\": {\n    \"id\": \"123-creative-ID\",\n    \"ad_format\": \"VAST\",\n    \"custom_account_ids\": {\n      \"seat_id\": \"123\",\n      \"organization_id\": \"123123\"\n    },\n    \"name\": \"Test - wine\",\n    \"adomain\": [\n      \"adomain.com\"\n    ],\n    \"brand\": \"my-cool-brand\",\n    \"cat\": [\n      \"IAB3\"\n    ],\n    \"cattax\": 5,\n    \"landing_page\": \"http://landingpage.com\",\n    \"iurl\": \"http://iurl.com\",\n    \"adm\": \"<VAST xmlns:xsi=\\\"http://www.w3.org/2001/XMLSchema-...\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://{human-api-url}/api-v2/gw/push', [
  'body' => '{
  "ad": {
    "id": "123-creative-ID",
    "ad_format": "VAST",
    "custom_account_ids": {
      "seat_id": "123",
      "organization_id": "123123"
    },
    "name": "Test - wine",
    "adomain": [
      "adomain.com"
    ],
    "brand": "my-cool-brand",
    "cat": [
      "IAB3"
    ],
    "cattax": 5,
    "landing_page": "http://landingpage.com",
    "iurl": "http://iurl.com",
    "adm": "<VAST xmlns:xsi=\\"http://www.w3.org/2001/XMLSchema-..."
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://{human-api-url}/api-v2/gw/push");
var request = new RestRequest(Method.POST);
request.AddHeader("X-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"ad\": {\n    \"id\": \"123-creative-ID\",\n    \"ad_format\": \"VAST\",\n    \"custom_account_ids\": {\n      \"seat_id\": \"123\",\n      \"organization_id\": \"123123\"\n    },\n    \"name\": \"Test - wine\",\n    \"adomain\": [\n      \"adomain.com\"\n    ],\n    \"brand\": \"my-cool-brand\",\n    \"cat\": [\n      \"IAB3\"\n    ],\n    \"cattax\": 5,\n    \"landing_page\": \"http://landingpage.com\",\n    \"iurl\": \"http://iurl.com\",\n    \"adm\": \"<VAST xmlns:xsi=\\\"http://www.w3.org/2001/XMLSchema-...\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["ad": [
    "id": "123-creative-ID",
    "ad_format": "VAST",
    "custom_account_ids": [
      "seat_id": "123",
      "organization_id": "123123"
    ],
    "name": "Test - wine",
    "adomain": ["adomain.com"],
    "brand": "my-cool-brand",
    "cat": ["IAB3"],
    "cattax": 5,
    "landing_page": "http://landingpage.com",
    "iurl": "http://iurl.com",
    "adm": "<VAST xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-..."
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://{human-api-url}/api-v2/gw/push")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```