OpenAPI Specification
openapi: 3.0.3
info:
title: Brightcove Analytics API Reference Access Tokens Leads API
description: "Reference for the Brightcove Analytics API, used to retrieve analytics data for your accounts. To test API requests, you can use our <a href=\"/getting-started/concepts-testing-tools-brightcove-apis.html\" target=\"_blank\">API Testing Tools</a>.\n\nFor additional in-depth guides to features of the API, see the **[general documentation](/analytics/index.html)**.\n\n **Base URL**: https://analytics.api.brightcove.com"
x-bc-access: public
version: 1.0.0
servers:
- url: https://analytics.api.brightcove.com
variables: {}
tags:
- name: Leads
description: Get leads for a Video Cloud account.
paths:
/accounts/{{account_id}}/leads:
get:
tags:
- Leads
summary: Get Leads
description: Get leads for an account
operationId: GetLeads
security:
- BC_OAuth2:
- video-cloud/audience/read
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/sort_leads'
- $ref: '#/components/parameters/fields_leads'
- $ref: '#/components/parameters/where'
- $ref: '#/components/parameters/from'
- $ref: '#/components/parameters/to'
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/Get_Leads_Response'
'400':
description: 'BAD_REQUEST_ERROR: Query parameters are invalid '
'401':
description: 'UNAUTHORIZED_ERROR: The access token is either absent, has expired, or is invalid'
'404':
description: 'RESOURCE_NOT_FOUND: The URL does not exist '
'429':
description: 'REQUEST_THROTTLED_ERROR: The user has exceeded the rate limiting policy'
'500':
description: 'INTERNAL_ERROR: An internal error has occurred '
'504':
description: 'GATEWAY_TIMEOUT_ERROR: The server timed out while fulfilling your request'
deprecated: false
x-operation-settings:
CollectParameters: false
AllowDynamicQueryParameters: false
AllowDynamicFormParameters: false
IsMultiContentStreaming: false
components:
schemas:
LeadsResult:
title: Leads Result
type: object
properties:
created_at:
type: string
description: the date created
email_address:
type: string
description: the lead's email address
example: jane@doe.com
first_name:
type: string
description: the lead's first name
example: Jane
last_name:
type: string
description: the lead's last name
example: Doe
business_phone:
type: string
description: the lead's phone number
country:
type: string
description: the lead's country
company_name:
type: string
description: the lead's company name
industry:
type: string
description: the lead's industry
page_url:
type: string
description: the url for the Brightcove player
player_id:
type: string
description: the ID for the Brightcove player
video_id:
type: string
description: the Video Cloud video id
video_name:
type: string
description: the Video Cloud video name
FieldsLeads:
title: fields
description: Fields for Leads. See [Fields for filtering and selection](/develop/overview-audience-api.html#Retrieving_view_events) for more information
enum:
- video_id
- video_name
- external_id
- first_name
- last_name
- email_address
- business_phone
- country
- company_name
- industry
- player_id
- page_url
- created_at
type: string
example: video_id
x-enum-elements:
- name: video_id
description: Brightcove video id
- name: video_name
description: Brightcove video name
- name: tracking_id
description: Custom tracking id
- name: external_id
description: The Marketo, Eloqua or other custom GUID
- name: player_id
description: Brightcove player id
- name: page_url
description: The URL of the page where the view event was created
- name: watched
description: Percent watched
- name: time_watched
description: Seconds watched
- name: created_at
description: Creation date
- name: updated_at
description: Last modified date
- name: is_synced
description: A boolean denoting whether or not the view event has been synchronized
- name: utm_source
description: UTM field found in the page_url
- name: utm_medium
description: UTM field found in the page_url
- name: utm_medium
description: UTM field found in the page_url
- name: utm_term
description: UTM field found in the page_url
- name: utm_content
description: UTM field found in the page_url
SortLeads:
title: sort for Leads
enum:
- video_id
- video_name
- player_id
- created_at
type: string
example: video_id
default: created_at
x-enum-elements:
- name: video_id
description: Video id
- name: video_name
description: Video name
- name: player_id
description: Player id
- name: created_at
description: When video was created
Get_Leads_Response:
title: Get Leads Response
type: object
properties:
count:
type: number
description: the total number of items
limit:
type: number
description: the limit for items in this request
offset:
type: number
description: the offset for items in this request
result:
type: array
items:
$ref: '#/components/schemas/LeadsResult'
description: array of result items
example:
result:
- email_address: rcrooks@brightcove.com
first_name: Robert
last_name: Crooks
business_phone: ''
company_name: Brightcove
page_url: https://players.brightcove.net/20318290001/HyH9wwb4BZ_default/index.html?playlistId=4344773088001
player_id: HyH9wwb4BZ
video_id: '6038250741001'
video_name: Creating a Smart Playlist
created_at: '2019-07-19T20:26:33.535Z'
external_id: cc8e546c-89e1-4de2-b83a-21fc8a7974f3
- email_address: aladron@brightcove.com
first_name: Alberto
last_name: Ladron
business_phone: ''
company_name: Brightcove
page_url: https://players.brightcove.net/20318290001/HyH9wwb4BZ_default/index.html?playlistId=4344773088001
player_id: HyH9wwb4BZ
video_id: '6038250741001'
video_name: Creating a Smart Playlist
created_at: '2019-07-19T20:26:28.229Z'
external_id: 2e3d9209-0018-4ade-82c7-83d9a15fb5b2
count: 14
offset: 0
limit: 4
parameters:
account_id:
name: account_id
in: path
description: a Video Cloud account ID
required: true
style: simple
explode: false
schema:
type: number
to:
name: to
in: query
description: End time for the period covered by the report — epoch time in milliseconds or a date in the format `yyyy-mm-dd` (such as `2013-09-26`) or a relative date in `d` (days), `h` (hours), `m` (minutes), `s` (seconds) (such as `-2d` or `-6h`)
style: form
explode: true
schema:
oneOf:
- type: string
- type: integer
fields_leads:
name: fields
in: query
description: 'Fields to return for leads
**Note:** by default, all fields are returned. Use this parameter to return fewer fields.'
style: form
explode: true
schema:
$ref: '#/components/schemas/FieldsLeads'
Authorization:
name: Authorization
in: header
description: 'Authorization: Bearer access_token (see Getting Access Tokens)'
required: true
style: simple
explode: false
schema:
type: string
where:
name: where
in: query
description: One or more field==value pairs to filter the results; fields supported are `video_id`, `video_name`, `tracking_id`, `external_id`, `player_id`, `page_url`, `watched`, `time_watched`, `created_at`, `updated_at`, `is_synced`
style: form
explode: true
schema:
type: string
from:
name: from
in: query
description: '''Start time for the period covered by the report — epoch time in milliseconds or a date in the format `yyyy-mm-dd` (such as `2013-09-26`) or a relative date in `d` (days), `h` (hours), `m` (minutes), `s` (seconds) (such as `-2d` or `-6h`)'''
style: form
explode: true
schema:
oneOf:
- type: string
- type: integer
sort_leads:
name: sort
in: query
description: Field to sort lead results by (prefix with `-` for descending order)
style: form
explode: true
schema:
$ref: '#/components/schemas/SortLeads'
Content-Type:
name: Content-Type
in: header
description: 'Content-Type: application/json'
required: true
style: simple
explode: false
schema:
type: string
offset:
name: offset
in: query
description: Number of items to skip
style: form
explode: true
schema:
type: integer
format: int32
default: 0
example: 0
limit:
name: limit
in: query
description: Number of items to return
style: form
explode: true
schema:
type: integer
format: int32
default: 25
example: 25
minimum: 1
maximum: 200
securitySchemes:
BC_OAuth2:
type: oauth2
description: Brightcove OAuth API. See the [support documentation](/oauth/index.html) or [Getting Access Tokens](/oauth/code-samples/oauth-api-sample-get-access-token.html) to learn more
flows:
clientCredentials:
tokenUrl: https://oauth.brightcove.com/v4/access_token
scopes:
video-cloud/analytics/read: Read analytics data
video-cloud/video/read: Read video data
x-bc-implicit-head: true
x-bc-implicit-options: true
x-bc-upstream: https://backend_server