> For the complete documentation index, see [llms.txt](https://developers.trooply.co.uk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.trooply.co.uk/field-definitions.md).

# Field Definitions

## List platform-wide field definitions

> Returns all platform-scoped field definitions available for any group or section.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"FieldDef":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"field_type":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_required":{"type":"boolean"},"label":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"integer"}},"scope":{"type":"string"},"section_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}}}},"paths":{"/v1/field-definitions":{"get":{"description":"Returns all platform-scoped field definitions available for any group or section.","tags":["field-definitions"],"summary":"List platform-wide field definitions","responses":{"200":{"description":"Platform field definitions","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FieldDef"}}}}]}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## List field categories for a group

> Returns platform and group-scoped field categories, platform first.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"Category":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"scope":{"type":"string"},"sort_order":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}}}},"paths":{"/v1/groups/{group_id}/field-categories":{"get":{"description":"Returns platform and group-scoped field categories, platform first.","tags":["field-definitions"],"summary":"List field categories for a group","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Group ID","name":"group_id","in":"path","required":true}],"responses":{"200":{"description":"Field categories","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}}]}}}},"400":{"description":"group_id is not a valid UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a field category for a group

> Adds a new group-scoped field category.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"Category":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"scope":{"type":"string"},"sort_order":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}},"CreateCategoryRequest":{"type":"object","required":["name"],"properties":{"description":{"type":"string"},"name":{"type":"string","maxLength":100,"minLength":1},"sort_order":{"type":"integer"}}}}},"paths":{"/v1/groups/{group_id}/field-categories":{"post":{"description":"Adds a new group-scoped field category.","tags":["field-definitions"],"summary":"Create a field category for a group","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Group ID","name":"group_id","in":"path","required":true}],"responses":{"201":{"description":"The created category","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Category"}}}]}}}},"400":{"description":"group_id is not a valid UUID or malformed JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCategoryRequest"}}},"description":"Category to create","required":true}}}}}
```

## Delete a group-scoped field category

> Removes a field category. Field definitions in this category become uncategorised.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}}}},"paths":{"/v1/groups/{group_id}/field-categories/{cat_id}":{"delete":{"description":"Removes a field category. Field definitions in this category become uncategorised.","tags":["field-definitions"],"summary":"Delete a group-scoped field category","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Group ID","name":"group_id","in":"path","required":true},{"schema":{"type":"string","format":"uuid"},"description":"Category ID","name":"cat_id","in":"path","required":true}],"responses":{"204":{"description":"Category deleted"},"400":{"description":"A path parameter is not a valid UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Insufficient permissions or platform-scoped category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update a group-scoped field category

> Applies a partial update to a field category.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"Category":{"type":"object","properties":{"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"scope":{"type":"string"},"sort_order":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}},"UpdateCategoryRequest":{"type":"object","properties":{"description":{"type":"string"},"name":{"type":"string","maxLength":100,"minLength":1},"sort_order":{"type":"integer"}}}}},"paths":{"/v1/groups/{group_id}/field-categories/{cat_id}":{"patch":{"description":"Applies a partial update to a field category.","tags":["field-definitions"],"summary":"Update a group-scoped field category","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Group ID","name":"group_id","in":"path","required":true},{"schema":{"type":"string","format":"uuid"},"description":"Category ID","name":"cat_id","in":"path","required":true}],"responses":{"200":{"description":"The updated category","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Category"}}}]}}}},"400":{"description":"A path parameter is not a valid UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Insufficient permissions or platform-scoped category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCategoryRequest"}}},"description":"Fields to update","required":true}}}}}
```

## List field definitions for a group

