BlueConic Groups API

openapi: 3.2.0
info:
  title: BlueConic REST API v2 Groups API
  description: Welcome to the BlueConic REST API v2.
  termsOfService: https://www.blueconic.com/blueconic-terms-and-conditions
  contact:
    name: Contact us
    url: https://support.blueconic.com/hc/en-us/requests/new
  license:
    name: BlueConic
    url: https://github.com/blueconic/openapi/blob/main/LICENSE.MD
  version: '100.0'
servers:
- url: https://{blueconicHostname}/rest/v2
  description: The BlueConic server
  variables:
    blueconicHostname:
      description: BlueConic server hostname, e.g. 'tenant.blueconic.net'
      default: tenantname
tags:
- name: Groups
  description: 'The following methods allow you to create, modify, retrieve, and delete BlueConic groups. To manage group properties, use the Properties endpoints.

    Best practice when updating groups is to use the bulk endpoint rather than a single request for each individual update.'
paths:
  /groups/{grouptype}/{group}:
    get:
      tags:
      - Groups
      summary: Get one group
      description: Retrieves the properties of the specified group.
      operationId: getOneGroupOfGroupType
      parameters:
      - name: grouptype
        in: path
        description: The ID of the BlueConic group type.
        required: true
        schema:
          type: string
        example: company
      - name: group
        in: path
        description: The ID of the BlueConic group.
        required: true
        schema:
          type: string
          pattern: (.*)+
        example: 640d01c7-1c30-4085-adf9-afad6560ec99
      - name: properties
        in: query
        description: Only returns the given group properties in the response.
        schema:
          type: string
        example: email,fullname,visits
      responses:
        '200':
          description: Returns the specified group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/group'
              examples:
                Example group response:
                  description: Example group response
                  value: "{\n  \"id\" : \"41ebc321-b02b-4e8a-a368-82995c81fb18\",\n  \"groupTypeId\": \"company\",\n  \"creationDate\" : \"2023-03-27T10:36:11.990Z\",\n  \"lastModifiedDate\": \"2024-01-10T12:52:44.816Z\",\n  \"properties\" : [ {\n    \"id\" : \"domaingroup\",\n    \"values\" : [ \"DEFAULT\" ]\n  }, {\n    \"id\" : \"fullname\",\n    \"values\" : [ \"blueconic\" ]\n  }, {\n    \"id\" : \"variant\",\n    \"values\" : [ \"a\" ]\n  }, {\n    \"id\" : \"email\",\n    \"values\" : [ \"example@blueconic.com\" ]\n  }]\n}"
        '401':
          description: Authentication failed (unauthorized).
        '404':
          description: The specified group doesn't exist.
        '408':
          description: Request timed out.
        '503':
          description: The server is too busy to handle the request.
      security:
      - oauth2:
        - read:groups
  /groups/{grouptype}:
    get:
      tags:
      - Groups
      summary: Get groups for group type
      description: Retrieves the groups for the given group type
      operationId: getAllGroupsByGroupType
      parameters:
      - name: grouptype
        in: path
        description: The ID of the group type.
        required: true
        schema:
          type: string
      - name: refinement
        in: query
        description: "**Refinement**\n\nSpecifies (URL-encoded) the refinement used to filter groups. If not specified, all groups will be returned.\n\nTo filter groups using refinements you can use the query parameter refinement. The refinement parameter is a URL-encoded JSON object that contains the refinement in the form of one or more filters.\n\n\n**Logical operators**\n\nThe logical operators used when combining multiple filters.\n\n| Name                    | Description |\n| :---------------------- | :---------- |\n| AND                     | All filters should match |\n| OR                      | Any of the filters should match |\n\n**Operators**\n\nThe operators used to filter the property or objectives within a group.\n\n| Name                    | Description |\n| :---------------------- | :---------- |\n| IS_EMPTY                | If the given property value is empty | \n| NOT_IS_EMPTY            | If the given property value is not empty |\n| CONTAINS_ANY            | If the given property value contains any of the given values |\n| CONTAINS_ALL            | If the given property value contains all of the given values |\n| NOT_CONTAINS_ANY        | If the given property value does not contain any of the given values |\n| NOT_CONTAINS_ALL        | If the given property value does not contain all of the given values |\n| IN_RANGE                | If the given property value is in the given range |\n| NOT_IN_RANGE            | If the given property value is not in the given range |\n| IN_LAST_DAYS            | If the given property value is in the last given number of days |\n| NOT_IN_LAST_DAYS        | If the given property value is not in the last given number of days |\n| IN_NEXT_DAYS            | If the given property value is in the next given number of days |\n| NOT_IN_NEXT_DAYS        | If the given property value is not in the next given number of days |\n| IN_LAST_HOURS           | If the given property value is in the last given number of hours |\n| NOT_IN_LAST_HOURS       | If the given property value is not in the last given number of hours |\n| IN_NEXT_HOURS           | If the given property value is in the next given number of hours |\n| NOT_IN_NEXT_HOURS       | If the given property value is not in the next given number of hours |"
        schema:
          $ref: '#/components/schemas/RefinementBean'
        examples:
          URL encoded example:
            description: URL encoded example
            value: '%7B%22property%22%3A%20%22email%22%2C%20%22operator%22%3A%20%22IS_EMPTY%22%7D%0A'
          Example composite refinement (not yet URL-encoded):
            description: Example composite refinement (not yet URL-encoded)
            value: "{\n  \"filters\": [{\n    \"property\": \"email\",\n    \"operator\": \"IS_EMPTY\"\n  }, {\n    \"property\": \"variant\",\n    \"operator\": \"CONTAINS_ANY\",\n    \"values\": [\"VariantA\", \"VariantB\"]\n  }\n  ],\n  \"operator\": \"AND\"\n}"
          Example property filter refinement (not yet URL-encoded):
            description: Example property filter refinement (not yet URL-encoded)
            value: "{\n  \"property\": \"visits\",\n  \"operator\": \"IN_RANGE\",\n  \"fromValue\": 1,\n  \"toValue\": 10\n}\n"
      - name: cursor
        in: query
        description: Defines the starting point of the page for pagination. When cursors are used, each page, except the last page, returns a `nextCursor` value which can be used to retrieve the next page.
        schema:
          type: string
        example: '*'
      - name: count
        in: query
        description: Specifies the number of results to return. Smaller than or equal to 1.000.000.
        schema:
          type: integer
          format: int32
        example: 20
      - name: maxHitsAllowed
        in: query
        description: When greater than 0, enables fast approximate export by limiting total hits (e.g. maxHitsAllowed=200 and count=20 for max 10 pages). Same behavior as segment export.
        schema:
          type: integer
          format: int32
      - name: properties
        in: query
        description: Specifies which group properties values will be returned for each group. If not specified, the values of all group properties will be returned, which may result in a large result set. One or more group property ids, separated by a comma.
        schema:
          type: string
        example: browserversion,email
      responses:
        '200':
          description: 'Returns the groups of the given group type in a streaming fashion (`Transfer-Encoding: chunked`).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupsAPIGroups'
              examples:
                Example groups response:
                  description: Example groups response
                  value: "{\n\"itemsPerPage\":20,\n\"totalPages\":5,\n\"totalResults\":100,\n\"cursor\":\"*\",\n\"nextCursor\":\"AoJylraPsPICPwU4ZDZiMzhmYS0yMmYwLTRmZTAtYmE0My1kOWVlNTFjNWE5MDA\",\n  \"links\" : [ {\n    \"href\" : \"https://localhost/rest/v2/groups/company?cursor=%2A&count=20\",\n    \"rel\" : \"first\",\n    \"type\" : \"application/json\"\n  }, {\n    \"href\" : \"https://localhost/rest/v2/groups/company?cursor=AoJylraPsPICPwU4ZDZiMzhmYS0yMmYwLTRmZTAtYmE0My1kOWVlNTFjNWE5MDA&count=20\",\n    \"rel\" : \"last\",\n    \"type\" : \"application/json\"\n  } ]\n,\n\"groups\": [\n{\n  \"id\" : \"41ebc321-b02b-4e8a-a368-82995c81fb18\",\n  \"groupTypeId\": \"company\",\n  \"creationDate\" : \"2023-03-27T10:36:11.990Z\",\n  \"lastModifiedDate\": \"2024-01-10T12:52:44.816Z\",\n  \"properties\" : [ {\n    \"id\" : \"domaingroup\",\n    \"values\" : [ \"DEFAULT\" ]\n  }, {\n    \"id\" : \"fullname\",\n    \"values\" : [ \"blueconic\" ]\n  }, {\n    \"id\" : \"variant\",\n    \"values\" : [ \"a\" ]\n  }, {\n    \"id\" : \"email\",\n    \"values\" : [ \"example@blueconic.com\" ]\n  }]\n}\n]}"
        '400':
          description: One or more required parameters are missing or invalid.
        '404':
          description: Group type not found.
        '401':
          description: Authentication failed (unauthorized).
        '503':
          description: The server is too busy to handle the request.
      security:
      - oauth2:
        - read:groups
  /groups:
    put:
      tags:
      - Groups
      summary: Create, update, or delete one or more groups
      description: Create, update, or delete one or more groups in a single request. This is the recommended way of creating, updating and deleting groups.
      operationId: createUpdateDeleteGroups
      requestBody:
        description: '**Group strategy**


          The following values are valid strategies for group operations. These can be used to create, update or delete groups.


          | Name         | Description                                                                                |

          | :----------- |:-------------------------------------------------------------------------------------------|

          | UPSERT   | Will update (and insert if not found) the group based on the rules passed along.           |

          | UPDATE   | Will update (but doesn’t insert if not found) the group based on the rules passed along. |

          | DELETE   | Will delete the group with the given ID.                                                 |


          **Limits**


          * Each request can contain up to 1000 entries. If this limit is exceeded, a HTTP 413 will be thrown (the first 1000 entries will be processed and returned in the response).

          * When too many requests are sent concurrently, a HTTP 429 can be thrown. BlueConic recommends designing your app to be resilient to this scenario. For example, implement a request queue with an exponential backoff algorithm.'
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BulkGroupInputEntry'
            examples:
              Basic create group example:
                description: Example that shows how to create one group.
                value: "[{\n    \"properties\": [{\n            \"id\": \"company_test_zipcode\",\n            \"values\": [\"02111\", \"02112\"],\n            \"strategy\": \"SET\"\n        },\n        {\n            \"id\": \"company_test_email\",\n            \"values\": [\"jane@example.com\"],\n            \"strategy\": \"SET\"\n        }\n    ],\n    \"domainGroup\": \"DEFAULT\",\n    \"groupId\": \"f7daa9db-5ea0-40c8-b9dc-96e519151f8c\",\n    \"groupType\": \"company_test\",\n    \"strategy\": \"UPSERT\"\n}]"
              Advanced example:
                description: "This request contains three operations:\n\n* The first operation looks up a specific BlueConic group by its id, then sets the property with id crm_id to 003Kz4Bsaa14 and adds a new entry to email property. If the group cannot be found, nothing will happen.\n* The second operation deletes a specific BlueConic group by its id.\n* The third operation tries to find a BlueConic group by its id in the specified domain. If the group is found, three properties will be set:\n    * Zipcodes `02111` and `02112` will be added.\n    * `email` will be set to `jane@example.com.`\n    * `crm_id` will be set to `002wC4BadR1w`.\n    * If no group can be found, a new group is created in the specified domaingroup. The three properties will be set on the group.\n"
                value: "[{\n    \"groupId\": \"f7daa9db-5ea0-40c8-b9dc-96e519151f8c\",\n    \"groupType\": \"company_test\",\n    \"properties\": [{\n        \"id\": \"company_test_crm_id\",\n        \"values\": [\"003Kz4Bsaa11\"],\n        \"strategy\": \"SET\"\n    }, {\n        \"id\": \"company_test_email\",\n        \"values\": [\"user_0000@gmail.com\"],\n        \"strategy\": \"ADD\"\n    }]\n},\n    {\n        \"groupId\": \"a84fe9e8-ee83-4c1c-8a32-9132f958fe13\",\n        \"groupType\": \"company_test\",\n        \"strategy\": \"DELETE\"\n    },\n    {\n        \"groupId\": \"f8daa9db-5ea0-40c8-b9dc-96e519151f8c\",\n        \"groupType\": \"company_test\",\n        \"properties\": [{\n            \"id\": \"company_test_zipcode\",\n            \"values\": [\"02111\", \"02112\"],\n            \"strategy\": \"ADD\"\n        },\n        {\n            \"id\": \"company_test_email\",\n            \"values\": [\"jane99@example.com\"],\n            \"strategy\": \"ADD\"\n        },\n        {\n            \"id\": \"company_test_crm_id\",\n            \"values\": [\"002wC5BadR1w\"],\n            \"strategy\": \"SET\"\n        }\n        ],\n        \"strategy\": \"UPSERT\",\n        \"domainGroup\": \"85ee8f33-15a3-4e95-aff5-abfa5bc457ab\"\n    }\n]"
        required: true
      responses:
        '200':
          description: "Bulk response \n\n**JSON Response**\n\nEvery bulk operation is returned in the response as well.\nThe state can be one of the following values: `CREATED`, `SKIPPED`, `MODIFIED`, `DELETED`, `UNCHANGED`, `NOTFOUND`, or `UNKNOWN_GROUP_TYPE`.\n\n```json\n[{\n    \"state\": \"CREATED\",\n    \"groupId\": \"group-ID of the created group\",\n    \"groupTypeId\": \"group-type-ID of the created group\",\n    \"identifier\": \" my-external-identifier\"\n}]\n```"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkGroupResultBean'
              examples:
                Example bulk response:
                  description: Example bulk response
                  value: "[\n  {\n    \"groupId\": \"f7daa9db-5ea0-40c8-b9dc-96e519151f8c\",\n    \"groupTypeId\": \"company_test\",\n    \"state\": \"MODIFIED\"\n  },\n  {\n    \"groupId\": \"a84fe9e8-ee83-4c1c-8a32-9132f958fe13\",\n    \"groupTypeId\": \"company_test\",\n    \"state\": \"DELETED\"\n  }\n]"
        '400':
          description: One or more required parameters are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRequestBean'
        '401':
          description: Authentication failed (unauthorized).
        '403':
          description: Forbidden, invalid (PII) permissions to perform the request. Please check your OAuth Application configuration.
        '413':
          description: More than the allowed 1000 entries are sent in the request. The entries that are processed are returned in the response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkResultBean'
              examples:
                Example bulk response:
                  description: Example bulk response
                  value: "[\n  {\n    \"groupId\": \"f7daa9db-5ea0-40c8-b9dc-96e519151f8c\",\n    \"groupTypeId\": \"company_test\",\n    \"state\": \"MODIFIED\"\n  },\n  {\n    \"groupId\": \"a84fe9e8-ee83-4c1c-8a32-9132f958fe13\",\n    \"groupTypeId\": \"company_test\",\n    \"state\": \"DELETED\"\n  }\n]"
        '429':
          description: Too many requests are sent concurrently. BlueConic recommends designing your app to be resilient to this scenario. For example, implement a request queue with an exponential backoff algorithm.
        '503':
          description: The server is too busy to handle the request.
      security:
      - oauth2:
        - write:groups
