Entity data

Abstract

Use this topic to find definitions for objects and fields used in the Grid API v2 /entity endpoints.

This topic contains definitions for objects and fields used in the Grid API v2 /entity endpoints.

EntitySearchRequest

The request body for a Grid entity search.

Field	Name	Type	Description
`criteria`	Search criteria	Array	A list of criteria, for example, entity name or system ID, that define how to search for entities. Contains `Criteria` data.
`includeReport`	Include report	Boolean	Indicates whether the search response should include the entity report. Default value: `false`.
`includedReportType`	Included report type	String	Specifies which type of report should be included when `includeReport` is set to `true`.
`targetFirmNumber`	Target firm number	String	Identifier for a Grid firm. This routes the request to the correct firm configuration.

Criteria

An entity search condition that specifies a specific attribute, for example, name, ID, address, or date of birth, to target in your entity lookup.

Field	Name	Type	Description
`entityId`	Entity ID	Integer	The Grid‑assigned entity ID. Used to retrieve a specific entity.
`sysId`	System ID	String	The system‑assigned identifier for the entity.
`name`	Name	String	The full or partial entity name to search for. Character limit: 128
`entityTyp`	Entity type	String	The type of entity represented by this record. This value reflects the entity’s classification in Grid. Possible values: `P` (Person), `O` (Organization), or `U` (Unknown)
`exactNameMatch`	Exact name match	Boolean	When set to `true`, the search must match the `name` value exactly. Default value: `false`.
`countryCode`	Country code	String	Two-letter country code associated with the address. Format: ISO 3166-1 alpha-2
`birthDt`	Birth date	Array	Birth date, typically in `YYYY‑MM‑DD` format. Multiple values may be provided. Example value: `1985‑01‑30`.
`yearRange`	Year range	Integer	A range, in years, to widen the birth date search window.
`eventCode`	Event code	Array	A list of risk event codes used to match risk types. See Grid risk event codes for more information.
`addresses`	Addresses	Array	A list of address records used to match entity locations. Contains `MultiAddress` data.
`address`	Address	String	A free‑form delivery address value used to match entity location. Character limit: 255
`city`	City	String	The city associated with the entity’s address. Character limit: 255
`state`	State	String	The state or province for the entity’s address. Character limit: 255
`zip`	Postal code	String	Postal or ZIP code for the entity's address. Character limit: 15

MultiAddress

A single, structured address in a list of multiple addresses used in entity search.

Field	Name	Type	Description
`addr1`	Address	String	A free‑form delivery address value used to match entity location. Character limit: 255
`city`	City	String	The city associated with the entity’s address. Character limit: 255
`stateProv`	State or province	String	The state or province for the entity’s address. Character limit: 255
`postalCode`	Postal code	String	Postal or ZIP code for the entity's address. Character limit: 15
`countryCode`	Country code	String	Two-letter country code associated with the address. Format: ISO 3166-1 alpha-2

ResponseEntity

The standard response wrapper for Grid entity search and retrieval operations.

Field	Name	Type	Description
`data`	Entity data	Object	Contains the entity returned by the search. Contains `Entity` data.
`status`	Response status	Object	Used to confirm successful processing or indicate errors or warnings. Contains `ResponseStatus` data.

Field

Name

Type

Description

data

Entity data

Object

Contains the entity returned by the search.

Contains Entity data.

status

Response status

Object

Used to confirm successful processing or indicate errors or warnings.

Contains ResponseStatus data.

ResponseListEntity

The standard response wrapper for Grid /entity search operations that return multiple entity results.

Field	Name	Type	Description
`data`	Entity list	Array	Contains a list of entities returned by the entity search. Each `Entity` object represents a single entity that matches your search criteria.
`status`	Response status	Object	Used to confirm successful processing or indicate errors or warnings. Contains `ResponseStatus` data.

Field

Name

Type

Description

data

Entity list

Array

Contains a list of entities returned by the entity search. Each Entity object represents a single entity that matches your search criteria.

status

Response status

Object

Used to confirm successful processing or indicate errors or warnings.

Contains ResponseStatus data.

Entity

A Grid entity record that contains core identifying information, attributes, related records, and metadata about the entity.

