Query and Manage Entities (APIs)
Query managed entities
Response to /api/v1/query
The total number of records in the dataset. The record count may return zero if there are no records in the dataset.
The number of the page within the complete dataset. This is indexed from 1.
The largest page number that yield an empty page. The page count may return zero if there are no records in the dataset.
The size of page that was requested (or defaulted). This is the maximum number of records that will be returned in the page.
default response to /api/v1/query
GET /api/v1/query HTTP/1.1
Host: api.example.com
Accept: */*
{
"record_count": 1,
"page_number": 1,
"page": [
{
"access_status": "text",
"bank_account": "text",
"country": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"reference": "text",
"role": "CUSTOMER",
"segment": "text",
"state": "VALID",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"continuation": "text",
"page_count": 1,
"page_size": 1
}Returns the number of all valid entities
Response to /api/v1/query/count
default response to /api/v1/query/count
GET /api/v1/query/count HTTP/1.1
Host: api.example.com
Accept: */*
{
"count_by_role": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"current_day_total": 1,
"total": 1
}Search entities
Response to /api/v1/query/search
The total number of records in the dataset. The record count may return zero if there are no records in the dataset.
The number of the page within the complete dataset. This is indexed from 1.
The largest page number that yield an empty page. The page count may return zero if there are no records in the dataset.
The size of page that was requested (or defaulted). This is the maximum number of records that will be returned in the page.
default response to /api/v1/query/search
GET /api/v1/query/search HTTP/1.1
Host: api.example.com
Accept: */*
{
"record_count": 1,
"page_number": 1,
"page": [
{
"access_status": "text",
"bank_account": "text",
"country": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"reference": "text",
"role": "CUSTOMER",
"segment": "text",
"state": "VALID",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"continuation": "text",
"page_count": 1,
"page_size": 1
}Get entity by reference
Response to /api/v1/search
The logical date-time at which the entity was created; this may significantly predate its initial persistence in the system in the case that the entity originates outside of the system.
A globally unique identifier for the managed entity, assigned by the software subsystem that manages it.
The date-time at which a change to the entity was last persisted. This is tracked for convenience only and should not generally form the basis for any system processing.
A reference supplied by the subsystem that requested its creation. The reference must at a minimum be unique over the declared role, but it is recommended that globally unique references are used where practical.
A strictly monotonically increasing number that is guaranteed to increase on any change to the entity.
The role of the entity in the system.
The state of the managed entity, see Managed Entity States
default response to /api/v1/search
GET /api/v1/search?references=text HTTP/1.1
Host: api.example.com
Accept: */*
[
{
"created": "2026-01-01T00:00:00.000Z",
"entity": {
"affiliation": "CUSTOMER",
"aspects": [
{
"aspect": {},
"identifier": "123e4567-e89b-12d3-a456-426614174000",
"relation": "text"
}
],
"reference": "text",
"type": "INDIVIDUAL"
},
"id": "123e4567-e89b-12d3-a456-426614174000",
"last_modified": "2026-01-01T00:00:00.000Z",
"reference": "text",
"revision": 1,
"role": "CUSTOMER",
"state": "VALID"
}
]Get entity relationships by reference
Response to /api/v1/{ref}/relationship/{relationshipRole}
The logical date-time at which the entity was created; this may significantly predate its initial persistence in the system in the case that the entity originates outside of the system.
A globally unique identifier for the managed entity, assigned by the software subsystem that manages it.
The date-time at which a change to the entity was last persisted. This is tracked for convenience only and should not generally form the basis for any system processing.
A reference supplied by the subsystem that requested its creation. The reference must at a minimum be unique over the declared role, but it is recommended that globally unique references are used where practical.
A strictly monotonically increasing number that is guaranteed to increase on any change to the entity.
The role of the entity in the system.
The state of the managed entity, see Managed Entity States
default response to /api/v1/{ref}/relationship/{relationshipRole}
GET /api/v1/{ref}/relationship/{relationshipRole} HTTP/1.1
Host: api.example.com
Accept: */*
[
{
"created": "2026-01-01T00:00:00.000Z",
"entity": {
"affiliation": "CUSTOMER",
"aspects": [
{
"aspect": {},
"identifier": "123e4567-e89b-12d3-a456-426614174000",
"relation": "text"
}
],
"reference": "text",
"type": "INDIVIDUAL"
},
"id": "123e4567-e89b-12d3-a456-426614174000",
"last_modified": "2026-01-01T00:00:00.000Z",
"reference": "text",
"revision": 1,
"role": "CUSTOMER",
"state": "VALID"
}
]Get entity by role and id
Response to /api/v1/{role}/id/{id}
The logical date-time at which the entity was created; this may significantly predate its initial persistence in the system in the case that the entity originates outside of the system.
A globally unique identifier for the managed entity, assigned by the software subsystem that manages it.
The date-time at which a change to the entity was last persisted. This is tracked for convenience only and should not generally form the basis for any system processing.
A reference supplied by the subsystem that requested its creation. The reference must at a minimum be unique over the declared role, but it is recommended that globally unique references are used where practical.
A strictly monotonically increasing number that is guaranteed to increase on any change to the entity.
The role of the entity in the system.
The state of the managed entity, see Managed Entity States
default response to /api/v1/{role}/id/{id}
GET /api/v1/{role}/id/{id} HTTP/1.1
Host: api.example.com
Accept: */*
{
"created": "2026-01-01T00:00:00.000Z",
"entity": {
"affiliation": "CUSTOMER",
"aspects": [
{
"aspect": {},
"identifier": "123e4567-e89b-12d3-a456-426614174000",
"relation": "text"
}
],
"reference": "text",
"type": "INDIVIDUAL"
},
"id": "123e4567-e89b-12d3-a456-426614174000",
"last_modified": "2026-01-01T00:00:00.000Z",
"reference": "text",
"revision": 1,
"role": "CUSTOMER",
"state": "VALID"
}Get entity by role and ref
Response to /api/v1/{role}/ref/{ref}
The logical date-time at which the entity was created; this may significantly predate its initial persistence in the system in the case that the entity originates outside of the system.
A globally unique identifier for the managed entity, assigned by the software subsystem that manages it.
The date-time at which a change to the entity was last persisted. This is tracked for convenience only and should not generally form the basis for any system processing.
A reference supplied by the subsystem that requested its creation. The reference must at a minimum be unique over the declared role, but it is recommended that globally unique references are used where practical.
A strictly monotonically increasing number that is guaranteed to increase on any change to the entity.
The role of the entity in the system.
The state of the managed entity, see Managed Entity States
default response to /api/v1/{role}/ref/{ref}
GET /api/v1/{role}/ref/{ref} HTTP/1.1
Host: api.example.com
Accept: */*
{
"created": "2026-01-01T00:00:00.000Z",
"entity": {
"affiliation": "CUSTOMER",
"aspects": [
{
"aspect": {},
"identifier": "123e4567-e89b-12d3-a456-426614174000",
"relation": "text"
}
],
"reference": "text",
"type": "INDIVIDUAL"
},
"id": "123e4567-e89b-12d3-a456-426614174000",
"last_modified": "2026-01-01T00:00:00.000Z",
"reference": "text",
"revision": 1,
"role": "CUSTOMER",
"state": "VALID"
}Get entity by role and idRef
Response to /api/v1/{role}/{idRef}
The logical date-time at which the entity was created; this may significantly predate its initial persistence in the system in the case that the entity originates outside of the system.
A globally unique identifier for the managed entity, assigned by the software subsystem that manages it.
The date-time at which a change to the entity was last persisted. This is tracked for convenience only and should not generally form the basis for any system processing.
A reference supplied by the subsystem that requested its creation. The reference must at a minimum be unique over the declared role, but it is recommended that globally unique references are used where practical.
A strictly monotonically increasing number that is guaranteed to increase on any change to the entity.
The role of the entity in the system.
The state of the managed entity, see Managed Entity States
default response to /api/v1/{role}/{idRef}
GET /api/v1/{role}/{idRef} HTTP/1.1
Host: api.example.com
Accept: */*
{
"created": "2026-01-01T00:00:00.000Z",
"entity": {
"affiliation": "CUSTOMER",
"aspects": [
{
"aspect": {},
"identifier": "123e4567-e89b-12d3-a456-426614174000",
"relation": "text"
}
],
"reference": "text",
"type": "INDIVIDUAL"
},
"id": "123e4567-e89b-12d3-a456-426614174000",
"last_modified": "2026-01-01T00:00:00.000Z",
"reference": "text",
"revision": 1,
"role": "CUSTOMER",
"state": "VALID"
}Last updated