{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/customer-io/main/json-schema/customer-io-group-schema.json",
  "title": "group",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/customer-io-group-api-openapi.yml#/components/schemas/group",
  "x-scalar-ignore": true,
  "oneOf": [
    {
      "title": "Known User",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "userId": {
              "$ref": "#/$defs/userId"
            },
            "type": {
              "type": "string",
              "enum": [
                "group"
              ],
              "description": "The event type. This is set automatically by the request method/endpoint."
            },
            "groupId": {
              "type": "string",
              "description": "ID of the group"
            },
            "traits": {
              "type": "object",
              "description": "Additional information about the group.",
              "properties": {
                "object_type_id": {
                  "$ref": "#/$defs/objectTypeId"
                },
                "relationshipAttributes": {
                  "type": "object",
                  "description": "Attributes that you want to set for the relationship between the person and the group."
                }
              },
              "additionalProperties": {
                "x-additionalPropertiesName": "Group Traits"
              }
            }
          }
        },
        {
          "$ref": "#/$defs/all_common_fields"
        }
      ]
    },
    {
      "title": "Anonymous User",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "anonymousId": {
              "$ref": "#/$defs/anonymousId"
            },
            "type": {
              "type": "string",
              "enum": [
                "group"
              ],
              "description": "The event type. This is set automatically by the request method/endpoint."
            },
            "groupId": {
              "type": "string",
              "description": "ID of the group"
            },
            "traits": {
              "type": "object",
              "description": "Additional information about the group.",
              "properties": {
                "object_type_id": {
                  "$ref": "#/$defs/objectTypeId"
                },
                "relationshipAttributes": {
                  "type": "object",
                  "description": "Attributes that you want to set for the relationship between the person and the group."
                }
              },
              "additionalProperties": {
                "x-additionalPropertiesName": "Group Traits",
                "description": "Attributes that you want to associate with the group."
              }
            }
          }
        },
        {
          "$ref": "#/$defs/all_common_fields"
        }
      ]
    }
  ],
  "$defs": {
    "all_common_fields": {
      "x-scalar-ignore": true,
      "allOf": [
        {
          "$ref": "#/$defs/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": "#/$defs/context_non_mobile"
                },
                {
                  "$ref": "#/$defs/context_mobile"
                }
              ]
            }
          }
        }
      ]
    },
    "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."
    },
    "common_fields": {
      "x-scalar-ignore": true,
      "type": "object",
      "properties": {
        "integrations": {
          "$ref": "#/$defs/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."
        }
      }
    },
    "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.\n\nThis is usually used when you send an .identify() call to update the traits independently of when you've “last seen” a user.\n"
        },
        "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."
        }
      }
    },
    "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": "#/$defs/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.\n",
              "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.\n",
              "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`.\n",
              "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."
                }
              }
            }
          }
        }
      ]
    },
    "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": "#/$defs/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`).\n",
              "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": "#/$defs/context_page"
            }
          }
        }
      ]
    },
    "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.\n"
        },
        "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"
          }
        }
      }
    },
    "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.\n",
      "additionalProperties": {
        "type": "boolean",
        "x-additionalPropertiesName": "Enabled/Disabled integrations"
      }
    },
    "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."
    },
    "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."
    }
  }
}