> 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-group/user/sync/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server.

# Sync Group Users

POST https://api.mercoa.com/entityGroup/{entityGroupId}/sync-users
Content-Type: application/json

Sync entity group users. This will add users to entities that do not have them and remove users from entities that have them.

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

## Authentication

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

## Request

### Path parameters

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

### Body (application/json)

This endpoint expects an object.

- `copyUsersFrom` (string, optional) — Entity ID / foreign ID of an entity currently in the group to copy users and roles from. If not provided, users will be synced from the entity with the most users that has been updated most recently.
- `filterRoles` (list of string, optional) — List of roles to filter users by. If not provided, all users will be copied. If provided, only users with the provided roles will be copied.
- `addUsers` (boolean, optional) — If true, users will be added to entities if they are not found in the copyUsersFrom entity. Default is true.
- `removeUsers` (boolean, optional) — If true, users will be removed from entities if they are not found in the copyUsersFrom entity. Default is false.

## 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

**Request**

```json
{
  "filterRoles": [
    "approver",
    "viewer"
  ]
}
```

**SDK Code**

```python Default
import requests

url = "https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/sync-users"

payload = { "filterRoles": ["approver", "viewer"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

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

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.entityGroup.user.sync("entg_8545a84e-a45f-41bf-bdf1-33b42a55812c", {
    filterRoles: ["approver", "viewer"]
});

```

```go Default
package main

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

func main() {

	url := "https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/sync-users"

	payload := strings.NewReader("{\n  \"filterRoles\": [\n    \"approver\",\n    \"viewer\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

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

}
```

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

url = URI("https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/sync-users")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filterRoles\": [\n    \"approver\",\n    \"viewer\"\n  ]\n}"

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

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

HttpResponse<String> response = Unirest.post("https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/sync-users")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filterRoles\": [\n    \"approver\",\n    \"viewer\"\n  ]\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/sync-users', [
  'body' => '{
  "filterRoles": [
    "approver",
    "viewer"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp Default
using RestSharp;

var client = new RestClient("https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/sync-users");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"filterRoles\": [\n    \"approver\",\n    \"viewer\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Default
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["filterRoles": ["approver", "viewer"]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/sync-users")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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()
```