components:
  schemas:
    BulkResultBean:
      type: object
      properties:
        identifier:
          type: string
          description: The identifier (optionally) as passed in the input, can be used as reference.
        profileId:
          type: string
          description: The profile ID of the profile that was created, updated or deleted.
        state:
          type: string
          description: The possible states for profile related changes.
          enum:
          - CREATED
          - SKIPPED
          - MODIFIED
          - UNCHANGED
          - NOTFOUND
          - RESTRICTION_MISMATCH
          - CONSENT_MISMATCH
          - DELETED
          - UNAUTHORIZED
        timeline:
          type: array
          description: The feedback on the given timeline events.
          items:
            $ref: '#/components/schemas/TimelineResultBean'
        validationErrors:
          type: object
          additionalProperties:
            type: array
            description: The errors found for the given profile changes (if any).
            items:
              type: string
              description: The errors found for the given profile changes (if any).
          description: The errors found for the given profile changes (if any).
    link:
      type: object
      properties:
        Href:
          type: string
          description: The href of the link
        Rel:
          type: string
          description: The link rel e.g. 'self', 'next', etc.
        Type:
          type: string
          description: The type of the link e.g. 'application/json'
    ErrorRequestBean:
      type: object
      properties:
        code:
          type: integer
          format: int32
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorBean'
        message:
          type: string
    TimelineResultBean:
      type: object
      description: The feedback on the given timeline events.
      properties:
        id:
          type: string
          description: The ID for this event.
        identifier:
          type: string
          description: The identifier (optionally) as passed in the input, can be used as reference.
        state:
          type: string
          description: The possible states for timeline events.
          enum:
          - CREATED
          - SET
          - MODIFIED
          - REJECTED
          - NOTFOUND
          - DELETED
        validationErrors:
          type: array
          description: The errors found for the given timeline event changes (if any).
          example:
          - '#/total_revenue/0: expected type: Number, found: String'
          items:
            type: string
            description: The errors found for the given timeline event changes (if any).
            example: '["#/total_revenue/0: expected type: Number, found: String"]'
    property:
      type: object
      description: A property consisting of an ID and a list of values.
      properties:
        id:
          type: string
          description: The ID of the property.
        values:
          type: array
          description: Values for this property.
          items:
            type: string
            description: Values for this property.
    ErrorBean:
      type: object
      properties:
        field:
          type: string
        message:
          type: string
    BulkGroupInputEntry:
      type: object
      properties:
        domainGroup:
          type: string
          default: DEFAULT
          description: Specifies the domain group in which a group is created. Used for matching and creating groups.
        groupId:
          type: string
          description: The BlueConic group ID to search for.
        groupTypeId:
          type: string
          description: The BlueConic group type ID.
        identifier:
          type: string
          description: An (external) identifier which can be passed along with an operation and is returned in the response.
          example: '[[{"id": "email", value: "test@test.com"}]]'
        properties:
          type: object
          description: The rules that will be executed on this group.
          properties:
            id:
              type: string
              description: The profile property ID to apply to this rule for.
            strategy:
              type: string
              description: The strategy to apply to this rule.
              enum:
              - ADD
              - SET
              - SET_IF_EMPTY
              - INCREMENT
              - REMOVE
            values:
              type: array
              description: The values to apply to this rule.
              items:
                type: string
                description: The values to apply to this rule.
        strategy:
          type: string
          default: UPDATE
          description: The strategy to apply to the given entry. Can be used to create, update or delete groups.
          enum:
          - UPSERT
          - UPDATE
          - DELETE
    group:
      type: object
      description: Groups that the profile is a part of.
      properties:
        creationDate:
          type: string
          format: date-time
          description: The creation date of the object. Datetime in UTC in the https://www.ietf.org/rfc/rfc3339.txt format, example = "2025-01-22T11:21:33.872Z".
        groupTypeId:
          type: string
          description: The ID of the BlueConic group type.
        id:
          type: string
          description: The unique identifier for the object.
        lastModifiedDate:
          type: string
          format: date-time
          description: The last modified date of the object. Datetime in UTC in the https://www.ietf.org/rfc/rfc3339.txt format, example = "2025-01-22T11:21:33.872Z".
        properties:
          type: array
          items:
            $ref: '#/components/schemas/property'
    BulkGroupResultBean:
      type: object
      properties:
        groupId:
          type: string
        groupTypeId:
          type: string
        identifier:
          type: string
          description: The identifier (optionally) as passed in the input, can be used as reference.
        state:
          type: string
          description: The possible states for group related changes.
          enum:
          - CREATED
          - SKIPPED
          - MODIFIED
          - UNCHANGED
          - NOTFOUND
          - DELETED
          - UNKNOWN_GROUP_TYPE
        validationErrors:
          type: object
          additionalProperties:
            type: array
            description: The errors found for the given group changes (if any).
            items:
              type: string
              description: The errors found for the given group changes (if any).
          description: The errors found for the given group changes (if any).
    GroupsAPIGroups:
      type: object
      properties:
        cursor:
          type: string
          description: The cursor of the current page. `*` when not passed.
        groups:
          type: array
          description: The groups.
          items:
            $ref: '#/components/schemas/group'
        itemsPerPage:
          type: integer
          format: int32
          description: Number of results per page.
          readOnly: true
        links:
          type: array
          description: The links to the first and next/last page.
          items:
            $ref: '#/components/schemas/link'
        nextCursor:
          type: string
          description: The cursor of the next page (if any).
        totalPages:
          type: integer
          format: int32
          description: The total number of pages.
          readOnly: true
        totalResults:
          type: integer
          format: int32
          description: The total number of results.
          readOnly: true
    RefinementBean:
      type: object
      properties:
        daysCount:
          type: integer
          format: int32
          description: The days count
        filters:
          type: array
          items:
            $ref: '#/components/schemas/RefinementBean'
        fromDate:
          type: string
          description: The from date in ISO 8601 format (e.g. '2025-01-22T11:21:33.872Z')
        fromValue:
          type: integer
          format: int32
          description: The from value
        groupProperty:
          type: string
          description: The group property
        hoursCount:
          type: integer
          format: int32
          description: The hours count
        objective:
          type: string
          description: The objective
        operator:
          type: string
          description: The operator
        property:
          type: string
          description: The property
        toDate:
          type: string
          description: The to date in ISO 8601 format (e.g. '2025-01-22T11:21:33.872Z')
        toValue:
          type: integer
          format: int32
          description: The to value
        values:
          type: array
          description: The values
          items:
            type: string
            description: The values
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Authenticates a registered OAuth 2.0 client. The Authorization code flow and Client credentials flow are supported. Make sure to select the correct flow based on which flow the registered client supports. The client id and client secret can be found in BlueConic by opening the registered client under *Settings* > *Access management* > *Applications*.<br/>**NOTE:** When using the Authorization code flow, the redirect URL of the registered client in BlueConic must be set to `https://rest.apidoc.blueconic.com/oauth-receiver.html` and ''Send Proof Key for Code Exchange'' must be enabled.<br/><br/>To use a Bearer token for authentication, follow these steps: <br/>1. Acquire the token through authentication.<br/>2. Include the token in the request''s Authorization header as Bearer \<token\>.<br/>3. Send the request to access protected resources.<br/>4. Handle token expiration by refreshing or obtaining a new token.'
      flows:
        clientCredentials:
          tokenUrl: /rest/v2/oauth/token
        authorizationCode:
          authorizationUrl: /rest/v2/oauth/authorize
          tokenUrl: /rest/v2/oauth/token
          refreshUrl: /rest/v2/oauth/token