# createColleague

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

## Operation

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

| Field | Value |
|---|---|
| operationId | createColleague |
| method | POST |
| server | https://staging-api.thomas.co |
| path | /v1/colleagues |
| tags | `People Administration` |
| summary | Create a colleague profile |
| badges | `{"name":"Admin"}`, `{"name":"Owner"}`, `{"name":"Partner scope: users:w"}` |
| scopes | `users:w` |

## Description

Create a single colleague profile by email. Returns 201 on creation, 200 with reactivation offer for archived profiles, 409 for duplicates. A Partner API client that is the tenant's active `users` source of record calls the same operation, supplying `partnerReference`, `sourceVersion` and optionally `hrisId`, `firstName`, `lastName`, `department`, `jobTitle` and `location` — the employee fields it masters. It may not send `personalEmail`; a human may not send `partnerReference`, `sourceVersion`, `hrisId` or a `null` work detail. Each is rejected with a 400, and the role may never be supplied by either. For the Partner, absent fields are left unchanged, `null` clears `department`, `jobTitle` or `location`, names must be non-blank, and `hrisId` is stored (it cannot be cleared); an `hrisId` another employee already holds is refused with IDENTITY_RESOLUTION_CONFLICT. Names are this organisation’s own name for the person: they are written here even when the person also belongs to another organisation, whose name for them is unchanged, and `namesNotApplied` is never set. The optional `Idempotency-Key` and `sourceVersion` answer DIFFERENT questions and compose: the key de-duplicates a REQUEST ("have I already executed this?"), `sourceVersion` orders assertions about the RECORD ("is this the newest state of this record?"). The key is decided first: repeating a settled key returns the original response verbatim without evaluating `sourceVersion` at all, and reusing it for different asserted data is refused with 409 IDEMPOTENCY_KEY_REUSED. Without a key — or with one that has not settled — `sourceVersion` applies exactly as it always did. A STALE-version refusal is never retained as a replayable answer: it depends on a version a later write advances, so retrying the same key once the version is correct is re-evaluated against current state and can succeed. `sourceVersion` is not part of the key fingerprint for that reason. For that Partner caller only, an `email` or `hrisId` resolving to an employee the tenant ALREADY has returns 200 with `classification: "reconciled"`: the reference is linked to that existing colleague, whose role, membership and creator provenance are all preserved, and nothing new is created. A human caller never receives that classification — a human create resolving to an existing active employee is still a 409 duplicate. For that Partner caller, `sourceVersion` is ORDERED per employee within the calling API client, which is what makes retrying safe: a higher version applies and is returned through the read path; the same version asserting the same data is an idempotent replay that answers exactly as the first request did and changes nothing; a lower version is refused as stale; and the same version asserting different data is refused as a version conflict. "The same data" means the whole request body apart from `sourceVersion` itself — `email` (compared lower-cased), `hrisId`, `partnerReference` and the mastered fields. A higher version applies the mastered fields — on an employee the tenant already had, the Partner’s values overwrite, while its role, membership source and creator provenance are preserved. Version histories are independent per Tenant and per API client, and are SHARED per employee with `POST /v1/colleagues/bulk`, `PATCH /v1/colleagues/{id}`, `POST /v1/colleagues/{id}/reactivate`, `DELETE /v1/colleagues/{id}/pending-change`, `POST /v1/colleagues/{id}/archive`, `POST /v1/colleagues/bulk/archive`, `POST /v1/colleagues/{id}/restore`, `POST /v1/colleagues/bulk/set-department`, `POST /v1/colleagues/bulk/set-location`, `POST /v1/memberships` and `PATCH /v1/memberships/{id}`, so an older write on any of them is stale against a newer one on another; each operation fingerprints its own body, so one version cannot be reused across operations.

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

## Responses

