Customer.io Group API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Pipelines Group API
  description: '# Overview

    In general, you''ll consume this API through one of our source libraries—our JavaScript client library or any of our server packages.'
servers:
- url: https://cdp.customer.io/v1
  description: The base URL for all Data Pipelines calls in our United States (US) region.
- url: https://cdp-eu.customer.io/v1
  description: The base URL for all Data Pipelines calls in our European Union (EU) region.
tags:
- name: Group
paths:
  /group:
    post:
      operationId: group
      summary: Create objects and relationships
      description: 'Group calls add people to a group. Groups could be a companies, accounts, online classes, and so on. How groups are represented in your destination depends on the destination. Some destinations have concepts of "groups"; Customer.io''s destination calls groups "objects."


        **When you use our libraries, you''ll typically only provide an ID for the user, the `groupId`, and `traits`. The libraries fill in the rest of the payload automatically.**'
      servers:
      - url: https://cdp.customer.io/v1
        description: This is a Data Pipeline API.
      security:
      - Basic-Auth: []
      parameters:
      - name: X-Strict-Mode
        in: header
        description: 'When set to `1`, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200. [Learn more](/integrations/api/track-vs-cdp-api#pipelines-strict-mode)

          '
        required: false
        schema:
          type: string
          enum:
          - '1'
        example: '1'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/group'
      x-codeSamples:
      - lang: json
        label: JSON
        source: "{\n  \"anonymousId\": \"507f191e810c19729de860ea,\",\n  \"channel\": \"browser,\",\n  \"context\": {\n    \"ip\": \"8.8.8.8\",\n    \"userAgent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36\"\n  },\n  \"integrations\": {\n    \"All\": true,\n    \"Mixpanel\": false,\n    \"Salesforce\": false\n  },\n  \"messageId\": \"022bb90c-bbac-11e4-8dfc-aa07a5b093db,\",\n  \"receivedAt\": \"2015-02-23T22:28:55.387Z,\",\n  \"sentAt\": \"2015-02-23T22:28:55.111Z,\",\n  \"timestamp\": \"2015-02-23T22:28:55.111Z,\",\n  \"traits\": {\n    \"name\": \"ACME, Inc.\",\n    \"industry\": \"Technology\",\n    \"employees\": 329,\n    \"plan\": \"enterprise\",\n    \"total billed\": 830\n  },\n  \"type\": \"group\",\n  \"userId\": \"97980cfea0067\",\n  \"groupId\": \"0e8c78ea9d97a7b8185e8632,\",\n  \"version\": 1.1\n}"
      - label: Curl
        lang: shell
        source: "curl --request POST \\\n  --url https://cdp.customer.io/v1/group \\\n  -u api_key: \\\n  -H 'content-type: application/json' \\\n  --data-raw '\n  {\n      \"userId\": \"97980cfea0067\",\n      \"groupId\": \"0e8c78ea9d97a7b8185e8632\",\n      \"traits\": {\n          \"objectTypeId\": 2,\n          \"name\": \"ACME, Inc.\",\n          \"industry\": \"Technology\",\n          \"employees\": 329,\n          \"plan\": \"enterprise\",\n          \"total billed\": 830\n      }\n  }'\n"
      - label: JavaScript (SDK)
        lang: javascript
        source: "analytics.group(\"0e8c78ea9d97a7b8185e8632\", {\n  objectTypeId: 2,\n  name: \"Acme\",\n  industry: \"Technology\",\n  road_runner_accidents: 329,\n  plan: \"enterprise\",\n  \"total billed\": 830\n});\n"
      - label: Node.js (SDK)
        lang: javascript
        source: "analytics.group({\n  userId: '019mr8mf4r',\n  groupId: '56',\n  traits: {\n    objectTypeId: 2,\n    name: 'ACME, Inc.',\n    description: 'Giant anvils'\n  }\n});\n"
      - label: Python (SDK)
        lang: python
        source: "analytics.group('user_id', 'group_id', {\n  'objectTypeId': 2,\n  'name': 'ACME, Inc.',\n  'domain': 'Giant anvils'\n})\n"
      - label: Go (SDK)
        lang: go
        source: "client.Enqueue(analytics.Group{\n  UserId:  \"019mr8mf4r\",\n  GroupId: \"56\",\n  Traits: map[string]interface{}{\n    \"objectTypeId\": 2,\n    \"name\":        \"ACME, Inc.\",\n    \"description\": \"Giant anvils\",\n  },\n})\n"
      responses:
        '200':
          $ref: '#/components/responses/200'
      tags:
      - Group
