> For the complete documentation index, see [llms.txt](https://docs.ag5.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ag5.com/ag5-api/version-4-beta/ag5-skills-management-api/custom-fields.md).

# Custom fields

Several entities in the API support custom fields. Entities supporting this feature allow a user to define custom fields on these entities and provide their own values. This allows a customer to set additional values to, for example, correlate entities with their source system or enrich the attributes of an entity. You could think of adding a custom field like `hr-system-id` or `department` on an Employee or a custom field `in-house-course-available` on the entity Skill.

A custom field can be defined using the POST createCustomFieldDefinitions call. The following example defines the custom field `hr-system-id` for the Employee entity. The entity type is referred to using the `entityDefinitionID`. To get a full list of available entity definition IDs you can use the GET /entityDefinitions call.

```json
POST /api/orgkeep/acme/orgkeep/v4/createCustomFieldDefinitions
Content-Type: application/json

{
  "code": "hr-system-id",
  "entityDefinitionID": "1ac17b5c-13be-c79e-3cd0-d7389fe58455",
  "isUnique": true,
  "name": { "en": "HR System ID" },
  "repositoryID": "12345678-2fe4-472f-af41-0c1b936247fa"
}
```

Note that we set the `isUnique` property to `true`. This allows us to retrieve a specific entity through the API using that custom field (see below).

#### Retrieving entities by custom field

A specific entity can be retrieved through the API by its own unique AG5 defined ID. For example, to fetch an employee with id `100` you could make an API call using the GET employee call like so:

```
GET /api/orgkeep/acme/orgkeep/v4/employees/100
```

However, the IDs internally used by AG5 won't correspond with, for example, the IDs of the customer's HR system. When making an integration between AG5 and an external system you may want to track the ID of an entity in the source system in AG5. AG5 allows a customer to create custom fields to accommodate this scenario.

To look up an entity by a custom field, the custom field definition must have the `isUnique` property set to `true`. Attempting to look up by a non-unique custom field will result in an Invalid Request response.

Suppose the Employee entity has the custom field `hr-system-id` defined. Now an employee can be retrieved through its hr-system-id using the following API call using the `{customfield}:{value}` format for the ID:

```
GET /api/orgkeep/acme/orgkeep/v4/employees/hr-system-id:C48D038DD
```


---

# 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.ag5.com/ag5-api/version-4-beta/ag5-skills-management-api/custom-fields.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.