Using the Exchange API

The Exchange API provides a single endpoint that you can use to make requests.

https://e.relay.bid/p/openrtb2

Where:

e-relay.bid - the Exchange API URL
p - The API version (in this case, public)
openrtb2 - the format of the request and response

The body of the request follows the standard OpenRTB 2.5 syntax. For more information on the OpenRTB 2.5 syntax, please refer to the following specification:

OpenRTB 2.5 Specification

When making an Exchange API request, please note the following objects in the request:

location - If an IP address is sent as part of the request, Kevel will use NetAcuity’s Digital Element to look up location data. If Kevel can match location data, this data will be used in the request.
user - need more information here
impression.ext - this object is an open extension point used to determine location of the impression configuration.
impression configuration - there are two different types of impression configurations: bidders, supply.

Bidder Configuration

The bidder configuration will always have the following outer structure:

```
{ 
    "relay": {
        "bidders": {}
    }
}
```

The bidders element describes the configuration of individual demand partners. In the following example, an in-place configuration for Index and AppNexus is provided.

```
{ 
    "relay": {
        "bidders": {
            "index": { "siteId": 123456 },
            "appnexus": {"placementId": abcdef }
        }
    }
}
```

The syntax of the bidders key and value is that for each key (eg. index) we want to send a request to that partner.

In the following example, all BidRequest fields are omitted, except id and imp. This example demonstrates the In Place configuration in context.

```
{ 
    "id": 11111111-bbbb-4444-cccc-333333333333,
    "imp": [
        { 
            "id": "1",
            "banner": {
                "w": 300,
                "h": 250,
                "pos": 1,
                "topframe": 0
            },
            "secure": 1
            "ext": { 
                "relay": {
                    "bidders": {
                        "index": {"siteId": 123456 },
                        "appenexus": {"placementId": abcdef }
                    }
                }
            }
        }, 			
    ],
}
```

The supply configuration has the same overall structure as that of bidders. Instead of bidders, the supply_id key is used, and the value is a string containing a UUID obtained from the configuration API.

```
{ 
    "relay": {
        "supply_id": { a269c016-c8f3-4228-a568-e81cba173e3b }
    }
}
```

Here is an example of the supply configuration in context of a request.

```
{ 
    "id": 11111111-bbbb-4444-cccc-333333333333,
    "imp": [
        { 
            "id": "1",
            "banner": {
                "w": 300,
                "h": 250,
                "pos": 1,
                "topframe": 0
            },
            "secure": 1
            "ext": { 
                "relay": {
                    "supply_id": { a269c016-c8f3-4228-a568-e81cba173e3b }
                }
            }
        }, 			
    ],
}
```

The semantic meaning of the supply_id is for Relay to lookup the stored bidders configuration for this UUID, replace it in the request and then operate as in the bidders configuration.

A sample cURL request assuming either of the above BidRequests were placed in example.json, and were something either Index Exchange or AppNexus were willing to bid upon.

```
curl -H 'Content-Type: application/json' https://e.relay.bid/p/openrtb2?a=ACCOUNT_ID -d @example.json
```

The query parameter a is short for account id. An account ID will be created for you during onboarding and would be substituted for ACCOUNT_ID in the URL.