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",
    "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.
`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.

Documentation Index

Add a reader with project-level access

Add the reader