> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/xyb-platform-1/api-reference/entities/query-and-manage-entities-apis.md).

# Query and Manage Entities (APIs)

## GET /api/v1/query

> Query managed entities

```json
{"openapi":"3.0.3","info":{"title":"Entity Service","version":"0.34.32-ac8849c"},"tags":[{"name":"EntityQueryController","description":"Endpoints for querying and searching managed entities."}],"servers":[{"url":"https://api.example.com","description":"Replace with your base URL"}],"paths":{"/api/v1/query":{"get":{"tags":["EntityQueryController"],"description":"Query managed entities","operationId":"EntityQueryController_queryManagedEntities","parameters":[{"name":"filter","in":"query","required":false,"schema":{"type":"string"}},{"name":"page[size]","in":"query","required":false,"schema":{"type":"string"}},{"name":"page[number]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/query","content":{"application/json":{"schema":{"type":"object","properties":{"record_count":{"type":"integer","description":"The total number of records in the dataset. The record count may return zero if there are no records in the dataset."},"page_number":{"type":"integer","description":"The number of the page within the complete dataset. This is indexed from 1."},"page":{"type":"array","items":{"$ref":"#/components/schemas/ManagedEntityLite"},"description":"A list of the records included in the page. The length of the list may be zero; it SHOULD NOT exceed the quoted page size."},"continuation":{"type":"string"},"page_count":{"type":"integer","description":"The largest page number that yield an empty page. The page count may return zero if there are no records in the dataset."},"page_size":{"type":"integer","description":"The size of page that was requested (or defaulted). This is the maximum number of records that will be returned in the page."}},"required":["page_number","page_size","page"]}}}},"default":{"description":"default response to /api/v1/query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"ManagedEntityLite":{"type":"object","properties":{"access_status":{"type":"string"},"bank_account":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string","format":"date-time","description":"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.\n"},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the managed entity, assigned by the software subsystem that manages it."},"name":{"type":"string","description":"Entity name"},"reference":{"type":"string","description":"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.\n"},"role":{"type":"string","enum":["CUSTOMER","CUSTOMER_BUSINESS","EMPLOYEE","APPLICATION","OWNER","PARTNER"],"description":"The role of the entity in the system."},"segment":{"type":"string"},"state":{"type":"string","enum":["VALID","INVALID","DESYNCED","DELETED"],"description":"The state of the managed entity, see Managed Entity States"},"updated_at":{"type":"string","format":"date-time","description":"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.\n"}},"required":["id","reference","role","state","created_at","updated_at","name"],"title":"ManagedEntityLite"},"ResponseCodeWrapper":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Response code metadata"},"comment":{"type":"string","description":"Response code comment"},"description":{"type":"string","description":"Response code description"},"response_code":{"type":"string","description":"Response code"}},"required":["response_code","description"],"title":"ResponseCodeWrapper"}}}}
```

## GET /api/v1/query/count

> Returns the number of all valid entities

```json
{"openapi":"3.0.3","info":{"title":"Entity Service","version":"0.34.32-ac8849c"},"tags":[{"name":"EntityQueryController","description":"Endpoints for querying and searching managed entities."}],"servers":[{"url":"https://api.example.com","description":"Replace with your base URL"}],"paths":{"/api/v1/query/count":{"get":{"tags":["EntityQueryController"],"description":"Returns the number of all valid entities","operationId":"EntityQueryController_countEntities","responses":{"200":{"description":"Response to /api/v1/query/count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityCount"}}}},"default":{"description":"default response to /api/v1/query/count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"EntityCount":{"type":"object","properties":{"count_by_role":{"type":"object","additionalProperties":{"type":"integer","format":"int32"}},"current_day_total":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int32"}},"required":["total","current_day_total","count_by_role"],"title":"EntityCount"},"ResponseCodeWrapper":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Response code metadata"},"comment":{"type":"string","description":"Response code comment"},"description":{"type":"string","description":"Response code description"},"response_code":{"type":"string","description":"Response code"}},"required":["response_code","description"],"title":"ResponseCodeWrapper"}}}}
```

## GET /api/v1/query/search

> Search entities

