# Create group (idempotent)

`POST https://api.agilitycredit.net/scim/v2/{tenantId}/Groups`

Docs page: https://apidocs.agilitycredit.com/sso/scim-api/create-group · Tag: Groups

Agility's groups are virtual. A `displayName` matching a configured IdP group
returns the existing virtual group with `201`. An unknown name returns `404`.
No new mapping is created.

Authentication: `Authorization: Bearer <api key>`.

## Request body (`application/scim+json`), required

Schema: `Group`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `schemas` | array of string | yes |  |
| `id` | string |  | The role name (e.g. `admin`). Server-managed. |
| `displayName` | string | yes | The IdP group name as configured in the tenant's role mapping. Cannot be changed via SCIM. |
| `members` | array of object |  |  |
| `members[].value` | string | yes | The user's `id`. |
| `members[].display` | string |  | The user's email. |
| `meta` | object |  |  |
| `meta.resourceType` | string: `User`, `Group`, `Schema`, `ServiceProviderConfig` |  |  |
| `meta.created` | string (date-time) |  |  |
| `meta.lastModified` | string (date-time) |  |  |
| `meta.location` | string |  |  |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 201 | Existing virtual group. | Group |
| 400 | Payload validation failed. | Error |
| 404 | Resource not found. | Error |
| 503 | SCIM provisioning is disabled on the tenant. | Error |

### Error bodies

400:

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "400",
  "scimType": "invalidValue",
  "detail": "userName or emails[0].value is required"
}
```

404:

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "404",
  "detail": "User not found"
}
```

503:

```json
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": "503",
  "detail": "SCIM provisioning is disabled for this tenant"
}
```