| Status | Description | Schema refs |
|---|---|---|
| 200 | Archived profile found — reactivation offer returned (classification: "reactivate"); or, for a Partner API client, the existing colleague its reference was linked to (classification: "reconciled") | #/components/schemas/ReactivateColleagueOfferDto, #/components/schemas/ReconciledColleagueResponseDto |
| 201 | Colleague profile created successfully (classification: "created") | #/components/schemas/CreatedColleagueResponseDto |
| 400 | Validation error in request body. 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 (AUTH_TOKEN_INVALID) | #/components/schemas/ApiErrorResponseDto |
| 403 | Insufficient role — admin or owner required (AUTH_INSUFFICIENT_ROLE); for an API client, no active Grant carrying `users:w` on this tenant (AUTH_TENANT_NOT_GRANTED) or not the tenant's active `users` source of record (AUTH_SOURCE_OF_RECORD_REQUIRED). An API client is refused before any tenant data is read or changed when its service membership is absent (AUTH_SERVICE_MEMBERSHIP_MISSING), or when the operation is not published to its principal kind (PRINCIPAL_TYPE_NOT_ALLOWED). An API client holds no organisation role, so AUTH_INSUFFICIENT_ROLE never applies to it. | #/components/schemas/ApiErrorResponseDto |
| 404 | The named acting person is unavailable. | #/components/schemas/ApiErrorResponseDto |
| 409 | Already holds a current relationship in this tenant — employee, former employee or candidate (DUPLICATE_EMAIL); for an API client that can read candidates (its Grant holds `users:r` and the tenant’s tier includes Candidates), a candidate is instead answered: the person is a candidate in this tenant, so convert them with `POST /v1/candidates/{id}/convert` using `details.candidateId` instead of creating an employee (IDENTITY_CANDIDATE_CONVERSION_REQUIRED); any other API client gets DUPLICATE_EMAIL for a candidate, with no `details`; the supplied reference, email and `hrisId` do not all name the same person, and the message names no individual id (IDENTITY_RESOLUTION_CONFLICT); this API client already holds a different reference for that employee (PARTNER_EMPLOYEE_REFERENCE_CONFLICT); the submitted `sourceVersion` is lower than the highest already accepted for that employee, so resend above it (PARTNER_EMPLOYEE_SOURCE_VERSION_STALE); that `sourceVersion` was already accepted asserting different data (PARTNER_EMPLOYEE_SOURCE_VERSION_CONFLICT); or a connected Source-of-Record integration masters a field this creation would write (SOURCE_OF_RECORD_FIELD_MASTERED) The Idempotency-Key may also conflict with an attempt already recorded against it. | #/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 — HTTP_BAD_REQUEST

```json
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "HTTP_BAD_REQUEST",
  "details": {
    "validationIssues": [
      {
        "path": "$",
        "rule": "invalid_type"
      }
    ]
  }
}
```

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

```json
{
  "statusCode": 403,
  "message": "Insufficient role privileges",
  "error": "AUTH_INSUFFICIENT_ROLE"
}
```

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

```json
{
  "statusCode": 409,
  "message": "A colleague with this email already exists",
  "error": "DUPLICATE_EMAIL"
}
```

### Response 409 example — IDENTITY_CANDIDATE_CONVERSION_REQUIRED

```json
{
  "statusCode": 409,
  "message": "This person is a candidate in this organisation. Convert the candidate with POST /v1/candidates/{id}/convert instead of creating an employee.",
  "error": "IDENTITY_CANDIDATE_CONVERSION_REQUIRED",
  "details": {
    "candidateId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  }
}
```

### Response 409 example — SOURCE_OF_RECORD_FIELD_MASTERED

```json
{
  "statusCode": 409,
  "message": "One or more of these fields is managed by a connected source-of-record integration and cannot be edited in Thomas",
  "error": "SOURCE_OF_RECORD_FIELD_MASTERED",
  "details": {
    "dataDomain": "users",
    "refusedFields": [
      "department"
    ],
    "owningApiClientId": "3f2504e0-4f89-41d3-9a0c-0305e82c5401",
    "owningApiClientName": "Acme HRIS Connector",
    "owningPartnerId": "3f2504e0-4f89-41d3-9a0c-0305e82c5402",
    "owningPartnerName": "Acme People Systems",
    "recovery": "Acme HRIS Connector is the source of record for these fields. Disconnecting or replacing that integration in Thomas restores native editability."
  }
}
```

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

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