> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mercoa.com/embedded-ap-ar/api-reference/entity/user/find/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server.

# Search entity users

GET https://api.mercoa.com/entity/{entityId}/users

Search entity users

Reference: https://docs.mercoa.com/embedded-ap-ar/api-reference/entity/user/find

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `entityId` (string, required) — Entity ID or Entity ForeignID

### Query parameters

- `foreignId` (string, optional) — ID used to identify user in your system
- `role` (string, optional) — Filter users by role. If multiple roles are provided, users with any of the roles will be returned.
- `name` (string, optional) — Filter users by name. Partial matches are supported.
- `email` (string, optional) — Filter users by email. Partial matches are supported.
- `limit` (integer, optional) — Number of entities to return. Limit can range between 1 and 100, and the default is 10.
- `startingAfter` (string, optional) — The ID of the user to start after. If not provided, the first page of entities will be returned.

## Response

### 200

- `count` (integer, required) — Total number of users for the given filters. This value is not limited by the limit parameter. It is provided so that you can determine how many pages of results are available.
- `hasMore` (boolean, required) — True if there are more users available for the given filters.
- `data` (list of object, required)
  - `id` (string, required)
  - `roles` (list of string, required)
  - `createdAt` (datetime, required)
  - `updatedAt` (datetime, required)
  - `foreignId` (string, optional) — The ID used to identify this user in your system.
  - `email` (string, optional)
  - `name` (string, optional)

## Errors

### 400 Bad Request

- `errorName` ("BadRequest", required)
- `content` (string, required)

### 401 Unauthorized

- `errorName` ("Unauthorized", required)
- `content` (string, required)

### 403 Forbidden

- `errorName` ("Forbidden", required)
- `content` (string, required)

### 404 Not Found

- `errorName` ("NotFound", required)
- `content` (string, required)

### 409 Conflict

- `errorName` ("Conflict", required)
- `content` (string, required)

### 500 Internal Server Error

- `errorName` ("InternalServerError", required)
- `content` (string, required)

### 501 Unimplemented

- `errorName` ("Unimplemented", required)
- `content` (string, required)

## Examples

**Response**

```json
{
  "count": 1,
  "hasMore": false,
  "data": [
    {
      "id": "user_ec3aafc8-ea86-408a-a6c1-545497badbbb",
      "roles": [
        "admin",
        "approver"
      ],
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "foreignId": "MY-DB-ID-12345",
      "email": "john.doe@acme.com",
      "name": "John Doe"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/users"

querystring = {"name":"John"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```typescript
import { MercoaClient } from "@mercoa/javascript";

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.entity.user.find("ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced", {
    name: "John"
});

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/users?name=John"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/users?name=John")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/users?name=John")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/users?name=John', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/users?name=John");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/entity/ent_a0f6ea94-0761-4a5e-a416-3c453cb7eced/users?name=John")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```