> For the complete documentation index, see [llms.txt](https://docs.insurehero.io/shield-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.insurehero.io/shield-api/integrations/fetch-users.md).

# Fetch Users

## Endpoints

<table><thead><tr><th width="113">Method</th><th>Endpoint</th></tr></thead><tbody><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#all-users"><code>https://app.insurehero.io/api/shield/integrations/v1/users</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-a-specific-user"><code>https://app.insurehero.io/api/shield/integrations/v1/users/:userId</code></a></td></tr><tr><td><mark style="color:blue;">GET</mark></td><td><a href="#get-a-user-by-email"><code>https://app.insurehero.io/api/shield/integrations/v1/users/by-email/:userEmail</code></a></td></tr></tbody></table>

{% hint style="info" %}
These endpoints only search the channels where your API key has the `users` table selected in its [webhooks configuration](/shield-api/integrations/webhooks-configuration.md). Broker and insurer API keys get the same results. To get the claims of a user, see [Fetch all claims from a given user](/shield-api/integrations/fetch-claims.md#fetch-all-claims-from-a-given-user).
{% endhint %}

All error responses use the `{ "error": string, "details": any }` envelope. See [Error Handling](https://docs.insurehero.io/shield-api/data-dictionary#error-handling) for the general format.

### All users

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/integrations/v1/users`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Query Parameters

| Name                                   | Type   | Description                                                                                |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------ |
| from<mark style="color:red;">\*</mark> | number | Starting record index (0-based).                                                           |
| to<mark style="color:red;">\*</mark>   | number | Ending record index (inclusive). It must be greater than `from`, and at most `from + 100`. |

#### Example Response

When your API key has no channel with the `users` table selected, the list is empty.

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": [
        {
            "id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
            "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
            "email": "maria.lopez@example.com",
            "first_name": "Maria",
            "last_name": "Lopez",
            "phone": "+593991234501",
            "uid": "USR-0001",
            "gender": "FEMALE",
            "dob": "1990-05-10",
            "address": null,
            "document_type": "CI",
            "document_number": "1700000001",
            "bank_accounts": null,
            "company_name": null,
            "company_role": null,
            "company_email": null,
            "company_identifier": null,
            "company_address": null,
            "company_bank_accounts": null,
            "group_id": null,
            "metadata": {}
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}

```json
{
    "error": "Request contains malformed data",
    "details": "Missing bearer token"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

```json
{
    "error": "Invalid or expired access token",
    "details": "Invalid access token"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}

```json
{
    "error": "Internal validation failed",
    "details": {
        "issues": [
            {
                "code": "custom",
                "message": "Invalid range, range cannot exceed 100 records. Update either to or from.",
                "path": []
            }
        ],
        "name": "ZodError"
    }
}
```

The same message is returned when `to` is not greater than `from`. Missing `from` or `to` returns an input validation error.
{% endtab %}
{% endtabs %}

#### Attributes

<table><thead><tr><th width="242">Name</th><th width="127">Type</th><th>Description</th></tr></thead><tbody><tr><td>data</td><td>object</td><td>Main container that holds all user information.</td></tr><tr><td>id</td><td>uuid</td><td>Unique identifier of the user.</td></tr><tr><td>channel_id</td><td>uuid</td><td>Identifier of the channel.</td></tr><tr><td>email</td><td>string</td><td>Email of user.</td></tr><tr><td>first_name</td><td>string</td><td>User's first name.</td></tr><tr><td>last_name</td><td>string</td><td>User's last name.</td></tr><tr><td>phone</td><td>string</td><td>User's phone number (Must be unique).</td></tr><tr><td>uid</td><td>string</td><td>Additional user's unique identifier in your system.</td></tr><tr><td>gender</td><td>string</td><td>MALE | FEMALE.</td></tr><tr><td>dob</td><td>string</td><td>User's date of birth.</td></tr><tr><td>address</td><td>string</td><td>The user's address information.</td></tr><tr><td>document_type</td><td>string</td><td>The type of document can be: PASSPORT, RUC, CI and CURP.</td></tr><tr><td>document_number</td><td>string</td><td>The user's document number.</td></tr><tr><td>bank_accounts</td><td>string</td><td>User bank accounts.</td></tr><tr><td>company_name</td><td>string</td><td>User company name.</td></tr><tr><td>company_role</td><td>string</td><td>User company role.</td></tr><tr><td>company_email</td><td>string</td><td>User company email.</td></tr><tr><td>company_identifier</td><td>string</td><td>User company identifier.</td></tr><tr><td>company_address</td><td>string</td><td>The user's company address information.</td></tr><tr><td>company_bank_accounts</td><td>string</td><td>The object fields are the same fields as bank_accounts.</td></tr><tr><td>group_id</td><td>uuid</td><td>The id of the group;</td></tr><tr><td>metadata</td><td>object</td><td>Additional data to include in the user record.</td></tr></tbody></table>

### Get a specific user

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/integrations/v1/users/:userId`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

| Name                                     | Type   | Description                                                      |
| ---------------------------------------- | ------ | ---------------------------------------------------------------- |
| userId<mark style="color:red;">\*</mark> | string | The user id, or the value of the field selected with `searchBy`. |

#### Query Parameters

| Name     | Type   | Description                                                                                                                                                     |
| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| searchBy | string | Field used to search for the user: `id` (default), `uid`, `email`, `phone` or `document_number`. Except for `id` and `uid`, the value is compared in lowercase. |

#### Example Response

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": {
        "id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
        "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
        "email": "maria.lopez@example.com",
        "first_name": "Maria",
        "last_name": "Lopez",
        "phone": "+593991234501",
        "uid": "USR-0001",
        "gender": "FEMALE",
        "dob": "1990-05-10",
        "address": null,
        "document_type": "CI",
        "document_number": "1700000001",
        "bank_accounts": null,
        "company_name": null,
        "company_role": null,
        "company_email": null,
        "company_identifier": null,
        "company_address": null,
        "company_bank_accounts": null,
        "group_id": null,
        "metadata": {}
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}

```json
{
    "error": "Request contains malformed data",
    "details": "Missing bearer token"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

```json
{
    "error": "Invalid or expired access token",
    "details": "Invalid access token"
}
```

{% endtab %}

{% tab title="404: Not Found Resource not found" %}

```json
{
    "error": "Resource not found",
    "details": "User not found"
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Internal validation failed" %}
An unknown `searchBy` returns an input validation error. See [Error Handling](https://docs.insurehero.io/shield-api/data-dictionary#error-handling).
{% endtab %}
{% endtabs %}

`404` is also returned when the value matches users in more than one of your channels.

#### Attributes

Same fields as in [All users](#all-users), in a single object in `data`.

### Get a user by email

<mark style="color:blue;">`GET`</mark> `https://app.insurehero.io/api/shield/integrations/v1/users/by-email/:userEmail`

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer access token |

#### Path Parameters

| Name                                        | Type   | Description                                     |
| ------------------------------------------- | ------ | ----------------------------------------------- |
| userEmail<mark style="color:red;">\*</mark> | string | Email of the user. It is compared in lowercase. |

#### Example Response

{% tabs %}
{% tab title="200: OK Retrieved successfully" %}

```json
{
    "data": {
        "id": "c4b53bc9-3cc6-501a-9d54-dbd25584d725",
        "channel_id": "0ccad1d6-18ee-5c17-a684-9f8fe203d7c1",
        "email": "maria.lopez@example.com",
        "first_name": "Maria",
        "last_name": "Lopez",
        "phone": "+593991234501",
        "uid": "USR-0001",
        "gender": "FEMALE",
        "dob": "1990-05-10",
        "address": null,
        "document_type": "CI",
        "document_number": "1700000001",
        "bank_accounts": null,
        "company_name": null,
        "company_role": null,
        "company_email": null,
        "company_identifier": null,
        "company_address": null,
        "company_bank_accounts": null,
        "group_id": null,
        "metadata": {}
    }
}
```

{% endtab %}

{% tab title="400: Bad Request Request contains malformed data" %}

```json
{
    "error": "Request contains malformed data",
    "details": "Missing bearer token"
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid or expired access token" %}

```json
{
    "error": "Invalid or expired access token",
    "details": "Invalid access token"
}
```

{% endtab %}

{% tab title="404: Not Found Resource not found" %}

```json
{
    "error": "Resource not found",
    "details": "User not found"
}
```

{% endtab %}
{% endtabs %}

`404` is also returned when the email matches users in more than one of your channels.

#### Attributes

Same fields as in [All users](#all-users), in a single object in `data`.

To access these resources, please remember to visit the [**Links and Resources**](/shield-api/links-and-resources.md) section of the documentation.