Bidding

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

1. you upload a bid
2. we store it in justtrack -> status: pending
3. we try to apply it on partner side
   a. if successful -> status: success
   b. if error: we rollback the change by fetching the current value from partner -> status: rollback-error
   b.1. rollback succeeded -> status: rollback-error
   b.2. rollback-failed -> status: error
4. We update the bid based on the returning status. In the case of newly creation 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 you will 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, mostly the entire batch is rejected and enters the rollback process.

Fetch current bids with status

This API provides with the bids within justtrack. In addition, it exposes the status of the latest operation associated with the bid.

curl -X POST -H 'X-API-KEY: `{api key}`' 'https://api.justtrack.io/management/v0/bids' \
-d '{"campaignId": 1, "country": "DE", "sourceId": "ffe6f603"}'

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
}