openapi: 3.2.0
info:
  title: Intent Data API
  description: 'The Intent API allows signals to be seamlessly defined and managed, while also providing efficient access to actionable intent data.


    ### **Security**

    All API endpoints are secured with OAuth 2.0 bearer token authentication. Developers must include a valid Bearer token in the Authorization request header to access endpoints.

    Go to the [Get Started](/get-started) page for additional details.


    ### **Error Handling**

    The API returns appropriate HTTP status codes and error messages in case of unauthorized access (401 Unauthorized) or forbidden actions (403 Forbidden), ensuring secure and reliable interaction.


    ### **Reference Data**

    The API may utilize reference attribute data within a request or response body. See [Reference API](/docs/reference-api/1/overview) for a complete list of supported reference attributes.

    '
  version: '1.0'
servers:
- url: https://api.bombora.com/intent/v1
security:
- bearerAuth: []
tags:
- name: Data
paths:
  /data:
    get:
      tags:
      - Data
      summary: Retrieve Intent Data
      description: "Allows paginated intent data to be retrieved.\n* Response body size will not exceed 10MB.\n\nData is retrieved by first calling the POST endpoint with a request body that describes the data to be retrieved through this GET endpoint. \nThe response from the POST endpoint will include a page token that should be supplied to this endpoint as a query parameter.\n\nEach call to the GET endpoint will return an object including the data requested and the next page token, which can be supplied to a subsequent call to retrieve the next page.\nAll results have been returned when nextPageToken is null.\n\nExample URL with query parameters\n```\nhttps://api.bombora.com/intent/v1/data?pageToken={pageToken}&limit=100\n```\n"
      parameters:
      - name: pageToken
        in: query
        required: true
        description: Page token for paginated retrieval.
        schema:
          type: string
        example: nSA21gW
      - name: limit
        in: query
        schema:
          type: integer
          format: int32
          default: 100
          maximum: 10000
          description: Number of results to return per page. If result size exceeds 10MB response body limit, the number of returned results will be lower than the specified limit.
      responses:
        '200':
          description: Success - The response body includes the requested resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      description: The returned object will contain the data attributes specified in the attributes array in the POST request body.
                  nextPageToken:
                    type:
                    - string
                    - 'null'
                    description: The page token to retrieve the next page of data. When null, there are no more pages available.
              example:
                data:
                - domain: nasa.gov
                  score: 95
                  scoreLabel: Strong
                - domain: ast-science.com
                  score: 93
                  scoreLabel: Strong
                - domain: he360.com
                  score: 87
                  scoreLabel: Strong
                nextPageToken: nSA21gW
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
      security:
      - bearerAuth: []
    post:
      tags:
      - Data
      summary: Retrieve Intent Data Request
      description: 'The POST is used before the corresponding GET endpoint to describe the required attributes and filters in the request body.

        When attributes is empty or unspecified, the domain, score, and scoreLabel attributes are returned by default.

        The request body must contain either a `signalDefinitionId` OR `topics`, but cannot contain both.

        '
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: 'An optional body that specifies attributes to be returned or filters that should be applied to the data returned by the GET endpoint.

                '
              properties:
                signalDefinitionId:
                  description: Unique identifier of a Signal Definition.
                  type: string
                  format: UUID
                topics:
                  description: A collection of [topic names](/docs/reference-api/1/routes/topics/get) to retrieve data for.
                  type: array
                  items:
                    type: string
                    maximum: 50
                attributes:
                  $ref: '#/components/schemas/Attributes'
                filters:
                  oneOf:
                  - $ref: '#/components/schemas/Eq'
                  - $ref: '#/components/schemas/Neq'
                  - $ref: '#/components/schemas/In'
                  - $ref: '#/components/schemas/Nin'
                  - $ref: '#/components/schemas/Gt'
                  - $ref: '#/components/schemas/Gte'
                  - $ref: '#/components/schemas/Lt'
                  - $ref: '#/components/schemas/Lte'
                  - $ref: '#/components/schemas/And'
                  - $ref: '#/components/schemas/Or'
            examples:
              Domain Filter using Signal Definition:
                summary: Defines a collection of attributes to be returned in the GET response body, along with a filter that excludes .edu domains.
                value:
                  signalDefinitionId: 517134f7-4451-4941-9491-8c5c7750d49a
                  attributes:
                  - areasOfInterest
                  - company.size
                  - company.hq
                  filter:
                    a: domain
                    neq: '*.edu'
              Account List Filter using List of Topics:
                summary: Defines a collection of attributes to be returned in the GET response body, along with a filter that restricts the domains returned to accounts in the specified account list.
                value:
                  topics:
                  - Bombora
                  - B2B Marketing
                  attributes:
                  - areasOfInterest
                  - company.size
                  - company.hq
                  filter:
                    a: domain
                    eq: accountList:7fa79789-097c-4414-965f-ba0a08af7ea5
              Example wih Country Filter:
                summary: Defines a combination of attributes to be returned in the GET response body, along with a filter that restricts the domains returned to accounts in London, United Kingdom  SW1A 1AA.
                value:
                  filter:
                    and:
                    - a: company.hq.country
                      eq: GB
                    - a: company.hq.city
                      eq: London
                    - a: company.hq.zip
                      eq: SW1A 1AA
      responses:
        '200':
          description: Success - The response body includes the pageToken that must be supplied to the GET endpoint to retrieve results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  pageToken:
                    type: string
              example:
                pageToken: nSA21gW
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
      security:
      - bearerAuth: []