```json
{"openapi":"3.0.3","info":{"title":"Entity Service","version":"0.34.32-ac8849c"},"tags":[{"name":"EntityQueryController","description":"Endpoints for querying and searching managed entities."}],"servers":[{"url":"https://api.example.com","description":"Replace with your base URL"}],"paths":{"/api/v1/query/search":{"get":{"tags":["EntityQueryController"],"description":"Search entities","operationId":"EntityQueryController_searchEntities","parameters":[{"name":"filter","in":"query","required":false,"schema":{"type":"string"}},{"name":"page[size]","in":"query","required":false,"schema":{"type":"string"}},{"name":"page[number]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/query/search","content":{"application/json":{"schema":{"type":"object","properties":{"record_count":{"type":"integer","description":"The total number of records in the dataset. The record count may return zero if there are no records in the dataset."},"page_number":{"type":"integer","description":"The number of the page within the complete dataset. This is indexed from 1."},"page":{"type":"array","items":{"$ref":"#/components/schemas/ManagedEntityLite"},"description":"A list of the records included in the page. The length of the list may be zero; it SHOULD NOT exceed the quoted page size."},"continuation":{"type":"string"},"page_count":{"type":"integer","description":"The largest page number that yield an empty page. The page count may return zero if there are no records in the dataset."},"page_size":{"type":"integer","description":"The size of page that was requested (or defaulted). This is the maximum number of records that will be returned in the page."}},"required":["page_number","page_size","page"]}}}},"default":{"description":"default response to /api/v1/query/search","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"ManagedEntityLite":{"type":"object","properties":{"access_status":{"type":"string"},"bank_account":{"type":"string"},"country":{"type":"string"},"created_at":{"type":"string","format":"date-time","description":"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.\n"},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the managed entity, assigned by the software subsystem that manages it."},"name":{"type":"string","description":"Entity name"},"reference":{"type":"string","description":"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.\n"},"role":{"type":"string","enum":["CUSTOMER","CUSTOMER_BUSINESS","EMPLOYEE","APPLICATION","OWNER","PARTNER"],"description":"The role of the entity in the system."},"segment":{"type":"string"},"state":{"type":"string","enum":["VALID","INVALID","DESYNCED","DELETED"],"description":"The state of the managed entity, see Managed Entity States"},"updated_at":{"type":"string","format":"date-time","description":"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.\n"}},"required":["id","reference","role","state","created_at","updated_at","name"],"title":"ManagedEntityLite"},"ResponseCodeWrapper":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Response code metadata"},"comment":{"type":"string","description":"Response code comment"},"description":{"type":"string","description":"Response code description"},"response_code":{"type":"string","description":"Response code"}},"required":["response_code","description"],"title":"ResponseCodeWrapper"}}}}
```

## GET /api/v1/search

> Get entity by reference

```json
{"openapi":"3.0.3","info":{"title":"Entity Service","version":"0.34.32-ac8849c"},"tags":[{"name":"EntityController","description":"CRUD and relationship operations for entities."}],"servers":[{"url":"https://api.example.com","description":"Replace with your base URL"}],"paths":{"/api/v1/search":{"get":{"tags":["EntityController"],"description":"Get entity by reference","operationId":"EntityController_getAllByReferences","parameters":[{"name":"references","in":"query","required":true,"style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Response to /api/v1/search","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ManagedEntity"}}}}},"default":{"description":"default response to /api/v1/search","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"ManagedEntity":{"type":"object","properties":{"created":{"type":"string","format":"date-time","description":"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.\n"},"entity":{"$ref":"#/components/schemas/Entity","description":"The persisted entity. Note that this field is, in general, mutable.\n"},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the managed entity, assigned by the software subsystem that manages it."},"last_modified":{"type":"string","format":"date-time","description":"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.\n"},"reference":{"type":"string","description":"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.\n"},"revision":{"description":"A strictly monotonically increasing number that is guaranteed to increase on any change to the entity.","type":"integer","format":"int64"},"role":{"type":"string","enum":["CUSTOMER","CUSTOMER_BUSINESS","EMPLOYEE","APPLICATION","OWNER","PARTNER"],"description":"The role of the entity in the system."},"state":{"type":"string","enum":["VALID","INVALID","DESYNCED","DELETED"],"description":"The state of the managed entity, see Managed Entity States"}},"required":["id","reference","role","entity","state","created","last_modified"],"title":"ManagedEntity"},"Entity":{"type":"object","properties":{"affiliation":{"type":"string","enum":["CUSTOMER","INTERNAL","EXTERNAL"],"description":"Describes the relationship the entity has with XYB."},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/EntityAspect"},"description":"The list of aspects associated with the Entity"},"reference":{"type":"string","description":"Possibly a company number, a service identifier or an employee code"},"type":{"type":"string","enum":["INDIVIDUAL","ORGANIZATION","COLLECTIVE","VIRTUAL"],"description":"The type of the entity; determines how any entity reference is interpreted."}},"required":["type","affiliation"],"title":"Entity","description":"Something or someone who owns an account, or who interacts directly or indirectly with the system.\n"},"EntityAspect":{"type":"object","properties":{"aspect":{"$ref":"#/components/schemas/Aspect","description":"Concrete aspect"},"identifier":{"type":"string","format":"uuid","description":"A unique identifier for the aspect"},"relation":{"type":"string","description":"May be used to disambiguate aspects of the same type associated with the same entity"}},"required":["identifier","aspect"],"title":"EntityAspect"},"Aspect":{"type":"object","properties":{},"title":"Aspect"},"ResponseCodeWrapper":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Response code metadata"},"comment":{"type":"string","description":"Response code comment"},"description":{"type":"string","description":"Response code description"},"response_code":{"type":"string","description":"Response code"}},"required":["response_code","description"],"title":"ResponseCodeWrapper"}}}}
```

