Bidding API v0

INTERNAL DOCUMENT

This document is for internal use only. Please don't share a link to this page outside of your organization.

Deprecated

This API is deprecated. Please migrate to our new Bids API.

With the Bidding API, you can:

Fetch the status of current bid uploads
Upload bids

Bid upload workflow

Bidding operates as a distributed transaction. The sequential flow is as follows:

You upload a bid
We store it in justtrack. Here, the status will be pending.
We try to apply it on partner side
- If successful, we'll change the status to success
- If unsuccessful, we'll rollback the change by fetching the current value from partner. We'll also change the status to rollback-error.
  - If the rollback is successful, the status will remain rollback-error
  - If the rollback failed, we'll change the status to error
We update the bid based on the returning status. In the case of newly created bids, this includes deleting them to ensure a consistent state between justtrack and the partner.

This process can take up to 30 minutes for rollbacks. Only then will you see a stable status.

info

We gather bids and apply them on the partner side in batches. This increases throughput and overall speed in which changes are applied.

As a downside, if one bid in one batch fails, the entire batch is rejected and enters the rollback process.

Fetch bids API

With this API, you can request with the bids within justtrack. In addition, it exposes the status of the latest operation associated with the bid.

POST /management/v0/bids

Request

{
  "page": {
    "offset": integer,
    "limit": integer,
  },
  "filter": {
    "networkId": integer,
    "campaignId": integer,
    "adSetId": integer,
    "country": string,
    "sourceId": string
  }
}

Name	Type	Description
`page.offset`	int	Number of bids to skip for this filter
`page.limit`	int	Maximum number of bids to return
`filter.networkId`	int	justtrack internal network ID Optional: set to `null` when not needed
`filter.campaignId`	int	justtrack internal campaign ID Optional: set to `null` when not needed
`filter.adSetId`	int	justtrack internal ad set ID Optional: set to `null` when not needed
`filter.country`	string	ISO 3166-1 alpha-2 code of your country, e.g. "DE" Optional: set to `null` when not needed
`filter.sourceId`	string	Identifier provided by ad network to target specific source app. Optional: set to `null` when not needed

The following filter combinations are eligible:

networkId
campaignId
campaignId + country
campaignId + country + sourceId
adSetId
adSetId + country
adSetId + country + sourceId

Response

Success: HTTP 200

[{
  "networkId": integer,
  "campaignId": integer,
  "adSetId": integer,
  "country": string,
  "sourceId": string,
  "status": string,
  "value": float
}]

Name	Type	Description
`networkId`	int	justtrack internal network ID
`campaignId`	int	justtrack internal campaign ID
`adSetId`	int / null	justtrack internal ad set ID
`country`	string / null	ISO 3166-1 alpha-2 code of your country, e.g. "DE"
`sourceId`	string / null	Identifier provided by ad network to target specific source app.
`status`	string	Current status of the latest bid operation
`value`	float	Current value of the bid

Invalid input: HTTP 400

{
  "error": string
}

Name	Type	Description
`error`	string	description of the error

Upload bids

With this API you can upload a batch of bids, similar to the CSV upload. The same hierarchy, rules, and limitations apply.

curl -X POST -H 'X-API-KEY: `{api key}`' 'https://api.justtrack.io/management/v0/bids/upload' \
-d '[`{"campaign": {"id": 1234}`, "country": "DE", "optimalBidUsd": 0.01, "delete": false}]'

Request

[
    {
        "adSetId": integer,
        "campaign": {
            "id": integer
        },
        "country": string,
        "sourceId": string,
        "optimalBidUsd": float,
        "delete": boolean
    }
]

Name	Type	Description
`adSetId`	int	justtrack internal ad set id Optional: set to null when not needed
`campaign.id`	int	justtrack internal campaign ID
`country`	string	ISO 3166-1 alpha-2 code of your country, e.g. "DE"
`sourceId`	string	Identifier provided by ad network to target specific source app. Optional: set to null when not needed
`optimalBidUsd`	float	The target bid value, in USD
`delete`	boolean	Whether this operation is delete or not Optional: default is false

Response

Success: HTTP 204

{}

Invalid request: HTTP 400

{
    "error": string
    "bidsValidation": [
        {
            "adSetId": integer
            "campaign": {
                "id": integer,
                "name": string
            },
            "country": {
                "id": integer,
                "name": string,
                "iso2": string
            },
            "delta": {
                "changePercentage": float,
                "newValue": float,
                "oldValue": float
            },
            "network": {
                "id": integer,
                "name": string
            },
            "sourceId": string,
            "status": string,
            "message": string
        }
    ]
}

For each bid failing validation an entry to bidsValidation is added, detailing its dimensions, the value change and the reason why it was rejected. Possible reasons include:

ad set bidding isn't enabled for this network
ad set not found
bidding isn't enabled for this network
campaign bidding isn't enabled for this network
countries of the campaign doesn't contain the bid's specified country
campaign has wrong optimization type for bidding
missing credentials
missing campaign attributes
missing client network vendor attributes
missing network vendor attributes
source ID bidding isn't enabled
source ID bid requires ad set to be set
can not delete campaign bid
can not delete non-existent bid
bid value is below minimum
given decimal precision isn't supported for this network

Error: HTTP 500

{
    "err": string
}