> ## Documentation Index
> Fetch the complete documentation index at: https://docs.proconvey.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating a Case

> How to create a case, with guidance on building the clients payload.

A case is created by `POST`ing to the [Create a new case](/api-reference/cases/create-a-new-case) endpoint. See the [API reference](/api-reference/cases/create-a-new-case) for the full schema.

The information below explains in detail the requirements for the `clients` array in the request body.

<Tip>
  Refer to the [`clients` body parameter](/api-reference/cases/create-a-new-case#body-clients) in the API reference for the full schema. This guide explains the conditional requirements that apply on top of it.
</Tip>

## Client identity

Each client must be provided in **exactly one** of the following forms. Do not mix fields from both options.

<Tabs>
  <Tab title="Option A — Existing client by ID">
    Reference an existing client by their unique identifier. No other identity fields should be included.

    ```json theme={null}
    { "clientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
    ```

    <Tip>
      You can retrieve client IDs from the [List clients](/api-reference/clients/list-clients) endpoint.
    </Tip>
  </Tab>

  <Tab title="Option B — New client by details">
    Provide full details to create a new client inline. All three fields are required.

    ```json theme={null}
    {
      "firstName": "Jane",
      "lastName": "Smith",
      "emailAddress": "jane.smith@example.com"
    }
    ```
  </Tab>
</Tabs>

<Warning>
  If `clientId` is supplied, do not include `firstName`, `lastName`, or `emailAddress`. Mixing fields from both options will return a validation error.
</Warning>

***

## ID & AML checks

Setting `idAndAmlCheck: true` requires a `checkProvider`. Each provider then has its own field requirements and restrictions.

### Provider requirements matrix

Legend: ✅ required · ⚪ optional · ❌ not allowed

| Field                                           | `yoti` | `thirdfort` | `title-guardian` |
| ----------------------------------------------- | :----: | :---------: | :--------------: |
| `checkProvider`                                 |    ✅   |      ✅      |         ✅        |
| `telephoneNumber` (E.164, e.g. `+447700900123`) |    ⚪   |      ✅      |         ✅        |
| `interestedPartyType`                           |    ⚪   |      ⚪      |         ✅        |
| `sofType`                                       |    ❌   |      ⚪      |         ⚪        |

<Note>
  `telephoneNumber` is always optional on the client itself, but becomes required as soon as Thirdfort or Title Guardian is selected as the check provider.
</Note>

### Example

```json theme={null}
{
  "idAndAmlCheck": true,
  "checkProvider": "title-guardian",
  "telephoneNumber": "+447700900123",
  "interestedPartyType": "borrower"
}
```

***

## Source of Funds

### Questionnaire

If `questionnaire: true`, you must provide `sofType`.

| Field     | Allowed values            | Required when         |
| --------- | ------------------------- | --------------------- |
| `sofType` | `"purchaser"`, `"giftor"` | `questionnaire: true` |

<Warning>
  `sofType` cannot be combined with `checkProvider: "yoti"`.
</Warning>

### Armalytix provider

When `sofProvider: "armalytix"`, additional fields are required. Some are conditional on the value of `armalytixCheckType`.

#### Always required with Armalytix

| Field                    | Allowed values                                                                                       |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `armalytixCheckType`     | `RESIDENTIAL_PROPERTY_PURCHASE`, `COMPANY_PROPERTY_PURCHASE`, `STANDARD`, `GIFTOR`, `SOF_REFRESH`    |
| `armalytixBankDataRange` | `6_MONTHS`, `9_MONTHS`, `1_YEAR`, `1_YEAR_3_MONTHS`, `1_YEAR_6_MONTHS`, `1_YEAR_9_MONTHS`, `2_YEARS` |

#### Conditional on `armalytixCheckType`

Legend: ✅ required · ⚪ optional

| Field                                                | `RESIDENTIAL_PROPERTY_PURCHASE` | `COMPANY_PROPERTY_PURCHASE` | `STANDARD` | `GIFTOR` | `SOF_REFRESH` |
| ---------------------------------------------------- | :-----------------------------: | :-------------------------: | :--------: | :------: | :-----------: |
| `armalytixAmountToProve`                             |                ✅                |              ✅              |      ✅     |     ✅    |       ⚪       |
| `armalytixBusinessName`                              |                ⚪                |              ✅              |      ⚪     |     ⚪    |       ⚪       |
| `armalytixMatterDescription` (gift recipient's name) |                ⚪                |              ⚪              |      ⚪     |     ✅    |       ⚪       |

***

## Optional fields reference

<AccordionGroup>
  <Accordion title="Identity & contact">
    | Field             | Type   | Notes                                                 |
    | ----------------- | ------ | ----------------------------------------------------- |
    | `title`           | string | Client title                                          |
    | `telephoneNumber` | string | E.164 format. Required for some providers — see above |
    | `companyName`     | string |                                                       |
  </Accordion>

  <Accordion title="Checks & verification">
    | Field                 | Type                                            | Notes                                               |
    | --------------------- | ----------------------------------------------- | --------------------------------------------------- |
    | `idAndAmlCheck`       | boolean                                         | Triggers requirement for `checkProvider`            |
    | `checkProvider`       | `"yoti"` \| `"thirdfort"` \| `"title-guardian"` | Required when `idAndAmlCheck: true`                 |
    | `idCheckType`         | `"standard"` \| `"original"`                    |                                                     |
    | `interestedPartyType` | string                                          | Required when `checkProvider` is `"title-guardian"` |
    | `ongoing`             | boolean                                         |                                                     |
    | `international`       | boolean                                         |                                                     |
    | `poa`                 | boolean                                         | Power of attorney                                   |
    | `poo`                 | boolean                                         | Proof of ownership                                  |
  </Accordion>

  <Accordion title="Source of Funds">
    | Field                 | Type                                         | Notes                                                     |
    | --------------------- | -------------------------------------------- | --------------------------------------------------------- |
    | `verificationOfFunds` | boolean                                      |                                                           |
    | `questionnaire`       | boolean                                      | Triggers requirement for `sofType`                        |
    | `sofType`             | `"purchaser"` \| `"giftor"`                  | Cannot be used with `checkProvider: "yoti"`               |
    | `sofProvider`         | `"upload"` \| `"thirdfort"` \| `"armalytix"` | Armalytix triggers additional required fields — see above |
    | `isGiftorOnly`        | boolean                                      |                                                           |
  </Accordion>

  <Accordion title="Communications & documents">
    | Field                 | Type    | Notes |
    | --------------------- | ------- | ----- |
    | `smsInvite`           | boolean |       |
    | `onboardingLetters`   | boolean |       |
    | `instructionLetters`  | boolean |       |
    | `statements`          | boolean |       |
    | `customLetterContent` | string  |       |
  </Accordion>

  <Accordion title="Other">
    | Field      | Type   | Notes |
    | ---------- | ------ | ----- |
    | `tenantId` | string |       |
  </Accordion>
</AccordionGroup>