Field	Name	Type	Description
`addresses`	Addresses	Array	A list of address records for an entity. Contains `Address` data.
`alertConfidence`	Alert confidence	Number	A numeric indicator of the system’s confidence in the relevance of the matched entity to the inquiry.
`alertNote`	Alert note	String	Text note about an alert attached to the entity.
`aliases`	Aliases	Array	Alternate names for an entity. Contains `Alias` data.
`attributes`	Attributes	Array	Additional attributes associated with the entity. Contains `Attribute` data.
`bestMatch`	Best match	Boolean	Indicates whether this entity is the best match.
`birthDt`	Birth date	Array	Birth date, typically in `YYYY‑MM‑DD` format. Multiple values may be provided.
`cvip`	CVIP	String	CVIP classification for an entity.
`entityId`	Entity ID	Integer	The Grid‑assigned entity ID.
`entityName`	Entity name	String	Name of an entity.
`entityTyp`	Entity type	String	The type of entity represented by this record. This value reflects the entity’s classification in Grid. Possible values: `P` (person) or `O` (organization)
`events`	Events	Array	Events related to an entity. Contains `Event` data.
`fullPositions`	Full positions	Array	List of roles or positions tied to an entity. Contains `FullPositions` data.
`id`	ID	String	The entity’s unique identifier.
`identifications`	Identifications	Array	Identification documents or numbers related to the entity. Contains `Identification` data.
`matchScore`	Match score	Integer	Numeric score representing the entity match strength.
`pepTypes`	PEP types	Array	Politically exposed person (PEP) classifications for the entity. Contains `PepType` data.
`rdcURL`	RDC URL	String	URL pointing to the Grid record associated with an entity.
`relations`	Relationships	Array	Relationship data linking the entity to other individuals or organizations. Contains `Relation` data.
`report`	Report	String	Base64 or other encoded report content.
`riskScore`	Risk score	Integer	Numeric score representing the assessed risk level. Range: 0 ≤ value < 100
`source`	Source	Object	Metadata describing the information source for the entity. Contains `Source` data.
`sources`	Sources	Array	Source list for the entity. Contains `Source` data.
`status`	Status	String	Status of the entity record.
`sysId`	System ID	String	The system‑assigned identifier for the entity.
`targetFirmNumber`	Target firm number	String	Firm number associated with the record.

Source

The publication or data source from which an entity’s profile information was derived.

Field	Name	Type	Description
`entityDt`	Entity date	String	The event or entity date associated with this source. Example format: `YYYY‑MM‑DD`
`format`	Format	String	The content format, for example, text, document, media.
`headline`	Headline	String	The headline or title associated with the source content.
`publicationSource`	Publication source	String	The originating publication or media outlet.
`publisher`	Publisher	String	The entity that published the source information.
`sourceKy`	Source key	String	A unique key or identifier assigned to this source.
`sourceName`	Source name	String	The name of the information source.
`sourceURL`	Source URL	String	The URL where the source content originates.

Event

A single event associated with an entity, for example, sanctions, adverse media, or other profile‑relevant occurrences.

Field	Name	Type	Description
`category`	Category	Object	Identifies an event’s main category, for example, sanction, enforcement action, or adverse media. Contains `Category` data.
`eventDesc`	Event description	String	Text describing an event.
`eventDt`	Event date	String	The date of an event in `YYYY‑MM‑DD` format.
`subCategory`	Sub‑category	Object	Additional classification that further qualifies an event type. Contains `Category` data.
`source`	Source	Object	Information about the source reporting an event. Contains `Source` data.

Field	Name	Type	Description
`categoryCode`	`Category code`	String	A code representing the event category. See Grid risk event codes for more information.
`categoryDesc`	`Category description`	String	A human‑readable, descriptive explanation for the event category code.

Address

A complete address associated with an entity, including an optional date range.

Field	Name	Type	Description
`addr1`	Address	String	First line of the address.
`addr2`	Address continued	String	The second line of the address.
`city`	City	String	City name.
`stateProv`	State or province	String	State or province name.
`postalCode`	Postal code	String	Postal or ZIP code.
`countryCode`	Country code	String	Two-letter country code associated with the address.
`fromDt`	From date	String	The date when this address became effective. Example format: `YYYY‑MM‑DD`
`toDt`	To date	String	The date when this address became no longer effective. Example format: `YYYY‑MM‑DD`

Attribute

An attribute associated with an entity or alert record

Field	Name	Type	Description
`code`	Attribute code	String	Code that identifies the kind of attribute. See Grid risk attribute codes for more information.Grid risk attribute codes
`value`	Attribute value	String	The value associated with the attribute code. For example, an ID number, deceased date, or source link.