components:
  schemas:
    context_page:
      x-scalar-ignore: true
      type: object
      description: Contains information about the current page in the browser. This is automatically collected by our JavaScript source.
      properties:
        name:
          type: string
          description: 'The name of the page. Reserved for future use.

            '
        path:
          type: string
          description: The path portion of the page's URL. Equivalent to the canonical `path` which defaults to `location.pathname` from the DOM API.
        referrer:
          type: string
          description: The previous page's full URL. Equivalent to `document.referrer` from the DOM API.
        search:
          type: string
          description: The query string portion of the page's URL. Equivalent to `location.search` from the DOM API.
        title:
          type: string
          description: The page's title. Equivalent to `document.title` from the DOM API.
        url:
          type: string
          description: A page's full URL. We first look for the canonical URL. If the canonical URL is not provided, we'll use `location.href` from the DOM API.
        keywords:
          type: array
          description: A list/array of keywords describing the page's content. The keywords are likely the same as, or similar to, the keywords you would find in an HTML `meta` tag for SEO purposes. This property is mainly used by content publishers that rely heavily on pageview tracking. This isn't automatically collected.
          items:
            type: string
    all_common_fields:
      x-scalar-ignore: true
      allOf:
      - $ref: '#/components/schemas/common_fields'
      - type: object
        properties:
          context:
            description: A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.
            oneOf:
            - $ref: '#/components/schemas/context_non_mobile'
            - $ref: '#/components/schemas/context_mobile'
    userId:
      x-scalar-ignore: true
      type: string
      description: The unique identifier for a person. This value should be unique across systems, so you recognize the same person in your sources _and_ destinations.
      example: 241ma8mf4a
    context_non_mobile:
      x-scalar-ignore: true
      description: A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.
      title: Non-mobile
      allOf:
      - $ref: '#/components/schemas/context_common'
      - type: object
        properties:
          campaign:
            type: object
            description: 'Contains information about the campaign that resulted in the API call, gathered from, or mapping to, UTM parameters (e.g. `utm_source`).

              '
            properties:
              name:
                type: string
                description: The campaign name.
              source:
                type: string
                description: The source of traffic—like the name of your email list, Facebook, Google, etc.
              medium:
                type: string
                description: The type of traffic a person/event originates from, like `email`, or `referral`.
              term:
                type: string
                description: The keyword term(s) a user came from.
              content:
                type: string
            additionalProperties:
              type: string
              x-additionalPropertiesName: Additional UTM Parameters
          page:
            $ref: '#/components/schemas/context_page'
    context_mobile:
      x-scalar-ignore: true
      description: A dictionary of context about a source call/event, like the user’s IP address or locale. Context is automatically collected by our source libraries.
      title: Mobile
      allOf:
      - $ref: '#/components/schemas/context_common'
      - type: object
        description: Fields included in events from mobile libraries.
        properties:
          app:
            type: object
            description: 'Contains information about the mobile app the event originated from, automatically collected by our mobile libraries when possible.

              '
            properties:
              name:
                type: string
                description: The name of the app.
              version:
                type: string
                description: The version of the app the call originated from.
              build:
                type: string
                description: The specific build number in the app.
              namespace:
                type: string
                description: The app's namespace.
          device:
            type: object
            description: 'Contains information about the device the event originated from.

              '
            properties:
              id:
                type: string
                description: The device ID.
              advertisingId:
                type: string
                description: The advertising ID is a unique, anonymous ID for advertising.
              manufacturer:
                type: string
                description: The device manufacturer.
              model:
                type: string
                description: The device model.
              name:
                type: string
                description: The device name.
              type:
                type: string
                description: The device type—android, iOS, etc.
                enum:
                - android
                - ios
              version:
                type: string
                description: The firmware version for the device.
          network:
            type: object
            description: Information about the current network connection, containing `bluetooth`, `carrier`, `cellular`, and `wifi`. If the `context.network.cellular` and `context.network.wifi` fields are empty, then the user is offline.
            properties:
              bluetooth:
                type: boolean
                description: Lets you know if bluetooth is enabled on a device.
              carrier:
                type: string
                description: The cellular carrier the phone uses.
              cellular:
                type: boolean
                description: Indicates whether the device's cellular connection is enabled or not.
              wifi:
                type: boolean
                description: Indicates whether a device's wifi connection is enabled or not.
          os:
            type: object
            description: 'Dictionary of information about the operating system, containing `name` and `version`.

              '
            properties:
              name:
                type: string
                description: The operating system running on the device.
              version:
                type: string
                description: The version of the OS running on the device.
    objectTypeId:
      x-scalar-ignore: true
      type: string
      description: If you use Customer.io Journeys as a destination, this value is the type of group/object your group belongs to; object type IDs are stringified integers. If you don't include this value, we assume the object type ID is `1`. See [objects in Customer.io Journeys](/journeys/objects-data/objects/types/) for more information.
      example: '1'
    context_common:
      x-scalar-ignore: true
      type: object
      description: Contains contextual information about the event.
      properties:
        active:
          type: boolean
          description: 'Whether a user is active.


            This is usually used when you send an .identify() call to update the traits independently of when you''ve “last seen” a user.

            '
        ip:
          type: string
          description: The user's IP address. This isn't captured by our libraries, but by our servers when we receive client-side events (like from our JavaScript source).
        locale:
          type: string
          description: The locale string for the current user, e.g. `en-US`.
        userAgent:
          type: string
          description: The user agent of the device making the request
        channel:
          type: string
          enum:
          - browser
          - server
          - mobile
          description: The channel the event originated from.
    integrations:
      x-scalar-ignore: true
      type: object
      description: 'Contains a list of booleans indicating the integrations that are enabled (true) or disabled (false). By default, all integrations are enabled (returning an empty object). Set `"All": false` to reverse this behavior.

        '
      additionalProperties:
        type: boolean
        x-additionalPropertiesName: Enabled/Disabled integrations
      example:
        All: true
        Salesforce: false
    group:
      x-scalar-ignore: true
      oneOf:
      - title: Known User
        allOf:
        - type: object
          properties:
            userId:
              $ref: '#/components/schemas/userId'
            type:
              type: string
              enum:
              - group
              description: The event type. This is set automatically by the request method/endpoint.
              example: group
            groupId:
              type: string
              description: ID of the group
              example: 0e8c78ea9d97a7b8185e8632
            traits:
              type: object
              description: Additional information about the group.
              properties:
                object_type_id:
                  $ref: '#/components/schemas/objectTypeId'
                relationshipAttributes:
                  type: object
                  description: Attributes that you want to set for the relationship between the person and the group.
                  example:
                    role: primary_contact
              additionalProperties:
                x-additionalPropertiesName: Group Traits
                example:
                  name: Acme
                  industry: Technology
                  road_runner_accidents: 329,
                  plan: enterprise,
                  total_billed: 830
        - $ref: '#/components/schemas/all_common_fields'
      - title: Anonymous User
        allOf:
        - type: object
          properties:
            anonymousId:
              $ref: '#/components/schemas/anonymousId'
            type:
              type: string
              enum:
              - group
              description: The event type. This is set automatically by the request method/endpoint.
              example: group
            groupId:
              type: string
              description: ID of the group
              example: 0e8c78ea9d97a7b8185e8632
            traits:
              type: object
              description: Additional information about the group.
              properties:
                object_type_id:
                  $ref: '#/components/schemas/objectTypeId'
                relationshipAttributes:
                  type: object
                  description: Attributes that you want to set for the relationship between the person and the group.
                  example:
                    role: primary_contact
              additionalProperties:
                x-additionalPropertiesName: Group Traits
                description: Attributes that you want to associate with the group.
                example:
                  name: Acme
                  industry: Technology
                  road_runner_accidents: 329,
                  plan: enterprise,
                  total_billed: 830
        - $ref: '#/components/schemas/all_common_fields'
      example:
        anonymousId: 507f191e810c19729de860ea,
        channel: browser,
        context:
          ip: 8.8.8.8
          userAgent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36
        integrations:
          All: true
          Mixpanel: false
          Salesforce: false
        messageId: 022bb90c-bbac-11e4-8dfc-aa07a5b093db,
        receivedAt: 2015-02-23T22:28:55.387Z,
        sentAt: 2015-02-23T22:28:55.111Z,
        timestamp: 2015-02-23T22:28:55.111Z,
        traits:
          name: ACME, Inc.
          industry: Technology
          employees: 329
          plan: enterprise
          total billed: 830
        type: group
        userId: 97980cfea0067
        groupId: 0e8c78ea9d97a7b8185e8632,
        version: 1.1
    anonymousId:
      x-scalar-ignore: true
      type: string
      description: A unique substitute for a User ID in cases when you don’t have an absolutely unique identifier. Our libraries generate this value automatically to help you track people before they sign up, log in, provide their email, etc.
      example: c0e5cae6-6f04-46e4-97a8-25076e8bdc0b
    common_fields:
      x-scalar-ignore: true
      type: object
      properties:
        integrations:
          $ref: '#/components/schemas/integrations'
        messageId:
          type: string
          description: A unique identifier for a Data Pipelines call, ensuring that each individual event is unique. This is set by Customer.io
        receivedAt:
          type: string
          format: date-time
          readOnly: true
          description: The ISO-8601 timestamp when Data Pipelines receives an event.
        sentAt:
          type: string
          format: date-time
          description: The ISO-8601 timestamp when a library sends an event to Data Pipelines.
        originalTimestamp:
          type: string
          format: date-time
          description: In general, you can use `timestamp` rather than this field if you want to back-date events. This is the timestamp on the client device you invoke a call or the timestamp value you manually passed in a server-side library call.
        timestamp:
          type: string
          format: date-time
          description: The ISO-8601 timestamp when the event originally took place. This is mostly useful when you backfill past events. If you're not backfilling data, you can leave this field empty and we'll use the current time or server time.
        type:
          readOnly: true
          type: string
          enum:
          - identify
          - group
          - track
          - page
          - screen
          - alias
          description: The type of source event. This is implicit and set by Customer.io based on the endpoint/method you use (e.g. `identify`).
        version:
          readOnly: true
          type: number
          description: The version of the API that received the event, automatically set by Customer.io.
  responses:
    '200':
      description: A successful request returns an empty object response.
  securitySchemes:
    Basic-Auth:
      type: http
      scheme: basic
      description: 'The Data Pipelines API uses a basic authentication scheme with your API key. Because basic authorization typically expects a username and password combination, you''ll use the API Key as the username and leave the password blank—base64 encoding your credentials in the format `API_key:`.

        '