> Returns all group-scoped field definitions belonging to the given group.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"FieldDef":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"field_type":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_required":{"type":"boolean"},"label":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"integer"}},"scope":{"type":"string"},"section_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}}}},"paths":{"/v1/groups/{group_id}/field-definitions":{"get":{"description":"Returns all group-scoped field definitions belonging to the given group.","tags":["field-definitions"],"summary":"List field definitions for a group","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Group ID","name":"group_id","in":"path","required":true}],"responses":{"200":{"description":"Group field definitions","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FieldDef"}}}}]}}}},"400":{"description":"group_id is not a valid UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a group-scoped field definition

> Adds a new field definition scoped to the given group.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"FieldDef":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"field_type":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_required":{"type":"boolean"},"label":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"integer"}},"scope":{"type":"string"},"section_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}},"CreateFieldDefRequest":{"type":"object","required":["field_type","label","name"],"properties":{"description":{"type":"string"},"field_type":{"type":"string"},"is_required":{"type":"boolean"},"label":{"type":"string","maxLength":200,"minLength":1},"name":{"type":"string","maxLength":100,"minLength":1},"options":{"type":"array","items":{"type":"integer"}},"sort_order":{"type":"integer"}}}}},"paths":{"/v1/groups/{group_id}/field-definitions":{"post":{"description":"Adds a new field definition scoped to the given group.","tags":["field-definitions"],"summary":"Create a group-scoped field definition","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Group ID","name":"group_id","in":"path","required":true}],"responses":{"201":{"description":"The created field definition","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FieldDef"}}}]}}}},"400":{"description":"group_id is not a valid UUID or malformed JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFieldDefRequest"}}},"description":"Field definition to create","required":true}}}}}
```

## Delete a group-scoped field definition

> Removes a field definition from the group. Soft-deletes if values exist; hard-deletes otherwise.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}}}},"paths":{"/v1/groups/{group_id}/field-definitions/{field_def_id}":{"delete":{"description":"Removes a field definition from the group. Soft-deletes if values exist; hard-deletes otherwise.","tags":["field-definitions"],"summary":"Delete a group-scoped field definition","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Group ID","name":"group_id","in":"path","required":true},{"schema":{"type":"string","format":"uuid"},"description":"Field Definition ID","name":"field_def_id","in":"path","required":true}],"responses":{"204":{"description":"Field definition deleted"},"400":{"description":"A path parameter is not a valid UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Field definition not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update a group-scoped field definition

> Applies a partial update to a field definition in the given group.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"FieldDef":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"field_type":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_required":{"type":"boolean"},"label":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"integer"}},"scope":{"type":"string"},"section_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}},"UpdateFieldDefRequest":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"description":{"type":"string"},"is_active":{"type":"boolean"},"is_required":{"type":"boolean"},"label":{"type":"string","maxLength":200,"minLength":1},"options":{"type":"array","items":{"type":"integer"}},"sort_order":{"type":"integer"}}}}},"paths":{"/v1/groups/{group_id}/field-definitions/{field_def_id}":{"patch":{"description":"Applies a partial update to a field definition in the given group.","tags":["field-definitions"],"summary":"Update a group-scoped field definition","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Group ID","name":"group_id","in":"path","required":true},{"schema":{"type":"string","format":"uuid"},"description":"Field Definition ID","name":"field_def_id","in":"path","required":true}],"responses":{"200":{"description":"The updated field definition","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FieldDef"}}}]}}}},"400":{"description":"A path parameter is not a valid UUID or malformed JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Field definition not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFieldDefRequest"}}},"description":"Fields to update","required":true}}}}}
```

## Get field values for a member in a group

> Returns all field values for the given member within the specified group.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"FieldValue":{"type":"object","properties":{"field_def_id":{"type":"string","format":"uuid"},"field_name":{"type":"string"},"field_type":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"member_id":{"type":"string","format":"uuid"},"options":{"type":"array","items":{"type":"integer"}},"value":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}}}},"paths":{"/v1/groups/{group_id}/members/{member_id}/field-values":{"get":{"description":"Returns all field values for the given member within the specified group.","tags":["field-definitions"],"summary":"Get field values for a member in a group","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Group ID","name":"group_id","in":"path","required":true},{"schema":{"type":"string","format":"uuid"},"description":"Member ID","name":"member_id","in":"path","required":true}],"responses":{"200":{"description":"Field values","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FieldValue"}}}}]}}}},"400":{"description":"A path parameter is not a valid UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Set field values for a member (batch)

> Batch-upserts field values for a member. A null value clears the field. All field\_def\_ids must be visible to the given group.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}},"SetFieldValuesRequest":{"type":"object","required":["group_id","values"],"properties":{"group_id":{"type":"string","format":"uuid"},"values":{"type":"object","additionalProperties":{"type":"string"}}}}}},"paths":{"/v1/groups/{group_id}/members/{member_id}/field-values":{"patch":{"description":"Batch-upserts field values for a member. A null value clears the field. All field_def_ids must be visible to the given group.","tags":["field-definitions"],"summary":"Set field values for a member (batch)","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Group ID","name":"group_id","in":"path","required":true},{"schema":{"type":"string","format":"uuid"},"description":"Member ID","name":"member_id","in":"path","required":true}],"responses":{"204":{"description":"Values saved"},"400":{"description":"A path parameter is not a valid UUID or malformed JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation failed or field_def_id not visible to group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetFieldValuesRequest"}}},"description":"Batch of field values","required":true}}}}}
```

## List field definitions for a section

> Returns all section-scoped field definitions belonging to the given section.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"FieldDef":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"field_type":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_required":{"type":"boolean"},"label":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"integer"}},"scope":{"type":"string"},"section_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}}}},"paths":{"/v1/sections/{section_id}/field-definitions":{"get":{"description":"Returns all section-scoped field definitions belonging to the given section.","tags":["field-definitions"],"summary":"List field definitions for a section","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Section ID","name":"section_id","in":"path","required":true}],"responses":{"200":{"description":"Section field definitions","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FieldDef"}}}}]}}}},"400":{"description":"section_id is not a valid UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create a section-scoped field definition

> Adds a new field definition scoped to the given section.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"FieldDef":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"field_type":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_required":{"type":"boolean"},"label":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"integer"}},"scope":{"type":"string"},"section_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}},"CreateFieldDefRequest":{"type":"object","required":["field_type","label","name"],"properties":{"description":{"type":"string"},"field_type":{"type":"string"},"is_required":{"type":"boolean"},"label":{"type":"string","maxLength":200,"minLength":1},"name":{"type":"string","maxLength":100,"minLength":1},"options":{"type":"array","items":{"type":"integer"}},"sort_order":{"type":"integer"}}}}},"paths":{"/v1/sections/{section_id}/field-definitions":{"post":{"description":"Adds a new field definition scoped to the given section.","tags":["field-definitions"],"summary":"Create a section-scoped field definition","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Section ID","name":"section_id","in":"path","required":true}],"responses":{"201":{"description":"The created field definition","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FieldDef"}}}]}}}},"400":{"description":"section_id is not a valid UUID or malformed JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFieldDefRequest"}}},"description":"Field definition to create","required":true}}}}}
```