Field

Name

Type

Description

code

Attribute code

String

Code that identifies the kind of attribute.

See Grid risk attribute codes for more information.Grid risk attribute codes

value

Attribute value

String

The value associated with the attribute code. For example, an ID number, deceased date, or source link.

Alias

An alternate name associated with an entity. Aliases may contribute to match scoring or alert context.

Field	Name	Type	Description
`type`	Alias type	String	Type/category of alias name, for example, alternate spellings or alternate language forms.
`name`	Alias name	String	The alternate name itself.
`bestMatch`	Best match flag	Boolean	Indicates whether this alias represents the best or most relevant alias match. Default value: `false`

Field

Name

Type

Description

type

Alias type

String

Type/category of alias name, for example, alternate spellings or alternate language forms.

name

Alias name

String

The alternate name itself.

bestMatch

Best match flag

Boolean

Indicates whether this alias represents the best or most relevant alias match.

Default value: false

FullPositions

A single position or role held by an entity. Each item in the fullPositions array contains the following fields.

Field	Name	Type	Description
`fromDate`	Start date	String	The date when the position began. Example format: `YYYY-MM-DD`.
`position`	Position name	String	The title or name of the position.
`toDate`	End date	String	The date when the position ended. If omitted, the position may still be active. Example format: `YYYY‑MM‑DD`.

Field

Name

Type

Description

fromDate

Start date

String

The date when the position began.

Example format: YYYY-MM-DD.

position

Position name

String

The title or name of the position.

toDate

End date

String

The date when the position ended. If omitted, the position may still be active.

Example format: YYYY‑MM‑DD.

PepType

PEP classifications associated with an entity.

Field	Name	Type	Description
`type`	PEP type	String	The category of PEP role assigned to the entity.
`level`	PEP level	Integer	The hierarchical level associated with the PEP role.
`position`	Position title	String	The title or position linked to the PEP designation.
`fromDate`	Role start date	String	The date when the entity began holding the PEP role. Example format: `YYYY‑MM‑DD`.
`toDate`	Role end date	String	The date when the entity stopped holding the PEP role. Example format: `YYYY‑MM‑DD`.

Relation

Defines a relationship between the current entity and another related entity.

Field	Name	Type	Description
`relDir`	Relationship direction	String	Indicates the direction of the relationship relative to the primary entity, for example, whether the related entity is upstream, downstream, or otherwise directionally linked.
`relTyp`	Relationship type	String	The category or class of the relationship. Indicates how the entities are connected.
`sysId`	Related entity system ID	String	A system‑assigned identifier used to associate the related entity with additional details.
`entityName`	Related entity name	String	A human‑readable name for the related entity referenced by `sysId`.

Identification

A single identification record associated with an entity.

Field	Name	Type	Description
`idNumber`	Identification number	String	The identification number value. This field is required
`idType`	Identification type	String	The identification type, for example, passport, national ID.
`location`	Issuing location	String	The location where the identification was issued.
`country`	Issuing country	String	The country that issued the identification.

ResponseStatus

The status block returned in responses.

Field	Name	Type	Description
`code`	Status code	Integer	Numeric code representing the response status.
`type`	Status type	String	Type of status. Possible values: `ERROR`, `WARNING`, `INFO`.
`description`	Status description	String	Human-readable description of the response status.
`additionalResponseStatuses`	Additional response statuses	Array	Additional status details. Contains `AdditionalResponseStatus` data.

AdditionalResponseStatus

Supplemental status details, for example, multiple warnings, informational messages, or secondary error conditions.

Field	Name	Type	Description
`type`	Type	String	Type of additional status. Possible values: `ERROR`, `WARNING`, `INFO`.
`description`	Description	String	Description of the additional status.
`code`	Code	Integer	Numeric code for the additional status.

Field

Name

Type

Description

type

Type

String

Type of additional status.

Possible values: ERROR, WARNING, INFO.

description

Description

String

Description of the additional status.

code

Code

Integer

Numeric code for the additional status.

Additional information

In this section:

Entity data

EntitySearchRequest

Criteria

MultiAddress

ResponseEntity

ResponseListEntity

Entity

Source

Event

Category

Address

Attribute

Alias

FullPositions

PepType

Relation

Identification

ResponseStatus

AdditionalResponseStatus

Additional information

Search results