Create business object

POST 
/v2/illuminate/business-objects

Creates a new business object to capture and organize event data.

Business Objects are created with isActive: false by default, allowing you to configure fields before activation. At least one subscribe key in the subkeys array is required to activate a Business Object.

Key IDs to save from the response

The response includes auto-generated IDs you will need for downstream resources:

Response fieldUsed by
id (top-level)businessObjectId when creating metrics, decisions, or queries
fields[].idmeasureId and dimensionIds when creating metrics; inputFields[].sourceId when creating decisions

Note: Omit id on fields when creating — the API auto-generates them. You must include field id values in subsequent PUT requests for existing fields.

Field source conditional requirements

sourceRequired fieldsNotes
JSONPATHjsonPath, jsonFieldTypejsonPath is required when isActive is true.
DERIVEDderivation objectMust include operation: "TIME_DIFF" and params (startSource, endSource, etc.)

Field type limits

  • TEXT_LONG fields (up to 1,000 characters) are limited to 5 per Business Object. Use TEXT (default 256-char limit) unless you need longer values.
  • Maximum 100 fields per Business Object.

Request​

Example
{
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "createdBy": "string",
  "updatedBy": "string",
  "id": "string",
  "name": "string",
  "isActive": false,
  "description": "string",
  "fields": [
    {
      "id": "string",
      "name": "string",
      "jsonPath": "string",
      "jsonFieldType": "TEXT",
      "isKeyset": false,
      "source": "JSONPATH",
      "derivation": {
        "operation": "TIME_DIFF",
        "params": {}
      }
    }
  ],
  "accountId": "string",
  "subkeys": [
    "string"
  ],
  "metrics": [
    {
      "id": "string",
      "name": "string",
      "measureId": "string",
      "businessObjectId": "string",
      "evaluationWindow": 0,
      "function": "string",
      "dimensionIds": [
        "string"
      ],
      "dimensions": [
        {}
      ],
      "filters": [
        {}
      ]
    }
  ],
  "decisions": [
    {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "createdBy": "string",
      "updatedBy": "string",
      "id": "string",
      "name": "string",
      "description": "string",
      "accountId": "string",
      "businessObjectId": "string",
      "sourceType": "BUSINESSOBJECT",
      "sourceId": "string",
      "hitType": "SINGLE",
      "enabled": false,
      "activeFrom": "2024-01-01T00:00:00.000Z",
      "activeUntil": "2024-01-01T00:00:00.000Z",
      "executeOnce": false,
      "executionFrequency": 0,
      "inputFields": [
        {}
      ],
      "outputFields": [
        {}
      ],
      "rules": [
        {}
      ],
      "actions": [
        {}
      ],
      "metric": {
        "id": "string",
        "name": "string",
        "measureId": "string",
        "businessObjectId": "string",
        "evaluationWindow": 0,
        "function": "string",
        "dimensionIds": [],
        "dimensions": [],
        "filters": []
      },
      "query": {
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z",
        "createdBy": "string",
        "updatedBy": "string",
        "decisions": [],
        "customer": {},
        "businessObjects": [],
        "id": "string",
        "name": "string",
        "description": "string",
        "definition": {},
        "template": "string",
        "accountId": "string"
      },
      "customer": {
        "id": "string",
        "name": "string"
      }
    }
  ],
  "dashboards": [
    {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "createdBy": "string",
      "updatedBy": "string",
      "id": "string",
      "name": "string",
      "accountId": "string",
      "dateRange": "30 minutes",
      "startDate": "2024-01-01T00:00:00.000Z",
      "endDate": "2024-01-01T00:00:00.000Z",
      "charts": [
        {}
      ],
      "customer": {
        "id": "string",
        "name": "string"
      }
    }
  ],
  "queries": [
    {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "createdBy": "string",
      "updatedBy": "string",
      "decisions": [
        {}
      ],
      "customer": {
        "id": "string",
        "name": "string"
      },
      "businessObjects": [],
      "id": "string",
      "name": "string",
      "description": "string",
      "definition": {
        "version": "2.0",
        "pipeline": {},
        "meta": {}
      },
      "template": "string",
      "accountId": "string"
    }
  ],
  "customers": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}