---
title: "Get document users"
url: "https://docs.signnow.com/docs/document/operations/get-document-roles"
type: "endpoint"
section: "document"
slug: "document/operations/get-document-roles"
method: "GET"
path: "/v2/documents/{document_id}/roles"
operation_id: "get-document-roles"
authorization: "bearer"
---

# Get document users

`GET /v2/documents/{document_id}/roles`

This endpoint allows API users to retrieve a paginated list of users who have access to the document, including their emails, roles, names, and avatars.

**Notes**

* The owner sees all users with roles (including themselves as `owner`).
* A non-owner (shared user) sees only the owner and themselves.

## Authorization

bearer

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_id` | string | Yes | Document ID. |

## Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | No | Number of items per page. Min: `1`, Max: `100`. Default: `15`. |
| `page` | integer | No | Page number. Min: `1`. Default: `1`. |

## Responses

### 200

Success. Returns a paginated list of users with access to the document.

**Example** (`Example 1`)

```json
{
  "data": [
    {
      "id": "abc123def456abc123def456abc123def456abc1",
      "role": "owner",
      "email": "owner@example.com",
      "full_name": "John Doe",
      "avatar_url": "https://example.com/avatars/abc123/download"
    },
    {
      "id": "def456abc123def456abc123def456abc123def4",
      "role": "viewer",
      "email": "viewer@example.com",
      "full_name": "Jane Smith",
      "avatar_url": null
    }
  ],
  "meta": {
    "pagination": {
      "count": 2,
      "total": 2,
      "per_page": 15,
      "total_pages": 1,
      "current_page": 1
    }
  }
}
```

**Example** (`application/json`)

```json
{
  "data": [
    {
      "id": "abc123def456abc123def456abc123def456abc1",
      "role": "owner",
      "email": "owner@example.com",
      "full_name": "John Doe",
      "avatar_url": "https://example.com/avatars/abc123/download"
    },
    {
      "id": "def456abc123def456abc123def456abc123def4",
      "role": "viewer",
      "email": "viewer@example.com",
      "full_name": "Jane Smith",
      "avatar_url": null
    }
  ],
  "meta": {
    "pagination": {
      "count": 2,
      "total": 2,
      "per_page": 15,
      "total_pages": 1,
      "current_page": 1
    }
  }
}
```

### 400

Bad request. Possible errors:

* Document not found.
* You don't have access to the entity.

**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "code": 12029021,
      "message": "Document not found."
    }
  ]
}
```

**Example** (`Document not found`)

```json
{
  "errors": [
    {
      "code": 12029021,
      "message": "Document not found."
    }
  ]
}
```

**Example** (`No access to entity`)

```json
{
  "errors": [
    {
      "code": 12029012,
      "message": "You don't have access to the entity."
    }
  ]
}
```

### 401

Incorrect or missing bearer token.

**Example** (`Example 1`)

```json
{
  "code": 1537,
  "error": "invalid_token"
}
```

**Example** (`Unauthorized`)

```json
{
  "code": 1537,
  "error": "invalid_token"
}
```

### 404

Incorrect document ID.

**Example** (`Example 1`)

```json
{
  "404": "Unable to find a route to match the URI: V2/documents/a8a70c6f26744bcfa6f03abfb5ae00694fed5d73/roles"
}
```

**Example** (`Incorrect document ID`)

```json
{
  "404": "Unable to find a route to match the URI: V2/documents/{document_id}/roles"
}
```

## Code Examples

> Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running.

### cURL

```bash
curl -X GET \
  "https://api.signnow.com/v2/documents/{document_id}/roles" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN"
```

---
*Full reference: https://docs.signnow.com/docs/document/operations/get-document-roles*