> For the complete documentation index, see [llms.txt](https://developers.gallantreecapital.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gallantreecapital.com/resources/individuals.md). # Individuals An **individual** is a natural person — a director, guarantor, beneficial owner, shareholder, or trustee — associated with one or more of your [**organisations**](/resources/organisations.md). Individuals are always associated with at least one organisation; there are no "orphan" individual records. Before you start: read [Data model](/concepts/data-model.md). ## Read ### List individuals ```bash curl -sS -H "x-api-key: $KEY" \ "https://developers.gallantreecapital.com/api/v1/individuals?page=1&limit=50" ``` Paginated. Returns individuals owned by the lender your key resolves to. **Required scope:** `organisations:read` (individuals share the organisation scopes — see below). ## The response shape ```json { "id": "65f3...c510", "firstName": "Alex", "middleName": null, "lastName": "Sandbox", "email": "alex@example.com", "mobilePhone": "+61400000000", "dateOfBirth": "1985-04-14T00:00:00.000Z", "status": "active", "kycStatus": "verified", "organisationIds": ["65f3...c4f2", "65f3...c4f8"], "createdAt": "2026-07-14T02:11:00.000Z", "updatedAt": "2026-08-02T09:42:11.000Z" } ``` Fields worth calling out: | Field | Notes | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`status`** | `pending` (created via external system, awaiting review), `active` (verified in the platform), `deleted` (soft-deleted; references still resolve). | | **`kycStatus`** | Compliance traffic light — same seven values as KYB. See below. | | **`organisationIds[]`** | Every organisation this person is associated with. The role for each association (director, guarantor, etc.) is stored on the underlying `organisationAssociations[]` field but flattened to ids in the read DTO — fetch the association detail from the platform if you need it. | | **`dateOfBirth`** | ISO 8601. PII — handle per your integration's data-handling policy. | | **`email`** / **`mobilePhone`** | PII. | ## KYC status `kycStatus` uses the same seven values as `kybStatus` on organisations: | Value | Meaning | | ------------- | ----------------------------------------------------------------------- | | `not_started` | No KYC verification has begun. | | `in_progress` | Verification is in progress or awaits review. | | `verified` | Verified and within the validity window. | | `expiring` | Verified but the validity window is closing (within 30 days). | | `expired` | Verified once, but validity window has passed — re-verification needed. | | `refused` | Verification concluded in refusal. | | `blocked` | Manually blocked from further verification attempts. | `null` means the record predates the compliance surface (no verification workflow was ever created against it). ## Roles (in the organisation association) When an individual is linked to an organisation, the link carries a **role**. Common values: * `director` — company director * `companySecretary` * `officeholder` * `guarantor` — personal guarantor on a loan * `shareholder` / `beneficialOwner` — ownership stake * `unitholder` / `beneficiary` * `trustee` — of a trust (personal capacity — trustee *companies* are Organisations with the `trustee` role, not individuals) * `settlor` / `appointor` — of a trust * `accountant` * `employee` A single individual can be linked to multiple organisations with different roles per link — e.g. a director of one borrower company and a guarantor on another. ## Create ``` POST /api/v1/individuals x-api-key: Idempotency-Key: Content-Type: application/json { "firstName": "Alex", "lastName": "Sandbox", "email": "alex@example.com", "mobilePhone": "+61400000000", "dateOfBirth": "1985-04-14", "status": "active", "organisationAssociations": [ { "organisation": "65f3...c4f2", "role": "director", "designation": "Managing Director" } ] } ``` **Required scope:** `organisations:write`. **Yes — individuals share the organisation write scope.** There's no separate `individuals:write` scope today, since individuals and organisations are managed together from a compliance/onboarding perspective. **Idempotency-Key header:** required. See [Idempotency](/guides/idempotency.md). **`organisationAssociations` is required — minimum one.** An individual cannot exist without at least one organisation link. ### Restrictions on organisation associations The API rejects associations pointing at organisations with certain "platform-side" roles — they exist for admin purposes and don't have individuals attached through this surface. Blocked roles: * `trustee` * `securityTrustee` * `servicer` * `arranger` Attempting to associate an individual with an organisation carrying any of those roles returns `400` with a message like `"Individuals cannot be associated with this organisation type"`. If you need a director/officer of a trustee company on your record, model it as a separate borrower-side organisation and associate the individual there. ### Response ```json { "id": "65f3...c510", "status": "active", ... } ``` `201 Created` on success. The response is the freshly-created `V1IndividualDto`. ### Errors | Status | When | | ------ | ------------------------------------------------------------------------------------------------------ | | `400` | Body validation failed, or the association points at a restricted org role | | `403` | Insufficient scope, **or** any `organisationAssociations[i].organisation` id belongs to another tenant | | `409` | Idempotency-Key conflict | | `422` | Semantically invalid — e.g. `dateOfBirth` in the future | The `403` on cross-tenant associations is deliberate: the endpoint validates that every organisation id you reference belongs to *your* lender before it creates the individual, and rejects the whole request if any check fails. ## Update A `PUT /api/v1/individuals/{id}` isn't exposed on the v1 surface today. To adjust a person's data — new email, new mobile, adding an association — use the platform's UI. Field-by-field updatability on the public surface is scheduled for a later phase. ## Delete Not exposed. Individuals are soft-deleted (`status: "deleted"`) via the platform; their id continues to resolve for audit purposes. ## PII handling Every field on the DTO except `id`, `status`, `kycStatus`, `organisationIds`, `createdAt`, and `updatedAt` is Personally Identifiable Information. Handling recommendations: * **Don't log the full DTO** — log the `id` alone; fetch fields lazily when you actually need them. * **Don't cache PII beyond your integration's data-handling policy** — always fetch fresh when consent or retention requirements apply. * **Redact in error messages** — if your integration exposes API errors to end users, ensure the failed-request payload isn't included verbatim. The public API returns PII directly because your integration has a legitimate need for it, not because it's safe to fan out. ## What to do next * [**Organisations**](/resources/organisations.md) — the counterparty side. * Reacting to KYC completion: `organisation.kyb_completed` fires when an *organisation's* KYB completes; there is no separate `individual.kyc_completed` event on the v1 surface yet. Watch the KYB event and re-fetch associated individuals. * Full field list: [**API reference**](/reference/openapi.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.gallantreecapital.com/resources/individuals.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.