## GET /api/v1/{ref}/relationship/{relationshipRole}

> Get entity relationships by reference

```json
{"openapi":"3.0.3","info":{"title":"Entity Service","version":"0.34.32-ac8849c"},"tags":[{"name":"EntityController","description":"CRUD and relationship operations for entities."}],"servers":[{"url":"https://api.example.com","description":"Replace with your base URL"}],"paths":{"/api/v1/{ref}/relationship/{relationshipRole}":{"get":{"tags":["EntityController"],"description":"Get entity relationships by reference","operationId":"EntityController_getRelationshipsByRefNoRole","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}},{"name":"relationshipRole","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/{ref}/relationship/{relationshipRole}","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ManagedEntity"}}}}},"default":{"description":"default response to /api/v1/{ref}/relationship/{relationshipRole}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"ManagedEntity":{"type":"object","properties":{"created":{"type":"string","format":"date-time","description":"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.\n"},"entity":{"$ref":"#/components/schemas/Entity","description":"The persisted entity. Note that this field is, in general, mutable.\n"},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the managed entity, assigned by the software subsystem that manages it."},"last_modified":{"type":"string","format":"date-time","description":"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.\n"},"reference":{"type":"string","description":"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.\n"},"revision":{"description":"A strictly monotonically increasing number that is guaranteed to increase on any change to the entity.","type":"integer","format":"int64"},"role":{"type":"string","enum":["CUSTOMER","CUSTOMER_BUSINESS","EMPLOYEE","APPLICATION","OWNER","PARTNER"],"description":"The role of the entity in the system."},"state":{"type":"string","enum":["VALID","INVALID","DESYNCED","DELETED"],"description":"The state of the managed entity, see Managed Entity States"}},"required":["id","reference","role","entity","state","created","last_modified"],"title":"ManagedEntity"},"Entity":{"type":"object","properties":{"affiliation":{"type":"string","enum":["CUSTOMER","INTERNAL","EXTERNAL"],"description":"Describes the relationship the entity has with XYB."},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/EntityAspect"},"description":"The list of aspects associated with the Entity"},"reference":{"type":"string","description":"Possibly a company number, a service identifier or an employee code"},"type":{"type":"string","enum":["INDIVIDUAL","ORGANIZATION","COLLECTIVE","VIRTUAL"],"description":"The type of the entity; determines how any entity reference is interpreted."}},"required":["type","affiliation"],"title":"Entity","description":"Something or someone who owns an account, or who interacts directly or indirectly with the system.\n"},"EntityAspect":{"type":"object","properties":{"aspect":{"$ref":"#/components/schemas/Aspect","description":"Concrete aspect"},"identifier":{"type":"string","format":"uuid","description":"A unique identifier for the aspect"},"relation":{"type":"string","description":"May be used to disambiguate aspects of the same type associated with the same entity"}},"required":["identifier","aspect"],"title":"EntityAspect"},"Aspect":{"type":"object","properties":{},"title":"Aspect"},"ResponseCodeWrapper":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Response code metadata"},"comment":{"type":"string","description":"Response code comment"},"description":{"type":"string","description":"Response code description"},"response_code":{"type":"string","description":"Response code"}},"required":["response_code","description"],"title":"ResponseCodeWrapper"}}}}
```

## GET /api/v1/{role}/id/{id}

> Get entity by role and id

