Skip to main content

Bidding

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:

  1. You upload a bid
  2. We store it in justtrack. Here, the status will be pending.
  3. 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
  4. 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​

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/v1/bids

Request​

{
  "page": {
    "offset": integer,
    "limit": integer,
  },
  "filter": {
    "adsetId": string,
    "campaignId": string,
    "countryCode": string,
    "partnerId": integer,
    "sourceId": string
  }
}
NameTypeDescription
page.offsetuintNumber of bids to skip for this filter
page.limituintMaximum number of bids to return
filter.partnerIduintjusttrack's identifier for the advertising partner
filter.adsetIdstringThe identifier for the adset that originated with the partner
Optional: set to null when not needed
filter.campaignIdstringThe identifier for the campaign that originated with the partner
Optional: set to null when not needed
filter.countryCodestringThe two-character ISO country code derived from the IP
Optional: set to null when not needed
filter.sourceIdstringThe ad partner's identifier of the media source where the ad is shown
Optional: set to null when not needed

Responses​

200
{
    "results": [
        {
            "adsetId": string,
            "campaignId": string,
            "countryCode": string,
            "partnerId": integer,
            "sourceId": string,
            "status": string,
            "value": float
        }
    ]
}
NameTypeDescription
adsetIdstringThe identifier for the adset that originated with the partner
campaignIdstringThe identifier for the campaign that originated with the partner
countryCodestringThe two-character ISO country code derived from the IP
partnerIduintjusttrack's identifier for the advertising partner
sourceIdstringThe ad partner's identifier of the media source where the ad is shown
statusstringStatus of the latest bid operation
valuefloat64Current value of the bid
400
{
  "error": string
}
NameTypeDescription
errorstringdescription 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.

POST /management/v1/bids/upload

Request​

[
    {
        "partnerId": uint,
        "adsetId": string,
        "campaignId": string,
        "countryCode": string,
        "delete": boolean,
        "optimalBidUsd": float,
        "sourceId": string
    }
]
NameTypeDescription
partnerIduintjusttrack's identifier for the advertising partner
adsetIdstringThe identifier for the adset that originated with the partner
Optional: set to null when not needed
campaignIdstringThe identifier for the campaign that originated with the partner ID
countrystringThe two-character ISO country code derived from the IP
deletebooleanWhether or not this operation is delete
Optional: default is false
optimalBidUsdfloat64The target bid value, in USD
sourceIdstringThe ad partner's identifier of the media source where the ad is shown
Optional: set to null when not needed

Responses​

204
{}
400
{
    "error": string,
    "bidsValidation": [
        {
            "adsetId": string,
            "campaignId": string,
            "campaignName": string,
            "countryCode": string,
            "partnerName": string,
            "partnerId": integer,
            "sourceId": string,
            "status": string,
            "delta": {
                "changePercentage": float,
                "newValue": float,
                "oldValue": float
            },
            "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:

  • Adset bidding isn't enabled for this partner
  • Adset not found
  • Bid value is below minimum
  • Bidding isn't enabled for this partner
  • Campaign bidding isn't enabled for this partner
  • Campaign has the wrong optimization type for bidding
  • Can't delete campaign bid
  • Can't delete non-existent bid
  • Given decimal precision isn't supported for this partner
  • Missing campaign attributes
  • Missing client partner vendor attributes
  • Missing credentials
  • Missing partner vendor attributes
  • Source ID bid requires adset to be set
  • Source ID bidding isn't enabled
  • Specified country isn't part of the campaign
500
{
    "error": string
}
Jump to