# Supply a User's Eligibility

> Coming soon, upon request — this feature is turned on for your tenant by the Aurea team. [Contact us](https://www.aureahub.com/contact)

Your tenant, as the authorised entity, supplies one or more items of a user's eligibility.

## Overview

- Send any of `residence` (country, and region where a region of the country is excluded), `usPerson` (the Regulation S declaration), `classification` (`retail` or `professional` client) and `appropriateness` (the appropriateness test's outcome); each one sent replaces that item's current value, and the earlier value is kept. Every item needs when it was declared or assessed (ISO 8601 with its offset, never in the future) and its `source` in your own words (for example `kyc`, `self_declaration`, `mifid_classification`, `appropriateness_test`); `reference` is your own, optional.
- `residence.subdivision` (ISO 3166-2) is needed only where a region of the country is excluded: without it, [Requirements](https://docs.aureahub.com/docs/tok-requirements.md) lists `residence_subdivision` as missing.
- `usPerson.isUsPerson`: `false` when the user declared not to be a US person (Regulation S, Rule 902) nor to act for one.
- What counts is the value written last, not the latest date declared. Every value written is kept, with who wrote it and when; the routes answer the current one. `userId` must be a user of your tenant.
- Answers the user's eligibility as [A User's Eligibility](https://docs.aureahub.com/docs/tok-user-eligibility-get.md) reads it. `isTestnet` only picks the environment whose tokenized assets your tenant has set up: the eligibility is the user's in both.
- User token of one of your tenant's administrators — `owner`, `tenantadmin` or `non_signing_admin` — and the tenant signature ([Calling the Routes](https://docs.aureahub.com/docs/guide-tokenized-assets.md)). Any other role: `403` `Tenant admin access required. Your role does not have permission to perform this action.`

## Errors

Besides [the answers every tokenized assets route can give](https://docs.aureahub.com/docs/guide-tokenized-assets.md) (no valid token or signature, the module not set up or not switched on, a field that does not fit):

| Status | details.code | When |
| --- | --- | --- |
| 403 | — | Not one of your tenant's administrators (`Tenant admin access required. Your role does not have permission to perform this action.`). |
| 404 | TOKENIZED_ASSETS_USER_NOT_FOUND | `userId` is not a user of your tenant (`There is no such user in this tenant.`, with `details.userId`). |
| 400 | TOKENIZED_ASSETS_ELIGIBILITY_INVALID | In this order: `residence.country must be a country's ISO 3166-1 alpha-2 code`; `residence.subdivision must be an ISO 3166-2 region of residence.country`; `<field> must be a date and time (ISO 8601)`; `<field> is in the future` (more than five minutes ahead); `Supply at least one of residence, usPerson, classification and appropriateness`. |

## Endpoint

### `PATCH /v1/tokenized-assets/users/{userId}/eligibility`

Authentication: bearer token required.

Supplies items of a user's eligibility.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | string | yes | A UUID. |

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `isTestnet` | boolean | no | The environment whose tokenized assets your tenant has set up; the eligibility is the user's in both. |
| `residence` | object | no | Where the user lives. |
| `residence.country` | string | no | ISO 3166-1 alpha-2. Pattern `^[A-Z]{2}$`. Required in `residence`. |
| `residence.subdivision` | string \| null | no | ISO 3166-2, when known: required where a region of the country is excluded. Pattern `^[A-Z]{2}-[A-Z0-9]{1,3}$`. |
| `residence.declaredAt` | string | no | ISO 8601, with its offset. Required in `residence`. |
| `residence.source` | string | no | Where it comes from, in the tenant's words: for example kyc, self_declaration, mifid_classification, appropriateness_test. Pattern `^[a-z][a-z0-9_]{0,63}$`. Required in `residence`. |
| `residence.reference` | string \| null | no | The tenant's own reference for it. 1 to 128 characters. |
| `usPerson` | object | no | The user's Regulation S declaration. |
| `usPerson.isUsPerson` | boolean | no | The Regulation S declaration: false when the user declared not to be a "US person" (Rule 902) nor acting for one. Required in `usPerson`. |
| `usPerson.declaredAt` | string | no | ISO 8601, with its offset. Required in `usPerson`. |
| `usPerson.source` | string | no | Where it comes from, in the tenant's words: for example kyc, self_declaration, mifid_classification, appropriateness_test. Pattern `^[a-z][a-z0-9_]{0,63}$`. Required in `usPerson`. |
| `usPerson.reference` | string \| null | no | The tenant's own reference for it. 1 to 128 characters. |
| `classification` | object | no | The client's classification. |
| `classification.investorClass` | string | no | One of `retail`, `professional`. Required in `classification`. |
| `classification.assessedAt` | string | no | ISO 8601, with its offset. Required in `classification`. |
| `classification.source` | string | no | Where it comes from, in the tenant's words: for example kyc, self_declaration, mifid_classification, appropriateness_test. Pattern `^[a-z][a-z0-9_]{0,63}$`. Required in `classification`. |
| `classification.reference` | string \| null | no | The tenant's own reference for it. 1 to 128 characters. |
| `appropriateness` | object | no | The appropriateness test's outcome. |
| `appropriateness.outcome` | string | no | One of `appropriate`, `not_appropriate`. Required in `appropriateness`. |
| `appropriateness.assessedAt` | string | no | ISO 8601, with its offset. Required in `appropriateness`. |
| `appropriateness.source` | string | no | Where it comes from, in the tenant's words: for example kyc, self_declaration, mifid_classification, appropriateness_test. Pattern `^[a-z][a-z0-9_]{0,63}$`. Required in `appropriateness`. |
| `appropriateness.reference` | string \| null | no | The tenant's own reference for it. 1 to 128 characters. |

**Responses**

`200` OK

```json
{
  "userId": "3f6b2d18-0c7e-4a91-b5d3-8e2f7a1c9d64",
  "residence": {
    "country": "IT",
    "subdivision": null,
    "declaredAt": "2026-09-30T10:12:00.000Z",
    "source": "kyc",
    "suppliedAt": "2026-10-01T08:00:02.000Z",
    "reference": "KYC-2026-08812",
    "suppliedBy": "9a4c1e72-5b3d-4f08-8e6a-2c7d1b9f0e35",
    "suppliedByRole": "tenantadmin"
  },
  "usPerson": {
    "isUsPerson": false,
    "declaredAt": "2026-09-30T10:12:00.000Z",
    "source": "self_declaration",
    "suppliedAt": "2026-10-01T08:00:02.000Z",
    "reference": null,
    "suppliedBy": "9a4c1e72-5b3d-4f08-8e6a-2c7d1b9f0e35",
    "suppliedByRole": "tenantadmin"
  },
  "classification": {
    "investorClass": "retail",
    "assessedAt": "2026-09-30T10:20:00.000Z",
    "source": "mifid_classification",
    "suppliedAt": "2026-10-01T08:00:02.000Z",
    "reference": null,
    "suppliedBy": "9a4c1e72-5b3d-4f08-8e6a-2c7d1b9f0e35",
    "suppliedByRole": "tenantadmin"
  },
  "appropriateness": {
    "outcome": "appropriate",
    "assessedAt": "2026-10-07T09:41:00.000Z",
    "source": "appropriateness_test",
    "suppliedAt": "2026-10-07T09:41:05.000Z",
    "reference": "AT-551",
    "suppliedBy": "9a4c1e72-5b3d-4f08-8e6a-2c7d1b9f0e35",
    "suppliedByRole": "tenantadmin"
  }
}
```

`400` Invalid

```json
{
  "statusCode": 400,
  "error": "BadRequestError",
  "message": "appropriateness.assessedAt is in the future",
  "details": {
    "code": "TOKENIZED_ASSETS_ELIGIBILITY_INVALID"
  }
}
```

[Contact us for details](https://www.aureahub.com/contact).

---

Web version: https://docs.aureahub.com/#tok-user-eligibility-supply