```json
{"openapi":"3.0.3","info":{"title":"Entity Service","version":"0.34.32-ac8849c"},"tags":[{"name":"EntityController","description":"CRUD and relationship operations for entities."}],"servers":[{"url":"https://api.example.com","description":"Replace with your base URL"}],"paths":{"/api/v1/{role}/id/{id}":{"get":{"tags":["EntityController"],"description":"Get entity by role and id","operationId":"EntityController_getById","parameters":[{"name":"role","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/{role}/id/{id}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedEntity"}}}},"default":{"description":"default response to /api/v1/{role}/id/{id}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"ManagedEntity":{"type":"object","properties":{"created":{"type":"string","format":"date-time","description":"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.\n"},"entity":{"$ref":"#/components/schemas/Entity","description":"The persisted entity. Note that this field is, in general, mutable.\n"},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the managed entity, assigned by the software subsystem that manages it."},"last_modified":{"type":"string","format":"date-time","description":"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.\n"},"reference":{"type":"string","description":"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.\n"},"revision":{"description":"A strictly monotonically increasing number that is guaranteed to increase on any change to the entity.","type":"integer","format":"int64"},"role":{"type":"string","enum":["CUSTOMER","CUSTOMER_BUSINESS","EMPLOYEE","APPLICATION","OWNER","PARTNER"],"description":"The role of the entity in the system."},"state":{"type":"string","enum":["VALID","INVALID","DESYNCED","DELETED"],"description":"The state of the managed entity, see Managed Entity States"}},"required":["id","reference","role","entity","state","created","last_modified"],"title":"ManagedEntity"},"Entity":{"type":"object","properties":{"affiliation":{"type":"string","enum":["CUSTOMER","INTERNAL","EXTERNAL"],"description":"Describes the relationship the entity has with XYB."},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/EntityAspect"},"description":"The list of aspects associated with the Entity"},"reference":{"type":"string","description":"Possibly a company number, a service identifier or an employee code"},"type":{"type":"string","enum":["INDIVIDUAL","ORGANIZATION","COLLECTIVE","VIRTUAL"],"description":"The type of the entity; determines how any entity reference is interpreted."}},"required":["type","affiliation"],"title":"Entity","description":"Something or someone who owns an account, or who interacts directly or indirectly with the system.\n"},"EntityAspect":{"type":"object","properties":{"aspect":{"$ref":"#/components/schemas/Aspect","description":"Concrete aspect"},"identifier":{"type":"string","format":"uuid","description":"A unique identifier for the aspect"},"relation":{"type":"string","description":"May be used to disambiguate aspects of the same type associated with the same entity"}},"required":["identifier","aspect"],"title":"EntityAspect"},"Aspect":{"type":"object","properties":{},"title":"Aspect"},"ResponseCodeWrapper":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Response code metadata"},"comment":{"type":"string","description":"Response code comment"},"description":{"type":"string","description":"Response code description"},"response_code":{"type":"string","description":"Response code"}},"required":["response_code","description"],"title":"ResponseCodeWrapper"}}}}
```

## GET /api/v1/{role}/ref/{ref}

> Get entity by role and ref

```json
{"openapi":"3.0.3","info":{"title":"Entity Service","version":"0.34.32-ac8849c"},"tags":[{"name":"EntityController","description":"CRUD and relationship operations for entities."}],"servers":[{"url":"https://api.example.com","description":"Replace with your base URL"}],"paths":{"/api/v1/{role}/ref/{ref}":{"get":{"tags":["EntityController"],"description":"Get entity by role and ref","operationId":"EntityController_getByRef","parameters":[{"name":"role","in":"path","required":true,"schema":{"type":"string"}},{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/{role}/ref/{ref}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedEntity"}}}},"default":{"description":"default response to /api/v1/{role}/ref/{ref}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"ManagedEntity":{"type":"object","properties":{"created":{"type":"string","format":"date-time","description":"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.\n"},"entity":{"$ref":"#/components/schemas/Entity","description":"The persisted entity. Note that this field is, in general, mutable.\n"},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the managed entity, assigned by the software subsystem that manages it."},"last_modified":{"type":"string","format":"date-time","description":"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.\n"},"reference":{"type":"string","description":"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.\n"},"revision":{"description":"A strictly monotonically increasing number that is guaranteed to increase on any change to the entity.","type":"integer","format":"int64"},"role":{"type":"string","enum":["CUSTOMER","CUSTOMER_BUSINESS","EMPLOYEE","APPLICATION","OWNER","PARTNER"],"description":"The role of the entity in the system."},"state":{"type":"string","enum":["VALID","INVALID","DESYNCED","DELETED"],"description":"The state of the managed entity, see Managed Entity States"}},"required":["id","reference","role","entity","state","created","last_modified"],"title":"ManagedEntity"},"Entity":{"type":"object","properties":{"affiliation":{"type":"string","enum":["CUSTOMER","INTERNAL","EXTERNAL"],"description":"Describes the relationship the entity has with XYB."},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/EntityAspect"},"description":"The list of aspects associated with the Entity"},"reference":{"type":"string","description":"Possibly a company number, a service identifier or an employee code"},"type":{"type":"string","enum":["INDIVIDUAL","ORGANIZATION","COLLECTIVE","VIRTUAL"],"description":"The type of the entity; determines how any entity reference is interpreted."}},"required":["type","affiliation"],"title":"Entity","description":"Something or someone who owns an account, or who interacts directly or indirectly with the system.\n"},"EntityAspect":{"type":"object","properties":{"aspect":{"$ref":"#/components/schemas/Aspect","description":"Concrete aspect"},"identifier":{"type":"string","format":"uuid","description":"A unique identifier for the aspect"},"relation":{"type":"string","description":"May be used to disambiguate aspects of the same type associated with the same entity"}},"required":["identifier","aspect"],"title":"EntityAspect"},"Aspect":{"type":"object","properties":{},"title":"Aspect"},"ResponseCodeWrapper":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Response code metadata"},"comment":{"type":"string","description":"Response code comment"},"description":{"type":"string","description":"Response code description"},"response_code":{"type":"string","description":"Response code"}},"required":["response_code","description"],"title":"ResponseCodeWrapper"}}}}
```

