Creating a Case - Pro Convey API

A case is created by POSTing to the Create a new case endpoint. See the API reference for the full schema. The information below explains in detail the requirements for the clients array in the request body.

Refer to the clients body parameter in the API reference for the full schema. This guide explains the conditional requirements that apply on top of it.

Client identity

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

Option A — Existing client by ID
Option B — New client by details

Reference an existing client by their unique identifier. No other identity fields should be included.

{ "clientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }

You can retrieve client IDs from the List clients endpoint.

Provide full details to create a new client inline. All three fields are required.

{
  "firstName": "Jane",
  "lastName": "Smith",
  "emailAddress": "jane.smith@example.com"
}

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

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`	❌	⚪	⚪

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

Example

{
  "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`

sofType cannot be combined with checkProvider: "yoti".

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

Identity & contact

Field	Type	Notes
`title`	string	Client title
`telephoneNumber`	string	E.164 format. Required for some providers — see above
`companyName`	string

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

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

Communications & documents

Field	Type	Notes
`smsInvite`	boolean
`onboardingLetters`	boolean
`instructionLetters`	boolean
`statements`	boolean
`customLetterContent`	string

Other

Field	Type	Notes
`tenantId`	string

​Client identity

​ID & AML checks

​Provider requirements matrix

​Example

​Source of Funds

​Questionnaire

​Armalytix provider

​Always required with Armalytix

​Conditional on armalytixCheckType

​Optional fields reference

Client identity

ID & AML checks

Provider requirements matrix

Example

Source of Funds

Questionnaire

Armalytix provider

Always required with Armalytix

Conditional on `armalytixCheckType`

Optional fields reference