This guide outlines the list of validation rules used in the Create a lead and Update significant persons endpoints. When any of the below validation rules are breached, the API returns a 422 response alongside a json body that contains information on the breached rule(s).

The error response when validation fails on any given property follows the structure below:

{
    "PropertyNameThatFailedValidation": [
        "message for first rule that failed",
        "message for second rule that failed",
        ...
        "message for n(th) rule that failed",
    ]
}

📘
Good to know: In the example error messages in the tables below, all messages for all the rules have been added (as if all rules were broken at once). When interacting with YouLend's API, you will only receive the error messages for the actually broken rules.

Create a lead

API reference for creating a new lead

Update significant persons

API reference for updating significant persons on a lead

Create a lead validation

The following table lists each property in the Create a lead request body, its validation rules, and the error messages returned when validation fails.

Property	Required	Description
`ThirdPartyCustomerId`	Yes	Your unique customer identifier (max 50 alphanumeric characters)
`CountryISOCode`	Yes	ISO 3166 country code
`LoanCurrencyISOCode`	Yes	Currency code: `GBP`, `EUR`, `DKK`, `PLN`, or `USD`
`KeyContactName`	Yes	Primary contact name (max 255 characters)
`CompanyType`	Yes	Company legal structure (e.g., `soleTrader`, `limitedCompany`)
`CompanyName`	Yes	Registered company name (2–255 characters)
`CompanyWebsite`	No	Company URL (max 1000 characters)
`TradingName`	No	Trading or brand name (1–200 characters)
`CompanyNumber`	Conditional	Company registration number (format varies by country)
`VatNumber`	No	VAT registration number (6–14 alphanumeric characters)
`Mid`	No	Merchant ID (min 7 alphanumeric characters)
`MerchantIds`	No	List of merchant IDs (alternative to `Mid`)
`ContactPhoneNumber`	No	Phone number (8–20 characters)
`ContactEmailAddress`	No	Email address (max 255 characters)
`SignupClientIp`	USA only	Client IP address
`EmployerIdentificationNumber`	USA only	EIN in `XX-XXXXXXX` format (non-sole traders)

ThirdPartyCustomerId

Validation rules:

Not empty
Max length of 50 characters
Matches regex: ^[a-zA-Z0-9_\.-]{1,50}

Error response:

{
  "ThirdPartyCustomerId": [
    "'Third Party Customer Id' must not be empty.",
    "The third party customer id is invalid."
  ]
}

CountryISOCode

Validation rules:

Not empty
Must be a valid ISO 3166 country code — see the Country ISO Codes Reference for the full list of supported countries

Error response:

{
  "$.countryISOCode": [
    "The JSON value could not be converted to YL.Web.Api.ThirdParty.Onboarding.Models.CountryCodes. Path: $.countryISOCode | LineNumber: 4 | BytePositionInLine: 28."
  ]
}

LoanCurrencyISOCode

Validation rules:

Not empty
One of "GBP", "EUR", "DKK", "PLN", "USD"

Error response:

{
  "LoanCurrencyISOCode": [
    "'Loan Currency ISO Code' must not be empty.",
    "The loan currency code is invalid. It must be an ISO 4217 currency code. Valid codes are GBP, EUR and DKK"
  ]
}

KeyContactName

Validation rules:

Not empty
Max length: 255 characters

Error response:

{
  "KeyContactName": [
    "'Key Contact Name' must not be empty."
  ]
}

CompanyType

Validation rules:

Not empty
Must be a valid company type — see the Company Type for allowed value by country (e.g., soleTrader, limitedCompany, etc.)

Error response:

{
  "$.companyType": [
    "The JSON value could not be converted to YL.Web.Api.ThirdParty.Onboarding.Models.CompanyTypes. Path: $.companyType | LineNumber: 7 | BytePositionInLine: 26."
  ]
}

CompanyName

Validation rules:

Not empty
Minimum length: 2 characters
Maximum length: 255 characters
Alphanumeric and special characters only (regex allows letters, digits, spaces, hyphens, accents, and common punctuation)

Error response:

{
  "CompanyName": [
    "'Company Name' must not be empty.",
    "The company name is invalid.",
    "The length of 'Company Name' must be at least 2 characters. You entered 1 characters.",
    "The length of 'Company Name' must be 255 characters or fewer. You entered 300 characters."
  ]
}

CompanyWebsite

Validation rules:

