---
title: "Add document user"
method: POST
path: "/documents/{document}/users"
tags: ["Document Operations"]
---

# Add document user

`POST /documents/{document}/users`

<small>Requires an API token with the **Document Manager** role.</small>

Gives a person access to a [document](/#documents) with the specified access level (`role`). By default the
user receives an invitation email for the document; pass `invite_method` to instead create a [personal
link](/#shareable-links) for them (returned in the response's `personal_link` field) or to add them
silently.

With `fynk_email`, the invitation email to a user without a fynk account user in your account carries the
document's default text for external collaborator invitations, if one is set on the document or inherited from
its template. This text is configured in fynk and is not part of the API.

> **Note:** When adding a user whose email corresponds to an existing user in the current fynk account, only
> `email` and `role` are used. Any additional fields (`first_name`, `last_name`, `title`) will be ignored and
> the user's information will be populated from their existing profile. Only such users can be given the
> `owner` role, and they cannot be added with the `personal_link` invite method.

> **Note:** Users without a fynk account user in your account cannot be added while the document is in the
> `draft` or `approved_draft` stage, regardless of the invite method. Attempting to do so will return a `409`
> response.

If the email address already belongs to a document user on this document, the request will be rejected with a
validation error - use the [Update document user](/operations/v1.documents.users.update) endpoint to change
their access level instead. This includes [signatories](/#signatories), who always appear as document users
as well.

## Path parameters

- `document` string, required

## Request body

- StoreDocumentUserRequest
  - `email` string, email, required — The user's email address
  - `role` 'owner' | 'collaborator' | 'viewer', required — The representation of a document user's access level in the external API. Internally the access level is held in the document user's roles (where a plain viewer simply has no role); the external API always exposes it as one of these three values.
  - `invite_method` 'fynk_email' | 'personal_link' | 'none' — How a newly added document user is given access to the document. | | |---| | `fynk_email` <br/> The user receives a fynk invitation email (the default). | | `personal_link` <br/> A personal link is created for the user; delivering it is up to the API consumer. | | `none` <br/> The user is added silently. |
  - `party_uuid` string, uuid, nullable — UUID of the [party](/#parties) the user belongs to
  - `first_name` string, nullable — Ignored when the email corresponds to an existing user in the current fynk account
  - `last_name` string, nullable — Ignored when the email corresponds to an existing user in the current fynk account
  - `title` string, nullable — Ignored when the email corresponds to an existing user in the current fynk account

## Response `201`

`DocumentUserResource`

- object
  - `data` DocumentUserResource, required
    - `uuid` string, required
    - `first_name` string, nullable, required
    - `last_name` string, nullable, required
    - `email` string, nullable, required
    - `title` string, nullable, required
    - `party_uuid` string, nullable, required — UUID of the [party](/#parties) the user belongs to, if any
    - `has_account_user` boolean, required — `true` if the document user has a fynk user belonging to your account
    - `role` 'owner' | 'collaborator' | 'viewer', required — The representation of a document user's access level in the external API. Internally the access level is held in the document user's roles (where a plain viewer simply has no role); the external API always exposes it as one of these three values.
    - `is_signatory` boolean, required — `true` if the user is also a [signatory](/#signatories) of the document. Use the signatory endpoints to manage this
    - `personal_link` ShareableLinkResource
      - `uuid` string, required
      - `url` string, required — The link URL. Treat it like a secret: anyone who has the URL can access the document with it
      - `expires_at` string, date-time, nullable, required — When the link stops working. `null` means the link never expires
      - `message` string, nullable, required — A personal message shown when the link is opened. Always `null` for public links
      - `created_at` string, date-time, nullable, required

## Other responses

- `401` — Unauthenticated
- `403` — Authorization error
- `404` — Not found
- `409` — The resource's current state prevents the requested change
- `422` — Validation error

---

[API](https://skmtc.dev/fynk/apis/fynk-api-reference.md) · [All operations](https://skmtc.dev/fynk/apis/fynk-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fynk/fynk-api-reference/revisions/9657a6757f59/schema)