---
title: "Add a reader with project-level access"
slug: "add-a-reader-with-project-level-access"
description: "Invite new readers to your Private or Mixed knowledge base using the v3 API. Learn how to set project-level access and retrieve reader details."
updated: 2026-09-05T18:39:54Z
published: 2026-09-05T18:39:54Z
canonical: "apidocs.document360.com/add-a-reader-with-project-level-access"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.document360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a reader with project-level access

You can use the v3 API to invite a new reader with project-level access to a Private or Mixed knowledge base. An invitation email is sent to the reader.

## Add the reader

Send a `POST` request. Set `access_scope.access_level` to `project` for project-wide access.

```
POST /v3/projects/{project_id}/readers
```

```
curl --request POST "https://apihub.document360.io/v3/projects/{project_id}/readers" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "invited_by": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "access_scope": { "access_level": "project" }
  }'
```

| Field | Required | Description |
| --- | --- | --- |
| `email` | Yes | Reader's email address. |
| `access_scope` | Yes | The reader's access scope. Use `access_level: project` for project-wide access. |
| `invited_by` | Yes, with an API key | The user sending the invitation. Required when authenticating with `X-API-Key`. Ignored when using a user access token (OAuth). |
| `first_name` / `last_name` | No | Reader's name. |
| `associated_reader_groups` | No | Reader group IDs to add the reader to. |
| `is_sso_user` / `scheme_name` | No | Set for SSO readers; `scheme_name` is required when `is_sso_user` is `true`. |

A successful request returns `201 Created` with the new reader's identity:

```
{
  "success": true,
  "request_id": "req_abc123def456",
  "data": {
    "id": "a3b4c5d6-e7f8-4a9b-c0d1-e2f3a4b5c6d7",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "access_scope": null,
    "associated_reader_groups": null,
    "is_invite_sso_user": false,
    "last_login_at": null
  }
}
```

Only the reader's `id`, name and email are populated on the create response; the remaining fields are returned as `null` or `false`. To retrieve the reader's full record, including the resolved `access_scope` and group memberships, call `GET /v3/projects/{project_id}/readers`.

Note

For narrower access, set `access_level` to `category`, `version` (workspace) or `language` and supply the matching `categories`, `workspaces` or `languages` arrays. Requires the **Manage roles, accounts and groups** permission.

Important

This endpoint is part of the premium API add-on. If it is not enabled for your project, the request returns `403` with the error code `PREMIUM_FEATURE_NOT_IN_LICENSE`. If your plan's reader seats are exhausted, the request returns `403` with `LICENSE_LIMIT_EXCEEDED`.

## Related

- [Add a user with project-level access](/add-a-user-with-project-level-access.md)
- [Create a reader](/create-a-reader.md)
- [Create a user](/create-a-user.md)