ImportEntities APIs request and response mapping

Supported in:

Google secops SIEM

This guide details the request and response mapping specifications and property parity analysis for migrating from the legacy Ingestion API (CreateEntities) to the modern Chronicle API (ImportEntities).

[!IMPORTANT] The modern ImportEntities API does not accept legacy Ingestion API keys or partner tokens. Callers must authenticate using standard Google Cloud IAM credentials authorized for the target instance resource.

Protocol and mapping overview

Feature	Legacy API (`CreateEntities`)	Modern Chronicle API (`ImportEntities`)
HTTP method	`POST`	`POST`
Permissions	Ingestion API key or legacy partner tokens	`chronicle.googleapis.com/entities.import`

Request payload field-by-field parity

In the legacy API, callers sent entity data using CreateEntitiesRequest, placing log_type and entities directly at the top level of the request body. In the modern Chronicle API, entities are ingested through ImportEntitiesRequest, which scopes the request to the parent instance in the URL path and wraps the entity payload inside an inline_source structure.

Legacy field (`CreateEntitiesRequest`)	Modern field (`ImportEntitiesRequest`)	Field type	Parity and migration notes
—	`parent` (in HTTP path)	`string`	Google Cloud scoping hierarchy: In the legacy API, the target customer was determined by the authentication token or API key. In the modern API, the parent instance is explicitly specified in the request URL: `projects/{project}/locations/{location}/instances/{instance}`.
—	`inline_source`	`EntitiesInlineSource` (oneof `source`)	Encapsulation wrapper: The modern API uses a `oneof source` container to represent the ingestion source. Inlined entities are provided within `inline_source`.
`log_type`	`inline_source.log_type`	`string`	Parity mapped: The log type identifying the source of the entity telemetry (for example, `OKTA`, `AZURE_AD`, or `ACTIVE_DIRECTORY`). In the modern API, this references a valid `chronicle.googleapis.com/LogType` resource.
`entities`	`inline_source.entities`	`repeated Entity`	Parity mapped with canonical resource naming: Repeated list of entities to be ingested. The entity schema preserves full compatibility with the UDM Entity model (`metadata`, `entity` noun, `relations`, `additional`, `risk_score`, `metric`) while adding an optional canonical resource `name` attribute in the modern schema.

Entity structure parity (`backstory.Entity` versus `google.cloud.chronicle.v1main.Entity`)

The schema of each entity in inline_source.entities retains complete structural alignment with the legacy UDM entity format:

Entity field	Field type	Parity and migration notes
`name`	`string`	New field: Canonical resource name of the entity (`projects/{project}/locations/{location}/instances/{instance}/entities/{entity}`).
`metadata`	`EntityMetadata`	Direct mapping: Contains entity metadata including `product_entity_id`, `collected_timestamp`, `creation_timestamp`, `interval`, `vendor_name`, `product_name`, `product_version`, `entity_type`, `feed`, and threat/IOC intelligence metadata.
`entity`	`Noun`	Direct mapping: The primary UDM Noun representing the entity (such as `user`, `asset`, `resource`, `file`, `process`, `domain_name`, `url`, or `ip_address`).
`relations`	`repeated Relation`	Direct mapping: Defines directed or bidirectional relationships between this entity and related entities (for example, `OWNS`, `ADMINISTERS`, `MEMBER`, `EXECUTES`, `DOWNLOADED_FROM`, or `CONTACTS`).
`additional`	`google.protobuf.Struct`	Direct mapping: Dynamic structured JSON object for supplemental attributes that cannot be accommodated within standard UDM fields.
`risk_score`	`EntityRisk`	Direct mapping: Contextual risk scoring details associated with the entity.
`metric`	`Metric`	Direct mapping: Numerical and statistical metrics associated with the entity when `entity_type` is `METRIC`.

Response payload field-by-field parity

Both endpoints return an empty confirmation payload upon successful receipt of the entities.

Legacy field (`google.protobuf.Empty`)	Modern field (`ImportEntitiesResponse`)	Field type	Parity and migration notes
—	—	`message`	Equivalent: Both APIs return an empty JSON object (`{}`) upon successful validation and queuing of the entity batch.

Key differences

Resource-scoped URL vs. global endpoint:
- Legacy CreateEntities sent requests to a global endpoint (/v1/entities), resolving the customer tenant implicitly from the ingestion token or API key.
- Modern ImportEntities adopts Google Cloud resource hierarchy standards, requiring explicit project, location, and instance identifiers in the URL path (/v1/projects/{project}/locations/{location}/instances/{instance}/entities:import).
Payload encapsulation (oneof source):
- Legacy CreateEntitiesRequest accepted log_type and entities directly at the root level of the payload.
- Modern ImportEntitiesRequest wraps the entity batch in an inline_source structure (EntitiesInlineSource), standardizing the import contract across direct inline uploads and future asynchronous source ingestion.
Modern IAM authorization:
- Authentication transitions from legacy API keys and partner tokens to standard Google Cloud IAM bearer tokens with granular permission enforcement (chronicle.googleapis.com/entities.import).
All-or-nothing batch validation:
- Both legacy and modern APIs enforce atomic validation across the entire batch: all entities in the request must be valid for the call to succeed. A validation error in any single entity causes the entire import request to fail.
Schema continuity:
- The internal schema of Entity remains fully consistent with the Universal Data Model (UDM) Entity definition, ensuring existing entity construction pipelines can migrate to the modern API with minimal transformation beyond payload wrapping.