> For the complete documentation index, see [llms.txt](https://docs.truedat.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.truedat.io/v8.12/api-integrations/data-catalog-data-lineage-and-grants-apis/grant-request-groups.md).

# Grant Request Groups

## Create grant request group

> Creates a new grant request group containing one or more child requests.\
> \
> \*\*Permissions:\*\*\
> \- For requests that specify a data structure, requires the \*\*'Create grant request'\*\* permission on that structure.\
> \- For requests that specify an existing grant, requires domain‑level permissions for creating foreign grant requests (\*\*'Allow grant request from third parties'\*\*).\
> \- Additionally, the caller must have the \*\*'Create grant request group'\*\* permission, which is automatically satisfied if the group is created for the caller's own user ID.\
> \- Requests based on a \`grant\_id\` do not trigger additional structure‑level permission checks at creation time.\
> \
> \*\*Request\*\*\
> \- \`grant\_request\_group\` object with:\
> &#x20; \- \`requests\` (required) – list of child requests. Each must include either:\
> &#x20;   \- \`data\_structure\_id\` or \`data\_structure\_external\_id\` – for grant creation.\
> &#x20;   \- \`grant\_id\` – for grant modification or removal.\
> &#x20; \- \`user\_id\` (optional) – defaults to the current user.\
> &#x20; \- \`type\` (optional) – e.g., \`"grant\_request"\`.\
> &#x20; \- \`modification\_grant\_id\` (optional).<br>

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.12.2"},"paths":{"/api/grant_request_groups":{"post":{"description":"Creates a new grant request group containing one or more child requests.\n\n**Permissions:**\n- For requests that specify a data structure, requires the **'Create grant request'** permission on that structure.\n- For requests that specify an existing grant, requires domain‑level permissions for creating foreign grant requests (**'Allow grant request from third parties'**).\n- Additionally, the caller must have the **'Create grant request group'** permission, which is automatically satisfied if the group is created for the caller's own user ID.\n- Requests based on a `grant_id` do not trigger additional structure‑level permission checks at creation time.\n\n**Request**\n- `grant_request_group` object with:\n  - `requests` (required) – list of child requests. Each must include either:\n    - `data_structure_id` or `data_structure_external_id` – for grant creation.\n    - `grant_id` – for grant modification or removal.\n  - `user_id` (optional) – defaults to the current user.\n  - `type` (optional) – e.g., `\"grant_request\"`.\n  - `modification_grant_id` (optional).\n","operationId":"TdDdWeb.GrantRequestGroupController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantRequestGroupCreateRequest"}}},"description":"Grant request group payload","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantRequestGroupShowResponse"}}},"description":"Grant request group created"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdNotFoundMessageResponse"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DDUnprocessableEntityVariableResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Create grant request group","tags":["Grant Request Groups"]}}},"components":{"schemas":{"GrantRequestGroupCreateRequest":{"additionalProperties":false,"properties":{"grant_request_group":{"additionalProperties":false,"properties":{"modification_grant_id":{"nullable":true,"type":"integer"},"requests":{"items":{"additionalProperties":false,"properties":{"data_structure_external_id":{"nullable":true,"type":"string"},"data_structure_id":{"nullable":true,"type":"integer"},"filters":{"additionalProperties":true,"nullable":true,"type":"object"},"grant_id":{"nullable":true,"type":"integer"},"metadata":{"additionalProperties":true,"nullable":true,"type":"object"},"request_type":{"description":"Derived from the group when omitted or null: grant_modification if modification_grant_id is set, grant_access otherwise","enum":["grant_access","grant_removal","grant_modification"],"nullable":true,"type":"string"}},"type":"object"},"type":"array"},"type":{"nullable":true,"type":"string"},"user_group_id":{"nullable":true,"type":"integer"},"user_id":{"nullable":true,"type":"integer"}},"required":["requests"],"type":"object"}},"required":["grant_request_group"],"title":"GrantRequestGroupCreateRequest","type":"object"},"GrantRequestGroupShowResponse":{"additionalProperties":false,"properties":{"data":{"properties":{"_embedded":{"additionalProperties":true,"type":"object"},"created_by_id":{"nullable":true,"type":"integer"},"id":{"type":"integer"},"inserted_at":{"format":"date-time","type":"string"},"status":{"nullable":true,"type":"string"},"type":{"nullable":true,"type":"string"},"updated_at":{"format":"date-time","nullable":true,"type":"string"},"user_group_id":{"nullable":true,"type":"integer"},"user_id":{"nullable":true,"type":"integer"}},"required":["id"],"type":"object"}},"required":["data"],"title":"GrantRequestGroupShowResponse","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdNotFoundMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdNotFoundMessageResponse","type":"object"},"DDUnprocessableEntityVariableResponse":{"description":"Response for 422 errors. Error messages might have different formats","oneOf":[{"$ref":"#/components/schemas/TdDdUnprocessableEntityStringResponse"},{"$ref":"#/components/schemas/TdDdUnprocessableEntityArrayResponse"},{"$ref":"#/components/schemas/TdDdUnprocessableEntityObjectResponse"}],"title":"DDUnprocessableEntityVariableResponse"},"TdDdUnprocessableEntityStringResponse":{"additionalProperties":false,"properties":{"error":{"type":"string"},"message":{"type":"string"}},"title":"TdDdUnprocessableEntityStringResponse","type":"object"},"TdDdUnprocessableEntityArrayResponse":{"additionalProperties":false,"properties":{"error":{"items":{"type":"string"},"type":"array"},"errors":{"items":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object"},"type":"array"}},"title":"TdDdUnprocessableEntityArrayResponse","type":"object"},"TdDdUnprocessableEntityObjectResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnprocessableEntityObjectResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```

## Bulk create grant request groups

> Creates multiple grant request groups in a single request.\
> \
> \*\*Permissions:\*\*\
> The same permission rules as the single \`create\` endpoint apply to \*\*every\*\* group in the array.\
> \- For requests that specify a data structure, requires the \*\*'Create grant request'\*\* permission on that structure.\
> \- For requests that specify an existing grant, requires domain‑level permissions for creating foreign grant requests (\*\*'Allow grant request from third parties'\*\*).\
> \- Additionally, the caller must have the \*\*'Create grant request group'\*\* permission, which is automatically satisfied if the group is created for the caller's own user ID.\
> \- Requests based on a \`grant\_id\` do not trigger additional structure‑level permission checks at creation time.\
> The operation fails fast if \*\*any\*\* entry violates the request format or permission checks.\
> \
> \*\*Request body\*\*\
> The payload must contain a top‑level \`grant\_request\_groups\` array.\
> Each group object in the array has the following structure:\
> &#x20; \- \`requests\` (required) – list of child requests. Each must include either:\
> &#x20;   \- \`data\_structure\_id\` or \`data\_structure\_external\_id\` – for grant creation.\
> &#x20;   \- \`grant\_id\` – for grant modification or removal.\
> &#x20; \- \`user\_id\` (optional) – defaults to the current user.\
> &#x20; \- \`type\` (optional) – e.g., \`"grant\_request"\`.\
> &#x20; \- \`modification\_grant\_id\` (optional).<br>

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.12.2"},"paths":{"/api/grant_request_groups/bulk":{"post":{"description":"Creates multiple grant request groups in a single request.\n\n**Permissions:**\nThe same permission rules as the single `create` endpoint apply to **every** group in the array.\n- For requests that specify a data structure, requires the **'Create grant request'** permission on that structure.\n- For requests that specify an existing grant, requires domain‑level permissions for creating foreign grant requests (**'Allow grant request from third parties'**).\n- Additionally, the caller must have the **'Create grant request group'** permission, which is automatically satisfied if the group is created for the caller's own user ID.\n- Requests based on a `grant_id` do not trigger additional structure‑level permission checks at creation time.\nThe operation fails fast if **any** entry violates the request format or permission checks.\n\n**Request body**\nThe payload must contain a top‑level `grant_request_groups` array.\nEach group object in the array has the following structure:\n  - `requests` (required) – list of child requests. Each must include either:\n    - `data_structure_id` or `data_structure_external_id` – for grant creation.\n    - `grant_id` – for grant modification or removal.\n  - `user_id` (optional) – defaults to the current user.\n  - `type` (optional) – e.g., `\"grant_request\"`.\n  - `modification_grant_id` (optional).\n","operationId":"TdDdWeb.GrantRequestGroupController.bulk_create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantRequestGroupBulkCreateRequest"}}},"description":"Grant request groups payload","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantRequestGroupBulkCreateResponse"}}},"description":"Grant request groups created"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdNotFoundMessageResponse"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DDUnprocessableEntityVariableResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Bulk create grant request groups","tags":["Grant Request Groups"]}}},"components":{"schemas":{"GrantRequestGroupBulkCreateRequest":{"additionalProperties":false,"properties":{"grant_request_groups":{"items":{"additionalProperties":false,"properties":{"requests":{"items":{"additionalProperties":false,"properties":{"data_structure_external_id":{"nullable":true,"type":"string"},"data_structure_id":{"nullable":true,"type":"integer"},"filters":{"additionalProperties":true,"nullable":true,"type":"object"},"grant_id":{"nullable":true,"type":"integer"},"metadata":{"additionalProperties":true,"nullable":true,"type":"object"},"request_type":{"description":"Derived from the group when omitted or null: grant_modification if modification_grant_id is set, grant_access otherwise","enum":["grant_access","grant_removal","grant_modification"],"nullable":true,"type":"string"}},"type":"object"},"type":"array"},"type":{"description":"Group type","nullable":true,"type":"string"},"user_group_id":{"nullable":true,"type":"integer"},"user_id":{"nullable":true,"type":"integer"}},"required":["requests"],"type":"object"},"type":"array"}},"required":["grant_request_groups"],"title":"GrantRequestGroupBulkCreateRequest","type":"object"},"GrantRequestGroupBulkCreateResponse":{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"grant_request_groups":{"items":{"additionalProperties":true,"type":"object"},"type":"array"}},"required":["grant_request_groups"],"type":"object"}},"required":["data"],"title":"GrantRequestGroupBulkCreateResponse","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdNotFoundMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdNotFoundMessageResponse","type":"object"},"DDUnprocessableEntityVariableResponse":{"description":"Response for 422 errors. Error messages might have different formats","oneOf":[{"$ref":"#/components/schemas/TdDdUnprocessableEntityStringResponse"},{"$ref":"#/components/schemas/TdDdUnprocessableEntityArrayResponse"},{"$ref":"#/components/schemas/TdDdUnprocessableEntityObjectResponse"}],"title":"DDUnprocessableEntityVariableResponse"},"TdDdUnprocessableEntityStringResponse":{"additionalProperties":false,"properties":{"error":{"type":"string"},"message":{"type":"string"}},"title":"TdDdUnprocessableEntityStringResponse","type":"object"},"TdDdUnprocessableEntityArrayResponse":{"additionalProperties":false,"properties":{"error":{"items":{"type":"string"},"type":"array"},"errors":{"items":{"properties":{"code":{"type":"string"},"name":{"type":"string"}},"type":"object"},"type":"array"}},"title":"TdDdUnprocessableEntityArrayResponse","type":"object"},"TdDdUnprocessableEntityObjectResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnprocessableEntityObjectResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```

## Get grant request group by ID

> Retrieves a grant request group and its associated child requests.\
> \
> \*\*Permissions:\*\* Requires the \*\*'View grant request group'\*\* permission on the target group.\
> This permission is automatically granted if:\
> \- The user is the target user (\`user\_id\`).\
> \- The user created the group (\`created\_by\_id\`).\
> \- The user belongs to the group's associated user group (\`user\_group\_id\`).\
> \- The user has the "Approve grant request" permission on the domains or structures covered by the group's requests.\
> \
> The response includes the full list of child grant requests embedded under \`\_embedded.requests\`.<br>

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.12.2"},"paths":{"/api/grant_request_groups/{id}":{"get":{"description":"Retrieves a grant request group and its associated child requests.\n\n**Permissions:** Requires the **'View grant request group'** permission on the target group.\nThis permission is automatically granted if:\n- The user is the target user (`user_id`).\n- The user created the group (`created_by_id`).\n- The user belongs to the group's associated user group (`user_group_id`).\n- The user has the \"Approve grant request\" permission on the domains or structures covered by the group's requests.\n\nThe response includes the full list of child grant requests embedded under `_embedded.requests`.\n","operationId":"TdDdWeb.GrantRequestGroupController.show","parameters":[{"description":"Grant request group ID","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrantRequestGroupShowResponse"}}},"description":"Grant request group retrieved"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdNotFoundErrorResponse"}}},"description":"Not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Get grant request group by ID","tags":["Grant Request Groups"]}}},"components":{"schemas":{"GrantRequestGroupShowResponse":{"additionalProperties":false,"properties":{"data":{"properties":{"_embedded":{"additionalProperties":true,"type":"object"},"created_by_id":{"nullable":true,"type":"integer"},"id":{"type":"integer"},"inserted_at":{"format":"date-time","type":"string"},"status":{"nullable":true,"type":"string"},"type":{"nullable":true,"type":"string"},"updated_at":{"format":"date-time","nullable":true,"type":"string"},"user_group_id":{"nullable":true,"type":"integer"},"user_id":{"nullable":true,"type":"integer"}},"required":["id"],"type":"object"}},"required":["data"],"title":"GrantRequestGroupShowResponse","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdNotFoundErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdNotFoundErrorResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```

## Delete grant request group

> Permanently deletes (hard delete) a grant request group identified by the given ID. The group and all its child grant requests are removed from the database immediately.\
> \
> Requires the user to have administrative privileges (\*\*administrator or service account\*\*).<br>

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.12.2"},"paths":{"/api/grant_request_groups/{id}":{"delete":{"description":"Permanently deletes (hard delete) a grant request group identified by the given ID. The group and all its child grant requests are removed from the database immediately.\n\nRequires the user to have administrative privileges (**administrator or service account**).\n","operationId":"TdDdWeb.GrantRequestGroupController.delete","parameters":[{"description":"Grant request group ID","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Grant request group deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdNotFoundErrorResponse"}}},"description":"Not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Delete grant request group","tags":["Grant Request Groups"]}}},"components":{"schemas":{"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdNotFoundErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdNotFoundErrorResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```