Maximum length: 1000 characters
Must be a valid URL format (matches regex: ^[a-zA-Z0-9:/-]{2,50}\.[a-zA-Z0-9@:%_+.~#?&/=-])

Error response:

{
  "CompanyWebsite": [
    "The company website is invalid.",
    "The length of 'Company Website' must be 1000 characters or fewer. You entered 1200 characters."
  ]
}

TradingName

Validation rules:

Minimum length: 1 character
Maximum length: 200 characters

Error response:

{
  "TradingName": [
    "The length of 'Trading Name' must be at least 1 characters. You entered 0 characters.",
    "The length of 'Trading Name' must be 200 characters or fewer. You entered 261 characters."
  ]
}

CompanyNumber

Validation rules (vary by country):

Ireland (IRL): Min length 4, max length 10, matches ^[a-zA-Z0-9].*
France (FRA): Matches ^\d{9}
All other countries (except USA): Min length 6, max length 10, matches ^[a-zA-Z0-9].*

Error response:

{
  "CompanyNumber": [
    "The length of 'Company Number' must be at least 4 characters. You entered 3 characters.",
    "The length of 'Company Number' must be 10 characters or fewer. You entered 21 characters.",
    "The company number is invalid."
  ]
}

VatNumber

Validation rules:

Minimum length: 6
Maximum length: 14
Matches regex: ^[a-zA-Z0-9].*

Error response:

{
  "VatNumber": [
    "The length of 'Vat Number' must be at least 6 characters. You entered 3 characters.",
    "The length of 'Vat Number' must be 14 characters or fewer. You entered 261 characters.",
    "The vat number is invalid."
  ]
}

Mid

Validation rules:

Matches regex: ^[a-zA-Z0-9]{7,} (at least 7 alphanumeric characters)
Cannot be used together with MerchantIds — use one or the other

Error response:

{
  "Mid": [
    "The mid is invalid. Acceptable MIDs must contain at least 7 alpha-numeric characters.",
    "You can only use one way of specifying MerchantIds."
  ]
}

MerchantIds

Validation rules:

Matches regex: ^[a-zA-Z0-9]{7,} (at least 7 alphanumeric characters per ID)
Cannot be used together with Mid — use one or the other

Error response:

{
  "MerchantIds": [
    "You can only use one way of specifying MerchantIds.",
    "The mid is invalid. Acceptable MIDs must contain at least 7 alpha-numeric characters."
  ]
}

ContactPhoneNumber

Validation rules:

Minimum length: 8
Maximum length: 20
Matches regex: ^[+0-9].*

Error response:

{
  "ContactPhoneNumber": [
    "The length of 'Contact Phone Number' must be 20 characters or fewer. You entered 49 characters.",
    "The company contact phone number is invalid."
  ]
}

ContactEmailAddress

Validation rules:

Maximum length: 255
Must contain exactly one @ symbol (ASP.NET Core compatible email validation)

Error response:

{
  "ContactEmailAddress": [
    "The length of 'Contact Email Address' must be 255 characters or fewer. You entered 540 characters.",
    "'Contact Email Address' is not a valid email address."
  ]
}

SignupClientIp

Validation rules:

Required when CountryISOCode is USA
Must be a valid IP address

Error response:

{
  "SignupClientIp": [
    "Signup Client Ip is invalid",
    "Signup Client Ip cannot be empty"
  ]
}

EmployerIdentificationNumber

Validation rules:

Required when CountryISOCode is USA and CompanyType is not soleTrader
Matches regex: ^\d{2}-\d{7} (format: XX-XXXXXXX)

Error response:

{
  "EmployerIdentificationNumber": [
    "Employer Identification Number is invalid",
    "Employer Identification Number cannot be empty"
  ]
}

Update significant persons validation

The following table lists each property in the Update significant persons request body, its validation rules, and the error messages returned when validation fails.

Property	Required	Description
`FirstName`	Yes	Person's first name (max 255 characters)
`Surname`	Yes	Person's surname (max 255 characters)
`TypeOfPerson`	Yes	Role type (see `typeOfPerson` enums)
`DateOfBirth`	Yes	Must be at least 18 years old
`Nationality`	No	Person's nationality
`NI Number`	No	Person's NI number
`Line1`, `City`, `AreaCode`, `Country`	Yes	Required address fields (max 255 characters each)
`Line2`, `Line3`, `Region`	No	Optional address fields (max 255 characters each)

Supported characters for significant person text fields

The FirstName, Surname, Nationality, and NI Number fields support the following characters:

Letters: a-z, A-Z
Extended Latin characters: Latin-1 Supplement, Latin Extended-A, Latin Extended-B, and Latin Extended Additional

Special characters:

- ´ ' ' , . @ & ¿ ? ¡ ! " " £ $ % ^ * _ : ; # + = ( ) \ / `

FirstName

Validation rules:

Not empty
Max length: 255 characters
Supports the significant person text field characters listed above

Error response:

{
  "SignificantPersons[0].FirstName": [
    "'First Name' must not be empty.",
    "The length of 'First Name' must be 255 characters or fewer. You entered 1501 characters."
  ]
}

Surname

Validation rules:

Not empty
Max length: 255 characters
Supports the significant person text field characters listed above

Error response:

{
  "SignificantPersons[0].Surname": [
    "'Surname' must not be empty.",
    "The specified condition was not met for 'Surname'.",
    "The length of 'Surname' must be 255 characters or fewer. You entered 1501 characters."
  ]
}

TypeOfPerson

Validation rules:

Not empty
Must be a valid person type — see the typeOfPerson enums for allowed values.

Error response:

{
  "$.significantPersons[0].typeOfPerson": [
    "The JSON value could not be converted to YL.Web.Api.ThirdParty.Onboarding.Models.SignificantPersonTypes. Path: $.significantPersons[0].typeOfPerson | LineNumber: 5 | BytePositionInLine: 39."
  ]
}

DateOfBirth

Validation rules:

The person must be at least 18 years old based on the provided date

Error response:

{
  "SignificantPersons[0].DateOfBirth.Year": [
    "'Year' must be less than or equal to '2006'."
  ]
}

Line1, City, AreaCode, Country

Validation rules:

Not empty
Max length: 255 characters
Generic text (standard alphanumeric and common characters)

Error response:

{
  "SignificantPersons[0].Address.Line1": [
    "'Line1' must not be empty.",
    "The length of 'Line 1' must be 255 characters or fewer. You entered 1501 characters."
  ]
}

Line2, Line3, Region

Validation rules:

Maximum length: 255 characters
Optional fields (not required)

Error response:

{
  "SignificantPersons[0].Address.Line2": [
    "The length of 'Line 2' must be 255 characters or fewer. You entered 1501 characters."
  ]
}