## Delete a section-scoped field definition

> Removes a field definition from the section.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}}}},"paths":{"/v1/sections/{section_id}/field-definitions/{field_def_id}":{"delete":{"description":"Removes a field definition from the section.","tags":["field-definitions"],"summary":"Delete a section-scoped field definition","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Section ID","name":"section_id","in":"path","required":true},{"schema":{"type":"string","format":"uuid"},"description":"Field Definition ID","name":"field_def_id","in":"path","required":true}],"responses":{"204":{"description":"Field definition deleted"},"400":{"description":"A path parameter is not a valid UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Field definition not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update a section-scoped field definition

> Applies a partial update to a field definition in the given section.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"FieldDef":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"field_type":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"is_active":{"type":"boolean"},"is_required":{"type":"boolean"},"label":{"type":"string"},"name":{"type":"string"},"options":{"type":"array","items":{"type":"integer"}},"scope":{"type":"string"},"section_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}},"UpdateFieldDefRequest":{"type":"object","properties":{"category_id":{"type":"string","format":"uuid"},"description":{"type":"string"},"is_active":{"type":"boolean"},"is_required":{"type":"boolean"},"label":{"type":"string","maxLength":200,"minLength":1},"options":{"type":"array","items":{"type":"integer"}},"sort_order":{"type":"integer"}}}}},"paths":{"/v1/sections/{section_id}/field-definitions/{field_def_id}":{"patch":{"description":"Applies a partial update to a field definition in the given section.","tags":["field-definitions"],"summary":"Update a section-scoped field definition","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Section ID","name":"section_id","in":"path","required":true},{"schema":{"type":"string","format":"uuid"},"description":"Field Definition ID","name":"field_def_id","in":"path","required":true}],"responses":{"200":{"description":"The updated field definition","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FieldDef"}}}]}}}},"400":{"description":"A path parameter is not a valid UUID or malformed JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Field definition not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFieldDefRequest"}}},"description":"Fields to update","required":true}}}}}
```

## Add a platform field definition toggle to a section

> Enables a platform-scoped field definition for the given section. The field definition must be platform-scoped.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SuccessResponse":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/ResponseMeta"}}},"ResponseMeta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"request_id":{"type":"string","format":"uuid"},"total":{"type":"integer"}}},"Toggle":{"type":"object","properties":{"field_def_id":{"type":"string","format":"uuid"},"is_required":{"type":"boolean"},"section_id":{"type":"string","format":"uuid"},"sort_order":{"type":"integer"}}},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}},"CreateToggleRequest":{"type":"object","required":["field_def_id"],"properties":{"field_def_id":{"type":"string","format":"uuid"},"is_required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"paths":{"/v1/sections/{section_id}/field-toggles":{"post":{"description":"Enables a platform-scoped field definition for the given section. The field definition must be platform-scoped.","tags":["field-definitions"],"summary":"Add a platform field definition toggle to a section","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Section ID","name":"section_id","in":"path","required":true}],"responses":{"201":{"description":"The created toggle","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Toggle"}}}]}}}},"400":{"description":"section_id is not a valid UUID or malformed JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Field definition is not platform-scoped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Field definition not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateToggleRequest"}}},"description":"Toggle to add","required":true}}}}}
```

## Remove a platform field definition toggle from a section

> Disables a platform-scoped field definition for the given section.

```json
{"openapi":"3.1.1","info":{"title":"Trooply API","version":"1.0"},"servers":[{"url":"https://api.trooply.co.uk/"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Bearer access token. Generate one from the **Developer** area of your Trooply account and send it as `Authorization: Bearer <token>`.","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"integer"}}}}},"paths":{"/v1/sections/{section_id}/field-toggles/{field_def_id}":{"delete":{"description":"Disables a platform-scoped field definition for the given section.","tags":["field-definitions"],"summary":"Remove a platform field definition toggle from a section","parameters":[{"schema":{"type":"string","format":"uuid"},"description":"Section ID","name":"section_id","in":"path","required":true},{"schema":{"type":"string","format":"uuid"},"description":"Field Definition ID","name":"field_def_id","in":"path","required":true}],"responses":{"204":{"description":"Toggle removed"},"400":{"description":"A path parameter is not a valid UUID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# 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://developers.trooply.co.uk/field-definitions.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.