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&#39;s email address
          example: jane@doe.com
        first_name:
          type: string
          description: the lead&#39;s first name
          example: Jane
        last_name:
          type: string
          description: the lead&#39;s last name
          example: Doe
        business_phone:
          type: string
          description: the lead&#39;s phone number
        country:
          type: string
          description: the lead&#39;s country
        company_name:
          type: string
          description: the lead&#39;s company name
        industry:
          type: string
          description: the lead&#39;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