# personalitySelfRefresh

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

## Operation

| Method | URL |
|---|---|
| POST | https://api.thomas.co/v1/personality/self-refresh |

| Field | Value |
|---|---|
| operationId | personalitySelfRefresh |
| method | POST |
| server | https://api.thomas.co |
| path | /v1/personality/self-refresh |
| tags | `Personality` |
| summary | Create a self-refresh assignment for the acting person's own stale Personality result |
| badges | None |
| scopes | `assessments:w` |

## Description

Available once the person has a committed Personality result that is over a year old (FR40, FR71). `accessToken` is the questionnaire link (`/assess/{accessToken}`), never a session token. A Partner acting on behalf of the person receives it too, because the person is always the subject here; a keyed replay returns `{ assignmentId }` alone. On behalf of a named person (`Thomas-On-Behalf-Of`), the request is parsed and authorised as that person. Thomas emails the subject when an assignment is created or its token is rotated. A keyed replay or a request that leaves an existing assignment unchanged sends no new email. The questionnaire link (`accessToken`) is returned only for an assignment whose subject is the named person. Each new link replaces the previous one, which stops working, and the subject is emailed the new link, so keep the link you received and open it again rather than asking for another. Ask again only when it stops working, for example after the organisation sends the person a reminder. A keyed replay never returns a link.

## 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. On behalf of a named person (`Thomas-On-Behalf-Of`) the key is optional, is bound to that person as well as to the API client, and a replay NEVER carries the questionnaire link: the response is stored with `accessToken` removed, so a replay returns the original response without it. To obtain a fresh link, repeat the request under a NEW key. |
| Thomas-On-Behalf-Of | header | true | string | Act as one named person using thomas:<companyIndividualId> or partner:<partnerReference>. |
| 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. |

## Request Body

None.

## Responses

| Status | Description | Schema refs |
|---|---|---|
| 201 | The self-refresh assignment | #/components/schemas/PersonalitySelfRefreshResponseDto |
| 400 | The tenant or named-person header is absent, repeated, or malformed. 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 | A Partner is refused when its Grant does not cover the tenant, or when it calls without naming a person in `Thomas-On-Behalf-Of`: the operation has no branch for an API client on its own. Also returned when a Partner API client calls without Thomas-On-Behalf-Of. | #/components/schemas/ApiErrorResponseDto |
| 404 | The named acting person is unavailable. | #/components/schemas/ApiErrorResponseDto |
| 409 | The current Personality result is still fresh. 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 — AUTH_TENANT_CONTEXT_INVALID

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

### Response 400 example — IDEMPOTENCY_KEY_INVALID

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

### Response 401 example

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

### Response 403 example — INSUFFICIENT_TIER

```json
{
  "statusCode": 403,
  "message": "All instruments requires the Professional plan.",
  "error": "INSUFFICIENT_TIER"
}
```

### Response 403 example — PERSONALITY_SELF_ASSIGN_FORBIDDEN

```json
{
  "statusCode": 403,
  "message": "Personality first completion is assignment-gated; a self-refresh requires an existing result",
  "error": "PERSONALITY_SELF_ASSIGN_FORBIDDEN"
}
```

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

```json
{
  "statusCode": 409,
  "message": "Personality self-refresh is only available once a result is over a year old",
  "error": "PERSONALITY_REFRESH_NOT_STALE"
}
```

### 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"
}
```