Bombora Accounts API

openapi: 3.2.0
info:
  title: Account List Accounts API
  description: The Account List API provides the ability to define and maintain lists of accounts.
  version: '1.1'
servers:
- url: https://api.bombora.com/account-list/v1
tags:
- name: Accounts
paths:
  /account-list/{accountListId}/accounts:
    post:
      tags:
      - Accounts
      operationId: updateAccounts
      summary: Add/Update Accounts
      description: 'Adds or updates accounts in the account list.

        - Only valid for Manual Account List Type.

        - If id is not specified for an account, the domain is used as the account identifier.

        - If the account identifier does not match an existing account in the account list, the account will be inserted.

        - If the account identifier matches an existing account in the account list, the existing account will be updated.

        - If there are duplicate account identifiers in the request body, the request will be rejected.'
      parameters:
      - $ref: '#/components/parameters/accountListId'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                - domain
                properties:
                  domain:
                    $ref: '#/components/schemas/domain'
                  id:
                    $ref: '#/components/schemas/id'
                  attributes:
                    $ref: '#/components/schemas/attributes'
            example:
            - domain: google.com
            - domain: bombora.com
              id: Custom provided ID
            - domain: bing.com
              attributes:
                ceoTShirtSize: M
                rank: 4
      responses:
        '200':
          description: Success - The request has been processed successfully.
        '202':
          description: Success - The request has been accepted for processing.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
      security:
      - bearerAuth: []
    delete:
      tags:
      - Accounts
      summary: Delete Account List Contents
      description: 'This idempotent endpoint deletes all accounts within the account list, but does not delete the account list itself.

        - Only valid for Manual Account List Type.'
      parameters:
      - $ref: '#/components/parameters/accountListId'
      responses:
        '200':
          description: Success - The request has been processed successfully.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
      security:
      - bearerAuth: []
      operationId: deleteAccountListByAccountListIdAccounts
      x-operation-id-source: derived
  /account-list/{accountListId}/accounts/domains:
    get:
      tags:
      - Accounts
      summary: Get Account Domains
      description: Returns all distinct domains in an account list
      parameters:
      - $ref: '#/components/parameters/accountListId'
      responses:
        '200':
          description: Success - The response body includes the requested resource.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: The domain name
              example:
              - bombora.com
              - starbucks.com
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      security:
      - bearerAuth: []
      operationId: getAccountListByAccountListIdAccountsDomains
      x-operation-id-source: derived
  /account-list/{accountListId}/accounts/search:
    post:
      tags:
      - Accounts
      summary: Retrieve Account Data Request
      description: 'The POST is used before the corresponding GET endpoint to describe the required attributes and filters in the request body.

        A prefix of `attributes.` is necessary if attempting to filter by optional account attributes in your list.

        When attributes is empty or unspecified, the id is returned by default.'
      parameters:
      - $ref: '#/components/parameters/accountListId'
      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:
                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:
              Example with Domain Filter:
                summary: Defines a collection of attributes to be returned in the GET response body, along with a filter that excludes .edu domains.
                value:
                  attributes:
                  - company.size
                  - company.hq
                  filter:
                    a: domain
                    neq: '*.edu'
              Example with Optional Account Attributes:
                summary: Includes optional account attributes as a return (if available) and as a filter requirement.
                value:
                  attributes:
                  - attributes.ceoTShirtSize
                  - company.hq
                  filter:
                    a: attributes.rank
                    gt: '1'
              Example with Country Filter:
                summary: Defines 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: []
      operationId: postAccountListByAccountListIdAccountsSearch
      x-operation-id-source: derived
    get:
      tags:
      - Accounts
      summary: Retrieve Account Data
      description: 'Allows paginated account data to be retrieved for an Account List.


        Data is retrieved by first calling the POST endpoint with a request body that describes the data to be retrieved through this GET endpoint.

        The response from the POST endpoint will include a page token that should be supplied to this endpoint as a query parameter.


        Each 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.

        All results have been returned when nextPageToken is null.


        Example URL with query parameters

        ```

        https://api.bombora.com/account-list/v1/account-list/{accountListId}?pageToken={pageToken}&limit=100

        ```'
      parameters:
      - $ref: '#/components/parameters/accountListId'
      - 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: 10000
          description: Number of results to return per page, maximum 10000.
      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:
                accounts:
                - domain: bombora.com
                  id: '123456'
                  attributes:
                    customObjectId: '12389367'
                    Country: US
                  company:
                    size: Medium-Small (50 - 199 Employees)
                    hq:
                      city: New York
                      state: NY
                      country: US
                      address: 115 E 23RD ST
                      address2: 7TH FL
                      zip: '10010'
                - '...'
                nextPageToken: nSA21gW
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
      security:
      - bearerAuth: []
      operationId: getAccountListByAccountListIdAccountsSearch
      x-operation-id-source: derived
  /account-list/{accountListId}/delete-accounts:
    post:
      tags:
      - Accounts
      summary: Delete Accounts
      description: 'Deletes the specified accounts from the account list.

        - Only valid for Manual Account List Type.'
      parameters:
      - $ref: '#/components/parameters/accountListId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - ids
              properties:
                ids:
                  type: array
                  description: An array of Ids used to identify which accounts to delete from account list.
                  items:
                    type: string
                    description: The account identifiers to be deleted from the account list.
            example:
              ids:
              - Top Account
              - bombora.com
      responses:
        '200':
          description: Success - The request has been processed successfully.
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '422':
          $ref: '#/components/responses/UnprocessableEntityError'
      security:
      - bearerAuth: []
      operationId: postAccountListByAccountListIdDeleteAccounts
      x-operation-id-source: derived
components:
  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
    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
    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'
    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
    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'
    ErrorMessageResponse:
      type: object
      properties:
        message:
          type:
          - string
          - 'null'
    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
    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
    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
    id:
      type:
      - string
      - 'null'
      description: The unique identifier of an account within an account list. When null, the value in the domain attribute is used as a unique identifier for the account.
      example: '123456'
    domain:
      type: string
      description: Domain name associated with the account.
    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 }

            '
    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
    attributes:
      type:
      - object
      - 'null'
      description: "Any optional attributes provided for the account represented as a string. \nUnsupported characters: '\"'\n"
      example:
        attributes:
          external_id: A34231
          account_rep: Adam Smith
  responses:
    UnprocessableEntityError:
      description: The request body is syntactically correct but semantically incorrect, such as validation errors.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageResponse'
    UnauthorizedError:
      description: The access token is missing or invalid.
    NotFoundError:
      description: The resource could at this path does not exist.
    ConflictError:
      description: Resource could not be retrieved due to a conflict with the current state of the resource (pending update or currently in use).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessageResponse'
    BadRequestError:
      description: The request is syntactically invalid.
    ForbiddenError:
      description: The access token does not have permission to access this API.
  parameters:
    accountListId:
      name: accountListId
      in: path
      required: true
      description: The unique identifier (AccountListId) of the account list.
      schema:
        type: string
        format: uuid
      example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT