---
title: "Grant permission"
method: POST
path: "/forms/{formId}/permissions"
tags: ["Permissions"]
---

# Grant permission

`POST /forms/{formId}/permissions`

Grants a role on a form to a user or a group. Requires MANAGE permission.

## Request body

- union
  - object
    - `role` 'view' | 'respond' | 'comment' | 'analyze' | 'edit' | 'manage', required
    - `user` string, email, required
    - `group` string, ulid
  - object
    - `role` 'view' | 'respond' | 'comment' | 'analyze' | 'edit' | 'manage', required
    - `user` string, email
    - `group` string, ulid, required

## Response `201`

Permission granted successfully.

- Permission
  - `id` string, ulid, required
  - `form` string, ulid, required
  - `role` 'view' | 'respond' | 'comment' | 'analyze' | 'edit' | 'manage', required
  - `user` string, ulid, nullable
  - `group` string, ulid, nullable

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict
- `422` — Unprocessable Entity

## Changes

- **2025-07-14** `9aec27988ad3` — 1 breaking
  - the `user` request property format changed from `ulid` to `email`
- **2025-07-13** `0d7f3c750979` — 1 breaking
  - the `user` request property format changed from `email` to `ulid`

[Change history](https://skmtc.dev/osdg-iiith/apis/forms-portal-api/changes/forms/:formId/permissions/post.md)

---

[API](https://skmtc.dev/osdg-iiith/apis/forms-portal-api.md) · [All operations](https://skmtc.dev/osdg-iiith/apis/forms-portal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/osdg-iiith/apis/forms-portal-api/revisions/de597e8f26bc?raw)