> 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/create-and-update-entity-apis.md).

# Create and Update Entity APIs

## POST /api/v1/{role}

> Create entity

```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}":{"post":{"tags":["EntityController"],"description":"Create entity","operationId":"EntityController_create","parameters":[{"name":"role","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}},"responses":{"200":{"description":"Response to /api/v1/{role}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedEntity"}}}},"default":{"description":"default response to /api/v1/{role}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"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"},"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"},"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"}}}}
```

## PUT /api/v1/{role}

> Update entity

```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}":{"put":{"tags":["EntityController"],"description":"Update entity","operationId":"EntityController_update","parameters":[{"name":"role","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}},"responses":{"200":{"description":"Response to /api/v1/{role}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedEntity"}}}},"default":{"description":"default response to /api/v1/{role}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"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"},"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"},"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"}}}}
```

## PATCH /api/v1/{role}

> Patch entity

```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}":{"patch":{"tags":["EntityController"],"description":"Patch entity","operationId":"EntityController_patch","parameters":[{"name":"role","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}},"responses":{"200":{"description":"Response to /api/v1/{role}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedEntity"}}}},"default":{"description":"default response to /api/v1/{role}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"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"},"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"},"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"}}}}
```

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

> Delete 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/{role}/{idRef}":{"delete":{"tags":["EntityController"],"description":"Delete entity by reference","operationId":"EntityController_deleteByReference","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}"},"default":{"description":"default response to /api/v1/{role}/{idRef}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseCodeWrapper"}}}}}}}},"components":{"schemas":{"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/create-and-update-entity-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.