## GET /api/v1/{role}/{idRef}

> Get entity by role and idRef

```json
{"openapi":"3.0.3","info":{"title":"Entity Service","version":"0.34.32-ac8849c"},"tags":[{"name":"EntityController","description":"CRUD and relationship operations for entities."}],"servers":[{"url":"https://api.example.com","description":"Replace with your base URL"}],"paths":{"/api/v1/{role}/{idRef}":{"get":{"tags":["EntityController"],"description":"Get entity by role and idRef","operationId":"EntityController_getByIdRef","parameters":[{"name":"role","in":"path","required":true,"schema":{"type":"string"}},{"name":"idRef","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response to /api/v1/{role}/{idRef}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedEntity"}}}},"default":{"description":"default response to /api/v1/{role}/{idRef}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"ManagedEntity":{"type":"object","properties":{"created":{"type":"string","format":"date-time","description":"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.\n"},"entity":{"$ref":"#/components/schemas/Entity","description":"The persisted entity. Note that this field is, in general, mutable.\n"},"id":{"type":"string","format":"uuid","description":"A globally unique identifier for the managed entity, assigned by the software subsystem that manages it."},"last_modified":{"type":"string","format":"date-time","description":"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.\n"},"reference":{"type":"string","description":"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.\n"},"revision":{"description":"A strictly monotonically increasing number that is guaranteed to increase on any change to the entity.","type":"integer","format":"int64"},"role":{"type":"string","enum":["CUSTOMER","CUSTOMER_BUSINESS","EMPLOYEE","APPLICATION","OWNER","PARTNER"],"description":"The role of the entity in the system."},"state":{"type":"string","enum":["VALID","INVALID","DESYNCED","DELETED"],"description":"The state of the managed entity, see Managed Entity States"}},"required":["id","reference","role","entity","state","created","last_modified"],"title":"ManagedEntity"},"Entity":{"type":"object","properties":{"affiliation":{"type":"string","enum":["CUSTOMER","INTERNAL","EXTERNAL"],"description":"Describes the relationship the entity has with XYB."},"aspects":{"type":"array","items":{"$ref":"#/components/schemas/EntityAspect"},"description":"The list of aspects associated with the Entity"},"reference":{"type":"string","description":"Possibly a company number, a service identifier or an employee code"},"type":{"type":"string","enum":["INDIVIDUAL","ORGANIZATION","COLLECTIVE","VIRTUAL"],"description":"The type of the entity; determines how any entity reference is interpreted."}},"required":["type","affiliation"],"title":"Entity","description":"Something or someone who owns an account, or who interacts directly or indirectly with the system.\n"},"EntityAspect":{"type":"object","properties":{"aspect":{"$ref":"#/components/schemas/Aspect","description":"Concrete aspect"},"identifier":{"type":"string","format":"uuid","description":"A unique identifier for the aspect"},"relation":{"type":"string","description":"May be used to disambiguate aspects of the same type associated with the same entity"}},"required":["identifier","aspect"],"title":"EntityAspect"},"Aspect":{"type":"object","properties":{},"title":"Aspect"},"ResponseCodeWrapper":{"type":"object","properties":{"attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Response code metadata"},"comment":{"type":"string","description":"Response code comment"},"description":{"type":"string","description":"Response code description"},"response_code":{"type":"string","description":"Response code"}},"required":["response_code","description"],"title":"ResponseCodeWrapper"}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xyb.co/xyb-platform-1/api-reference/entities/query-and-manage-entities-apis.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.