components:
  responses:
    UnauthorizedError:
      description: The access token is missing or invalid.
    BadRequestError:
      description: The request is syntactically invalid.
    ForbiddenError:
      description: The access token does not have permission to access this API.
    UnprocessableEntityError:
      description: The request body is syntactically correct but semantically incorrect, such as validation errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageResponse'
  schemas:
    And:
      type: object
      description: And operator, allowing for multiple filters to be joined.
      required:
      - and
      properties:
        and:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/Eq'
            - $ref: '#/components/schemas/Neq'
            - $ref: '#/components/schemas/In'
            - $ref: '#/components/schemas/Nin'
            - $ref: '#/components/schemas/Gt'
            - $ref: '#/components/schemas/Gte'
            - $ref: '#/components/schemas/Lt'
            - $ref: '#/components/schemas/Lte'
      example:
        Simple:
          summary: This example shows where the score must be greater than 80 AND the company HQ country must be equal to US.
          value:
            and:
            - a: score
              gt: 80
            - a: company.hq.country
              eq: US
    Gte:
      type: object
      description: Greater Than or Equal To operator. The data value must be greater than or equal to this value.
      required:
      - a
      - gte
      properties:
        a:
          type: string
          description: The attribute that the condition applies to.
        gte:
          type: string
          description: The value which the attribute is evaluated.
      example:
        Simple:
          summary: This example shows where the score must be greater than or equal to 65.
          value: '{ "a": "score", "gte": 65 }

            '
    Gt:
      type: object
      description: Greater Than operator. The data value must be greater than this value.
      required:
      - a
      - gt
      properties:
        a:
          type: string
          description: The attribute that the condition applies to.
        gt:
          type: string
          description: The value which the attribute is evaluated.
      example:
        Simple:
          summary: This example shows where the score must be greater than 65.
          value:
            a: score
            gt: 65
    Attributes:
      type: array
      items:
        type: string
        enum:
        - domain
        - topic
        - researchCountry
        - researchState
        - researchMetro
        - score
        - scoreLabel
        - topicsCount
        - topics
        - topics.id
        - topics.name
        - topics.score
        - topics.personas
        - areasOfInterest
        - personas
        - company
        - company.name
        - company.industry
        - company.size
        - company.revenue
        - company.hq
        - company.hq.address
        - company.hq.address2
        - company.hq.country
        - company.hq.state
        - company.hq.city
        - company.hq.zip
      description: "The available attributes that can be retrieved.\n\nPlease note: Key Attributes form part of the unique identifier for each record when specified. In addition to the domain attribute, the topic, researchCountry, researchState, and researchMetro attributes are Key Attributes.\n\nAttributes | Descriptions\n----------------|-------------\ndomain | (Key) The domain of the company.\ntopic |  (Key) The intent [topic](/docs/reference-api/1/routes/topics/get). When specified, data will apply at the intent topic level, in addition to domain and any other specified key fields.\nresearchCountry | (Key) ISO 3166-2 [Country](/docs/reference-api/1/routes/geographic/country/get) Code that the research originates. When specified, data will apply at the country level, in addition to domain and any other specified key fields.\nresearchState | (Key) The [state](/docs/reference-api/1/routes/geographic/state/get) (US and CA only) that the research originates. When specified, data will apply at the country and state level, in addition to domain and any other specified key fields.\nresearchMetro | (Key) The [metro](/docs/reference-api/1/routes/geographic/metro-area/get) area that the research originates. When specified, data will apply at the metro level, in addition to domain and any other specified key fields. This attribute cannot be specified with researchCountry or researchState.\nscore | The score associated with this record. \nscoreLabel | A categorization label associated with the score.\ntopicsCount | The count of topics associated with this record.\ntopics | An array of [topic data](/docs/reference-api/1/routes/topics/get) associated with this record. Includes all nested topics.* attributes. Cannot be used alongside `topic` attribute.\ntopics.id | A unique topic identifier.\ntopics.name | The topic's name.\ntopics.score | The score associated with the topic.\ntopics.personas | The [personas](/docs/reference-api/1/routes/demographic/b2b-personas/get) associated with the topic. Please reach out to your Bombora representative to find out how to enable access to this attribute.\nareasOfInterest | The topics showing intent, ordered by topic score descending.\npersonas | The [personas](/docs/reference-api/1/routes/demographic/b2b-personas/get) associated with this record. Please reach out to your Bombora representative to find out how to enable access to this attribute.\ncompany | Includes all nested company.* attributes.\ncompany.name  | The company name\ncompany.industry  | The [company industry](/docs/reference-api/1/routes/firmographic/industry/get)\ncompany.size  | The [company size](/docs/reference-api/1/routes/firmographic/company-size/get)\ncompany.revenue | The [company revenue](/docs/reference-api/1/routes/firmographic/revenue/get)\ncompany.hq  | The company HQ geographic information in a nested structure\ncompany.hq.address  | First line of address\ncompany.hq.address2 | Second line of address\ncompany.hq.country  | ISO 3166-2 [Country](/docs/reference-api/1/routes/geographic/country/get) Code\ncompany.hq.state  | [State](/docs/reference-api/1/routes/geographic/state/get) (returned for US and CA only)\ncompany.hq.city | City\ncompany.hq.zip  | Postal code\n"
      example:
        attributes:
        - areasOfInterest
        - company.size
        - company.hq
    Lte:
      type: object
      description: Less Than or Equal To operator. The data value must be less than or equal to this value.
      required:
      - a
      - lte
      properties:
        a:
          type: string
          description: The attribute that the condition applies to.
        lte:
          type: string
          description: The value which the attribute is evaluated.
      example:
        Simple:
          summary: This example shows where the score must be less than or equal to 75.
          value:
            a: score
            lte: 75
    Neq:
      type: object
      description: "Not-Equal operator. The data must not be equal to this value. \nWildcards are supported, for example `\"a\": \"domain\", \"neq\": \"*.edu\"`.\n"
      required:
      - a
      - neq
      properties:
        a:
          type: string
          description: The attribute that the condition applies to.
        neq:
          type: string
          description: The value which the attribute is evaluated.
      example:
        Simple:
          summary: This example shows where the company HQ country must not be US.
          value:
            a: company.hq.country
            neq: US
        Wildcard:
          summary: This example shows where a domain must not be an .edu domain.
          value:
            a: domain
            neq: '*.edu'
        Account List:
          summary: This example shows where a domain must not appear in the specified account list.
          value:
            a: domain
            neq: accountList:7fa79789-097c-4414-965f-ba0a08af7ea5
    ErrorMessageResponse:
      type: object
      properties:
        message:
          type:
          - string
          - 'null'
    Eq:
      type: object
      description: "Equal operator. The data must be equal to this value. \nWildcards are supported, for example `\"a\": \"domain\", \"eq\": \"*.edu\"`.\n"
      required:
      - a
      - eq
      properties:
        a:
          type: string
          description: The attribute that the condition applies to.
        eq:
          type: string
          description: The value which the attribute is evaluated.
      example:
        Simple:
          summary: This example shows where the company HQ country must be US.
          value:
            a: company.hq.country
            eq: US
        Wildcard:
          summary: This example shows where a domain must be an .edu domain.
          value:
            a: domain
            eq: '*.edu'
        Account List:
          summary: This example shows where a domain must appear in the specified account list.
          value:
            a: domain
            eq: accountList:7fa79789-097c-4414-965f-ba0a08af7ea5
    In:
      type: object
      description: In operator. The data value must appear in this collection of values.
      required:
      - a
      - in
      properties:
        a:
          type: string
          description: The attribute that the condition applies to.
        in:
          type: array
          description: The collection of values which the attribute value must match.
          items:
            type: string
      example:
        Simple:
          summary: This example shows where the company HQ country must be in US or CA.
          value:
            a: company.hq.country
            in:
            - US
            - CA
        Account List:
          summary: This example shows where a domain must appear in the specified account list. This is functionally identical to specifying an accountList with the eq operator.
          value:
            a: domain
            in:
            - accountList:7fa79789-097c-4414-965f-ba0a08af7ea5
    Nin:
      type: object
      description: Not-In operator. The data value must not appear in this collection of values.
      required:
      - a
      - nin
      properties:
        a:
          type: string
          description: The attribute that the condition applies to.
        nin:
          type: array
          description: The collection of values which the attribute is evaluated.
          items:
            type: string
      example:
        Simple:
          summary: This example shows where the company HQ country must not be in US or CA.
          value:
            a: company.hq.country
            nin:
            - US
            - CA
        Account List:
          summary: This example shows where a domain must not appear in the specified account list. This is functionally identical to specifying an accountList with the neq operator.
          value:
            a: domain
            nin:
            - accountList:7fa79789-097c-4414-965f-ba0a08af7ea5
    Lt:
      type: object
      description: Less Than operator. The data value must be less than this value.
      required:
      - a
      - lt
      properties:
        a:
          type: string
          description: The attribute that the condition applies to.
        lt:
          type: string
          description: The value which the attribute is evaluated.
      example:
        Simple:
          summary: This example shows where the score must be less than 75.
          value:
            a: score
            lt: 75
    Or:
      type: object
      description: Or operator, allowing for multiple filters to be joined.
      required:
      - or
      properties:
        or:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/Eq'
            - $ref: '#/components/schemas/Neq'
            - $ref: '#/components/schemas/In'
            - $ref: '#/components/schemas/Nin'
            - $ref: '#/components/schemas/Gt'
            - $ref: '#/components/schemas/Gte'
            - $ref: '#/components/schemas/Lt'
            - $ref: '#/components/schemas/Lte'
      example:
        Simple:
          summary: This example shows where the score must be greater than 80 OR the company HQ country must be equal to US.
          value:
            or:
            - a: score
              gt: 80
            - a: company.hq.country
              eq: US
        Complex:
          summary: This example shows where [the score must be greater than 80 AND the company HQ country must be equal to US] OR [the score must be greater than 70 AND the company HQ country must be equal to CA].
          value:
            or:
            - and:
              - a: score
                gt: 80
              - a: company.hq.country
                eq: US
            - and:
              - a: score
                gt: 70
              - a: company.hq.country
                eq: CA
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT