# createConnectionTeam

Source: /openapi/thomas-federated.openapi.json

## Operation

| Method | URL |
|---|---|
| POST | https://staging-api.thomas.co/v1/teams |

| Field | Value |
|---|---|
| operationId | createConnectionTeam |
| method | POST |
| server | https://staging-api.thomas.co |
| path | /v1/teams |
| tags | `Teams` |
| summary | Create a connection team |
| badges | `{"name":"Partner scope: teams:w and users:r"}` |
| scopes | `teams:w`, `users:r` |

## Description

For an API client calling as itself, the body additionally carries the calling partner's own `externalTeamReference` and its `sourceVersion`, and must name at least one human owner — the machine caller is never added as an owner or member. A request made on behalf of a named person (`Thomas-On-Behalf-Of`) is that person creating the team: it sends the human document, and the person is the creator exactly as when signed in. The response returns the THOMAS team id, which is the address for every later operation on this team, alongside the reference a machine caller submitted. `sourceVersion` is recorded as provenance and is never compared: team writes are not version-ordered. For an API client calling as itself, each named owner and member must be an active or pending (not yet signed in) colleague of the tenant, and any other person is refused with `IDENTITY_COLLEAGUE_REQUIRED`. For a person, or a request on behalf of one, naming a suspended or archived colleague is refused with the same `IDENTITY_COLLEAGUE_REQUIRED`.

## Request Parameters

| Name | In | Required | Schema | Description |
|---|---|---|---|---|
| Idempotency-Key | header | false | string | An opaque client-generated key, 1-255 visible ASCII characters excluding comma. Optional, and recommended for every write. Repeating a request with the same key and the same canonical request returns the ORIGINAL response instead of performing the work twice. Reusing the key for a DIFFERENT canonical request is refused with 409 IDEMPOTENCY_KEY_REUSED, and an equivalent request still in flight is refused with 409 IDEMPOTENCY_REQUEST_IN_PROGRESS and a Retry-After header. Omit it and the operation behaves exactly as it does without this header: the work is performed, and no replay protection applies. Sending the header with an EMPTY value counts as omitting it; any other malformed value — a repeated header, a comma-separated pair, or a value outside the charset or length above — is refused with 400 IDEMPOTENCY_KEY_INVALID. |
| Thomas-Tenant-Id | header | true | string:uuid | Required for API clients: the Tenant this call acts in. Send exactly one. Signed-in users don't send it — their Tenant comes from their session. The header only selects the Tenant; your Grant for it decides access, and is checked on every call. |
| Thomas-On-Behalf-Of | header | false | string | Optional for a Partner API client on this operation. Send it to act on behalf of one named person: thomas:<companyIndividualId> or partner:<partnerReference>. The call is then authorised as that person, within that person's access circles and the scopes your Grant holds. Omit it to call as your API client. A signed-in person never sends it. |

## Request Body

| Content type | Required | Schema refs |
|---|---|---|
| application/json | true | #/components/schemas/CreateExplicitTeamDto, #/components/schemas/CreatePartnerTeamDto |

## Responses

| Status | Description | Schema refs |
|---|---|---|
| 201 | Connection team created | #/components/schemas/TeamWithMembersResponseDto |
| 400 | Invalid request payload, or a malformed `Idempotency-Key`. The Idempotency-Key header may also be sent in a shape that cannot be bound. Also returned when the Thomas-On-Behalf-Of header is repeated or malformed. | #/components/schemas/ApiErrorResponseDto |
| 401 | Invalid or missing authentication token | #/components/schemas/ApiErrorResponseDto |
| 403 | The calling human has not completed a scored behaviour assessment, is hidden until revealed or confidential, the request names an ineligible owner or member, or an API client is not authorized for this tenant/operation. An API client whose Grant is active and carries the scope, but which is not the tenant’s active source of record for this data — including any consumer-role Grant — is refused (AUTH_SOURCE_OF_RECORD_REQUIRED). | #/components/schemas/ApiErrorResponseDto |
| 404 | The roster names an id that is not a current employee of this tenant. Also returned when the person named in Thomas-On-Behalf-Of is unavailable. | #/components/schemas/ApiErrorResponseDto |
| 409 | For an API client: the submitted `externalTeamReference` is already bound to a team in this API client's namespace for this tenant. `details.teamId` names that Thomas team, so a partner that has lost its reference map recovers the entry from this one response. The Idempotency-Key may also conflict with an attempt already recorded against it. | #/components/schemas/ApiErrorResponseDto |
| 422 | The target is a manager-derived (implicit) team, or a person the request would make a team owner is hidden until revealed or confidential | #/components/schemas/ApiErrorResponseDto |
| 429 | Rate limit exceeded. | #/components/schemas/ApiErrorResponseDto |

### Response 409 headers

| Name | Description | Schema |
|---|---|---|
| Retry-After | Present as `1` only when an equivalent idempotent request is in progress | {"type":"string","example":"1"} |

### Response 429 headers

| Name | Description | Schema |
|---|---|---|
| Retry-After | Seconds until the rate-limit block expires before retrying. | {"type":"integer","minimum":0} |
| RateLimit-Limit | Configured request limit for the active rate-limit window. | {"type":"integer"} |
| RateLimit-Remaining | Requests remaining in the active rate-limit window; zero when blocked. | {"type":"integer"} |
| RateLimit-Reset | Seconds until the rate-limit block expires. | {"type":"integer","minimum":0} |

## Artifact Examples

### Response 400 example — VALIDATION_ERROR

```json
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "VALIDATION_ERROR"
}
```

### Response 400 example — TEAM_REQUIRES_PARTICIPANT

```json
{
  "statusCode": 400,
  "message": "A team must have at least one participant",
  "error": "TEAM_REQUIRES_PARTICIPANT"
}
```

### Response 400 example — TEAM_PEOPLE_LIMIT_EXCEEDED

```json
{
  "statusCode": 400,
  "message": "A team can have at most 50 participants",
  "error": "TEAM_PEOPLE_LIMIT_EXCEEDED"
}
```

### Response 400 example — TEAM_HOST_LIMIT_EXCEEDED

```json
{
  "statusCode": 400,
  "message": "A team can have at most 10 owners",
  "error": "TEAM_HOST_LIMIT_EXCEEDED"
}
```

### Response 400 example — IDEMPOTENCY_KEY_INVALID

```json
{
  "statusCode": 400,
  "message": "Exactly one valid Idempotency-Key header is required",
  "error": "IDEMPOTENCY_KEY_INVALID"
}
```

### Response 400 example — AUTH_TENANT_CONTEXT_INVALID

```json
{
  "statusCode": 400,
  "message": "Exactly one valid Thomas-On-Behalf-Of header is required",
  "error": "AUTH_TENANT_CONTEXT_INVALID"
}
```

### Response 401 example

```json
{
  "statusCode": 401,
  "message": "Invalid or missing authentication token",
  "error": "AUTH_TOKEN_INVALID"
}
```

### Response 403 example — ASSESSMENT_REQUIRED

```json
{
  "statusCode": 403,
  "message": "You must complete your behaviour assessment before creating a team",
  "error": "ASSESSMENT_REQUIRED"
}
```

### Response 403 example — TEAM_CREATOR_DIRECTORY_HIDDEN

```json
{
  "statusCode": 403,
  "message": "You cannot create a team yet. Your organisation has not added you to the directory. You'll be able to create one once an admin makes you visible.",
  "error": "TEAM_CREATOR_DIRECTORY_HIDDEN"
}
```

### Response 403 example — TEAM_CREATOR_CONFIDENTIAL

```json
{
  "statusCode": 403,
  "message": "You can't create a team while your record is confidential.",
  "error": "TEAM_CREATOR_CONFIDENTIAL"
}
```

### Response 403 example — AUTH_INSUFFICIENT_ROLE

```json
{
  "statusCode": 403,
  "message": "Request principal could not be resolved",
  "error": "AUTH_INSUFFICIENT_ROLE"
}
```

### Response 403 example — IDENTITY_COLLEAGUE_REQUIRED

```json
{
  "statusCode": 403,
  "message": "An active colleague membership is required",
  "error": "IDENTITY_COLLEAGUE_REQUIRED"
}
```

### Response 403 example — AUTH_SOURCE_OF_RECORD_REQUIRED

```json
{
  "statusCode": 403,
  "message": "API client is not the source of record for this data domain in this tenant",
  "error": "AUTH_SOURCE_OF_RECORD_REQUIRED"
}
```

### Response 403 example — AUTH_TENANT_NOT_GRANTED

```json
{
  "statusCode": 403,
  "message": "API client is not granted access to this tenant",
  "error": "AUTH_TENANT_NOT_GRANTED"
}
```

### Response 403 example — AUTH_SERVICE_MEMBERSHIP_MISSING

```json
{
  "statusCode": 403,
  "message": "API client has no active service membership in this tenant",
  "error": "AUTH_SERVICE_MEMBERSHIP_MISSING"
}
```

### Response 403 example — PRINCIPAL_TYPE_NOT_ALLOWED

```json
{
  "statusCode": 403,
  "message": "API client is not permitted to call this operation",
  "error": "PRINCIPAL_TYPE_NOT_ALLOWED"
}
```

### Response 404 example — MEMBER_NOT_IN_TENANT

```json
{
  "statusCode": 404,
  "message": "One or more individuals not found in tenant",
  "error": "MEMBER_NOT_IN_TENANT"
}
```

### Response 404 example — AUTH_ON_BEHALF_PERSON_NOT_AVAILABLE

```json
{
  "statusCode": 404,
  "message": "The named person is not available for this operation",
  "error": "AUTH_ON_BEHALF_PERSON_NOT_AVAILABLE"
}
```

### Response 409 example — PARTNER_TEAM_REFERENCE_CONFLICT

```json
{
  "statusCode": 409,
  "message": "This API client already holds this external team reference",
  "error": "PARTNER_TEAM_REFERENCE_CONFLICT"
}
```

### Response 409 example — IDEMPOTENCY_KEY_REUSED

```json
{
  "statusCode": 409,
  "message": "This Idempotency-Key was already used for a different request",
  "error": "IDEMPOTENCY_KEY_REUSED"
}
```

### Response 409 example — IDEMPOTENCY_REQUEST_IN_PROGRESS

```json
{
  "statusCode": 409,
  "message": "An equivalent request is already in progress",
  "error": "IDEMPOTENCY_REQUEST_IN_PROGRESS"
}
```

### Response 422 example — IMPLICIT_TEAM_NOT_EDITABLE

```json
{
  "statusCode": 422,
  "message": "Manager-derived teams cannot be edited through the explicit team surface; change the manager relationship instead",
  "error": "IMPLICIT_TEAM_NOT_EDITABLE"
}
```

### Response 422 example — TEAM_OWNER_DIRECTORY_HIDDEN

```json
{
  "statusCode": 422,
  "message": "Reveal this colleague before making them a team owner.",
  "error": "TEAM_OWNER_DIRECTORY_HIDDEN"
}
```

### Response 422 example — TEAM_OWNER_CONFIDENTIAL

```json
{
  "statusCode": 422,
  "message": "End confidentiality before making this person a team owner.",
  "error": "TEAM_OWNER_CONFIDENTIAL"
}
```

### Response 429 example

```json
{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests",
  "error": "HTTP_TOO_MANY_REQUESTS"
}
```
