Basis Analytics API
The Analytics API from Basis — 31 operation(s) for analytics.
OpenAPI Specification
openapi: 3.0.0
info:
title: Basis Platform Analytics API
version: v1
description: "\n# Introduction\n\nThe Basis API is designed to be easy to use and simple to test to help customers\nand partners get up and running quickly. Use the API endpoints to connect to\nBasis to retrieve campaign planning and delivery data. The current version of\nthe API is v1.\n\n# Getting Started\n\nThe Basis API is a RESTful API. This means that the API is designed to allow you\nto work with objects using familiar HTTP verbs.\n\n* read = GET\n* create = POST\n* update = PUT\n* delete = DELETE\n\nAll production API requests are made to [https://api.basis.net/v1](https://api.basis.net/v1).\nThere is also a testing sandbox to use when developing and testing applications,\nwith requests being made to [https://api-sandbox.basis.net/v1](https://api-sandbox.basis.net/v1).\nThe Basis API is available to Centro customers and integration partners, and all\norganizations must acquire valid credentials prior to using the web services.\nContact your Centro representative to obtain valid credentials.\n\n#### API Request Limits\n\nTo maintain optimum performance and ensure that the Basis Platform API is available to all our customers,\nBasis balances transaction loads by imposing rate limits of 75,000 requests per hour across all endpoints per API user.\n\nGenerating client credentials tokens is also limited to 10 per hour, with a maximum of 25 per day. More information\non this can be found in the Client Credentials Flow section below.\n\n# Authentication\n\nAll API endpoints require authentication. Basis API uses [OAuth2](https://oauth.net/2/). Supported grant types:\n\n* [Authorization Code](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow)\n* [Client Credentials](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow)\n* [Refresh Token](https://auth0.com/docs/secure/tokens/refresh-tokens/use-refresh-tokens)\n\nThe password grant flow has now been deprecated. Please update your applications to use one of the above two flows.\n\nIf you encounter any issues or challenges while setting up the OAuth connection, please don't hesitate to contact us\nfor support.\n\nPlease note that OAuth authentication uses `https://auth.basis.net` not `https://api.basis.net`.\n\n#### Authorization Code Flow\n\nTo authorize your API access, visit the following URL in your browser, replacing\nplaceholders with your specific values as needed:\n\n`https://auth.basis.net/authorize?response_type=code&client_id=<client_id>&scope=openid profile email offline_access&state=<your state token>&redirect_uri=<redirect URI>&audience=https://api.basis.net`\n\nAfter successful authorization you will be redirected to your specified redirect\nURI and the authorization code as well as the `state` (more info\n[here](https://www.oauth.com/oauth2-servers/getting-ready/)) supplied in the\nrequest will be passed as parameters.\n\nOnce you have this auth code you will need to make a second request to get a token which\ncan be used to make API requests:\n\n```\ncurl -X POST https://auth.basis.net/oauth/token\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'grant_type=authorization_code' \\\n --data-urlencode 'client_id=<your application ID>' \\\n --data-urlencode 'client_secret=<your application secret>' \\\n --data-urlencode 'code=<authorization code>' \\\n --data-urlencode 'redirect_uri=<your application redirect URI>'\n```\n\nThis token can then be sent along with API requests in the Authorization header as\noutlined in the next section. If you want a refresh token as well, make sure to include\nthe `offline_access` scope in the /authorize request above.\n\nNote: In order to use this flow successfully, your application needs to have an associated\nredirect URI. If you did not previously have a redirect URI set and need to set one, reach\nout to Basis support.\n\n#### Client Credentials Flow\n\n```\ncurl --location 'https://auth.basis.net/oauth/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'grant_type=client_credentials' \\\n --data-urlencode 'client_id=<your application ID>' \\\n --data-urlencode 'client_secret=<your application secret>' \\\n --data-urlencode 'audience=https://api.basis.net'\n```\n\nA few important notes:\n* Your application must have an associated owner ID (i.e. agency ID) in order to use this flow. \n It will return a 401 otherwise. If you did not previously have an owner ID set and need to set\n one, reach out to Basis support.\n* This token returns all clients for an agency, so if there are restricted clients, we recommend\n using the authorization code flow above.\n* Endpoints providing user information will return a 404, since this token is associated with\n an organization, not a user.\n\n##### Client Credentials Token Quota\n\nClient credentials token generation is limited to **10 per hour**, with a maximum of **25 per day**.\nIf you exceed this limit, you'll receive a `429 Too Many Requests` error. Please reach out to\nBasis Support if you need to increase this limit.\n\nIf you receive this 429 error, you can check the headers of the response for real-time information\non your current usage and limits. See the\n[official Auth0 docs](https://auth0.com/docs/fine-grained-m2m-token-quotas-early-access#monitor-token-quota-consumption)\nfor more information.\n\n#### Refresh Token Flow\n```\ncurl --location 'https://auth.basis.net/oauth/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'grant_type=refresh_token' \\\n --data-urlencode 'client_id=<your application ID>' \\\n --data-urlencode 'client_secret=<your application secret>' \\\n --data-urlencode 'refresh_token=<your refresh token>' \\\n```\n\nA few important notes:\n* Only the authorization code flow returns a refresh token.\n* The refresh token can be used to obtain a new access token when the current one expires.\n* The refresh token flow will itself return a refresh token.\n\n#### Request Data\n\nOnce you have your access token from the token response you can make requests to\nthe API with header `Authorization: Bearer <access_token>`.\n\nFor example:\n\n```\ncurl -X GET \"https://api.basis.net/v1/agency\" -H \"Authorization: Bearer <access_token>\"\n```\n\nTo try the endpoints within this documentation, click **Authorize** below, and\nuse a token obtained via any of the above methods to fill in the \"Bearer\" field.\n\n# Analytics API\n\nThe analytics API gives you access to delivery statistics and details of your\nBasis resources:\n\n* agency\n* clients\n* brands\n* campaigns\n* line items\n* groups\n* tactics\n* add-ons\n* vendors\n* properties\n* verticals\n* key performance indicators (KPI)\n\n## Statistics\n\nRetrieve statistics by calling\n\n`GET /v1/stats/{scope}`\n\nUse the scope parameter to choose how the statistics are aggregated:\n\n* line_item\n* daily_by_line_item\n* daily\n\nA line item describes the details of a media purchase or programmatic buy.\nStatistics returned for each line item include delivery metrics, such as\nimpressions, clicks, and video completions, and performance metrics like eCPM,\neCPC, and eCPV.\n\n## Finding Resource Details\n\nMany of the Analytics API endpoints list all of a particular type of resource, like\n\n`GET /v1/brands`\n\nwhich returns a list of all of your brands, as well as the ID, name, creation\ntimestamp, and verticals for each.\n\nMany other endpoints return details for one resource, like\n\n`GET /v1/brands/{id}`\n\nwhich returns the ID, name, creation timestamp, and verticals for the brand with\nthe given brand ID.\n\n### Resource Relationships\n\nCampaigns have\n\n* 1 client\n* 1 brand\n* many line items\n* many add-ons\n\nLine items have\n\n* 1 campaign\n* 1 property\n* 1 vendor\n\nCampaign details returned by `GET /v1/campaigns/{id}` or `GET /v1/campaigns`\ninclude the client_id and brand_id for the campaign. To find the line items for\na campaign, call `GET /v1/campaigns/{id}/line_items`.\n"
servers:
- url: https://api.basis.net
tags:
- name: Analytics
paths:
/v1/me:
get:
tags:
- Analytics
description: Returns the currently authenticated user
security:
- Bearer: []
OAuth2: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
id:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
description: Bad Request
type: object
properties:
message:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
type: object
properties:
message:
type: string
'404':
description: User not found
content:
application/json:
schema:
description: User not found
type: object
properties: {}
/v1/agency:
get:
tags:
- Analytics
description: Returns details for the agency, the organization representing a buyer.
security:
- Bearer: []
OAuth2: []
responses:
'200':
description: Successful Response
content:
application/json:
schema:
description: Successful Response
type: object
properties:
data:
type: object
properties:
id:
type: string
name:
type: string
dsp_advertiser_id:
type: string
created_at:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
type: object
properties:
message:
type: string
/v1/brands/{id}:
get:
tags:
- Analytics
description: Returns details for one brand.
parameters:
- schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[34][0-9a-fA-F]{3}-[89ab][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
in: path
name: id
required: true
description: Identifies a single brand.
security:
- Bearer: []
OAuth2: []
responses:
'200':
description: Successful Response
content:
application/json:
schema:
description: Successful Response
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Identifies a single brand.
name:
type: string
description: The name of the brand.
created_at:
type: string
verticals:
type: array
items:
type: object
properties:
id:
type: string
description: Identifies a single vertical.
name:
type: string
description: The name of the vertical.
created_at:
type: string
description: The date and time the vertical was added.
subverticals:
type: array
items:
type: object
properties:
id:
type: string
description: Identifies a single sub-vertical.
name:
type: string
description: The name of the sub-vertical.
created_at:
type: string
description: The date and time the sub-vertical was added.
'400':
description: Bad Request
content:
application/json:
schema:
description: Bad Request
type: object
properties:
message:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
type: object
properties:
message:
type: string
'404':
description: Brand not found
content:
application/json:
schema:
description: Brand not found
type: object
properties: {}
/v1/brands:
get:
tags:
- Analytics
description: Lists all brands.
parameters:
- schema:
type: string
in: query
name: cursor
required: false
description: Used to paginate through the list of records. Don't set this parameter to see the first page of records, then check the metadata object in the response for the cursor to use to fetch the next page.
- schema:
type: string
in: query
name: query
required: false
description: Used to refine the results by a chosen parameter. Valid parameters = name
- schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[34][0-9a-fA-F]{3}-[89ab][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
in: query
name: client_id
required: false
description: Identifies a single client. Set this parameter to limit the brands to the specified client.
security:
- Bearer: []
OAuth2: []
responses:
'200':
description: Successful Response
content:
application/json:
schema:
description: Successful Response
type: object
properties:
metadata:
type: object
properties:
cursor:
type:
- 'null'
- string
description: Use this cursor value in your next call to this endpoint to return the next set of items
page_size:
type: integer
total:
type: integer
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identifies a single brand.
name:
type: string
description: The name of the brand.
created_at:
type: string
verticals:
type: array
items:
type: object
properties:
id:
type: string
description: Identifies a single vertical.
name:
type: string
description: The name of the vertical.
created_at:
type: string
description: The date and time the vertical was added.
subverticals:
type: array
items:
type: object
properties:
id:
type: string
description: Identifies a single sub-vertical.
name:
type: string
description: The name of the sub-vertical.
created_at:
type: string
description: The date and time the sub-vertical was added.
'400':
description: Bad Request
content:
application/json:
schema:
description: Bad Request
type: object
properties:
message:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
type: object
properties:
message:
type: string
/v1/clients/{id}:
get:
tags:
- Analytics
description: Returns details for one client. An agency can represent multiple clients, and each client can have multiple brands.
parameters:
- schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[34][0-9a-fA-F]{3}-[89ab][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
in: path
name: id
required: true
description: Identifies a single client.
security:
- Bearer: []
OAuth2: []
responses:
'200':
description: Successful Response
content:
application/json:
schema:
description: Successful Response
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Identifies a single client.
name:
type: string
billing_name:
type:
- 'null'
- string
contact_first_name:
type:
- 'null'
- string
contact_last_name:
type:
- 'null'
- string
contact_email:
type:
- 'null'
- string
contact_phone:
type:
- 'null'
- string
contact_extension:
type:
- 'null'
- string
notes:
type:
- 'null'
- string
created_at:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
description: Bad Request
type: object
properties:
message:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
type: object
properties:
message:
type: string
'404':
description: Client not found
content:
application/json:
schema:
description: Client not found
type: object
properties: {}
/v1/clients:
get:
tags:
- Analytics
description: Lists all clients.
parameters:
- schema:
type: string
in: query
name: cursor
required: false
description: Used to paginate through the list of records. Don't set this parameter to see the first page of records, then check the metadata object in the response for the cursor to use to fetch the next page.
- schema:
type: string
in: query
name: query
required: false
description: Used to refine the results by a chosen parameter. Valid parameters are name, contact_first_name, contact_last_name, contact_email, billing_name, notes
security:
- Bearer: []
OAuth2: []
responses:
'200':
description: Successful Response
content:
application/json:
schema:
description: Successful Response
type: object
properties:
metadata:
type: object
properties:
cursor:
type:
- 'null'
- string
description: Use this cursor value in your next call to this endpoint to return the next set of items
page_size:
type: integer
total:
type: integer
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identifies a single client.
name:
type: string
billing_name:
type:
- 'null'
- string
contact_first_name:
type:
- 'null'
- string
contact_last_name:
type:
- 'null'
- string
contact_email:
type:
- 'null'
- string
contact_phone:
type:
- 'null'
- string
contact_extension:
type:
- 'null'
- string
notes:
type:
- 'null'
- string
created_at:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
description: Bad Request
type: object
properties:
message:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
type: object
properties:
message:
type: string
/v1/vendors/{id}:
get:
tags:
- Analytics
description: Returns details for one vendor, an entity or organization selling and offering products, content, or services for payment. Examples of vendors would include the owners of websites that offer advertisement space and exchanges that offers ad space on multiple websites.
parameters:
- schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[34][0-9a-fA-F]{3}-[89ab][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
in: path
name: id
required: true
description: Identifies a single vendor.
security:
- Bearer: []
OAuth2: []
responses:
'200':
description: Successful Response
content:
application/json:
schema:
description: Successful Response
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Identifies a single vendor.
name:
type: string
type:
type: string
created_at:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
description: Bad Request
type: object
properties:
message:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
type: object
properties:
message:
type: string
'404':
description: Vendor not found
content:
application/json:
schema:
description: Vendor not found
type: object
properties: {}
/v1/vendors:
get:
tags:
- Analytics
description: Lists all vendors, entities or organizations selling and offering products, content, or services for payment. Examples of vendors would include the owners of websites that offer advertisement space and exchanges that offers ad space on multiple websites.
parameters:
- schema:
type: string
in: query
name: cursor
required: false
description: Used to paginate through the list of records. Don't set this parameter to see the first page of records, then check the metadata object in the response for the cursor to use to fetch the next page.
- schema:
type: string
in: query
name: query
required: false
description: Used to refine the results by a chosen parameter. Valid parameters = name
- schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[34][0-9a-fA-F]{3}-[89ab][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
in: query
name: campaign_id
required: false
description: Identifies a single campaign.
security:
- Bearer: []
OAuth2: []
responses:
'200':
description: Successful Response
content:
application/json:
schema:
description: Successful Response
type: object
properties:
metadata:
type: object
properties:
cursor:
type:
- 'null'
- string
description: Use this cursor value in your next call to this endpoint to return the next set of items
page_size:
type: integer
total:
type: integer
data:
type: array
items:
type: object
properties:
id:
type: string
description: Identifies a single vendor.
name:
type: string
type:
type: string
created_at:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
description: Bad Request
type: object
properties:
message:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
type: object
properties:
message:
type: string
/v1/properties/{id}:
get:
tags:
- Analytics
description: Returns details for one property--inventory (advertising space) available for sale, often a website or network.
parameters:
- schema:
type: string
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[34][0-9a-fA-F]{3}-[89ab][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
in: path
name: id
required: true
description: Identifies a single property.
security:
- Bearer: []
OAuth2: []
responses:
'200':
description: Successful Response
content:
application/json:
schema:
description: Successful Response
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Identifies a single property.
name:
type: string
type:
type: string
url:
type:
- 'null'
- string
created_at:
type: string
verticals:
type: array
items:
type: string
description: Identifies a single vertical.
included:
type: object
properties:
verticals:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
created_at:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
description: Bad Request
type: object
properties:
message:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
description: Unauthorized
type: object
properties:
message:
type: string
'404':
description: Property not found
content:
application/json:
schema:
description: Property not found
type: object
properties: {}
/v1/properties:
get:
tags:
- Analytics
description: Lists all properties, inventory (advertising space) available for sale, often websites or networks.
parameters:
- schema:
# --- truncated at 32 KB (125 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/basis/refs/heads/main/openapi/basis-analytics-api-openapi.yml