Workflow API Overview

The BidCore Workflow API provides a REST based interface to view, create, update and delete entities in the system. With this API you can operate with and customize any parts of your workflow.

Auth Overview

The first step in using the API is to authenticate successfully. Users can authenticate through OAuth2 authorization, obtaining a temporary access token with a limited lifetime. After receiving the token, users can request data, adding the access token to the request.

Auth Token

Endpoint Info

Description

endpoint

https://uauth.iponweb.com/oauth2/token/

Method

GET

username

(Required) Your UI username

password

(Required) Your UI password

scope

(Required) The service to which your user token should grant you access, e.g. "scope=service_id=demo.bidcore.iponweb.com"

Getting an Auth Token

Make an HTTP POST request to the following URL. The response will contain your access token and its expiration time. You can use this token to perform API requests until the token expires.

https://uauth.iponweb.com/oauth2/token/

Sample AUTH Request

curl https://uauth.iponweb.com/oauth2/token/ \
-k -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "username=$username" \
-d "password=$password" \
-d "scope=service_id=demo.bidcore.iponweb.com"

Sample AUTH Response

{
  "token_type": "Bearer",
  "scope": "service_id=demo.bidcore.iponweb.com",
  "access_token": "<access_token>",
  "expires_in": 3600
}

GET Usage

GET Endpoint

Endpoint Info

Description

Endpoint

/publishers/

Method

GET

Required Header

You must include the auth token for all requested to the endpoint Authorization: Bearer <access_token>

Sample GET Request

curl -k --header "Authorization: Bearer $access_token" https://demo.bidcore.iponweb.com/publishers/

Sample GET Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "Publisher Norma Hitchcock XXXVI",
            "external_id": "abc",
            "url": "https://pub.com"
        }
    ]
}

POST Usage

POST Endpoint

Endpoint Info

Description

Endpoint

/brands/

Method

POST

Required Headers

  • Authorization: Bearer <access_token>

  • Content-Type: application/json;charset=UTF-8

Data

(Required) JSON containing all the required fields. See the Workflow OpenAPI Docs for details.

Note

When you update an entity, it is advisable to send the entire object that you received earlier in the request to prevent validation errors.

Sample POST Request

curl -k 'https://demo.bidcore.iponweb.com/brands/' \
-X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer $access_token' \
--data-binary '{"name": "BrandName", "is_open_auction_allowed": true, "is_pmp_allowed": false, "external_id": "BrandExternalId", "advertiser_domains": ["brand.domain.arpa", "another.brand.domain.arpa"]}'

Sample POST Response

{
    "is_pmp_allowed": false,
    "name": "BrandName",
    "is_open_auction_allowed": true,
    "external_id": "BrandExternalId",
    "id": 8053,
    "advertiser_domains": ["brand.domain.arpa","another.brand.domain.arpa"]
}

Supported Methods

There is a variety of use cases which you can address using the API. For example: accessing and updating inventory (publishers, ad units, etc.), adding or deleting supply or demand side entities (brands, agencies, bidders). As the BidCore API is RESTful it supports the following HTTP Methods.

Methods

Method

Description

GET

Gets an entities list

POST

Creates an entity

PUT

Updates an entity

DELETE

Deletes an entity

Response Codes

The REST API uses HTTP Response Codes to inform whether a request was successful. When the operation is successful, the API responds with a 2xx code and in the case of an error — with 4xx (application errors) or 5xx (server errors).

Code

Meaning

200 OK

Successful GET request

201 Created

Successful POST request

204 No Content

Successful PUT or DELETE request

400 Bad Request

Unsupported query parameters, the request failed validation

401 Unauthorized

The user is unauthenticated or does not have access

403 Forbidden

The user doesn’t have permission to perform this action

404 Not Found

The requested resource doesn’t exist

405 Method Not Allowed

The requested resource exists, but an unsupported method was requested

406 Not acceptable

Invalid action, e.g. the user tried to delete dependent entities

409 Conflict

Database Error

429 Too Many Requests

Throttling limit was exceeded

500 Internal Server Error

General Server Problems

504 Gateway Timeout

Request was too large, timed out