# 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: 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:

```
GET https://docs.ag5.com/ag5-api/version-4-beta/ag5-skills-management-api/custom-fields.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.