--- updatedAt: 2026-09-28T10:13:59.000Z agentTools: projectIndex: https://docs.youlend.com/llms.txt --- # Onboarding API Validation Validation rules for Create a lead and Update significant persons endpoints, including supported characters for significant person text fields. This guide outlines the list of validation rules used in the [Create a lead](https://docs.youlend.com/reference/post_leads) and [Update significant persons](https://docs.youlend.com/reference/put_leads-leadid-significantpersons) 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: ```json { "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. API reference for creating a new lead API reference for updating significant persons on a lead *** # [Create a lead](https://docs.youlend.com/reference/post_leads) validation The following table lists each property in the [Create a lead](https://docs.youlend.com/reference/post_leads) 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–200 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` | Yes | Phone number (8–20 characters) | | `ContactEmailAddress` | Yes | Email address (max 255 characters) | | `SignupClientIp` | USA only | Client IP address | | `EmployerIdentificationNumber` | USA only | EIN in `XX-XXXXXXX` format (non-sole traders) | **Validation rules:** * Not empty * Max length of 50 characters * Matches regex: `^[a-zA-Z0-9_\.-]{1,50}` **Error response:** ```json { "ThirdPartyCustomerId": [ "'Third Party Customer Id' must not be empty.", "The third party customer id is invalid." ] } ``` **Validation rules:** * Not empty * Must be a valid ISO 3166 country code — see the [Country ISO Codes Reference](https://docs.youlend.com/reference/country-iso-codes) for the full list of supported countries **Error response:** ```json { "$.countryISOCode": [ "The JSON value could not be converted to YL.Web.Api.ThirdParty.Onboarding.Models.CountryCodes. Path: $.countryISOCode | LineNumber: 4 | BytePositionInLine: 28." ] } ``` **Validation rules:** * Not empty * One of `"GBP"`, `"EUR"`, `"DKK"`, `"PLN"`, `"USD"` **Error response:** ```json { "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" ] } ``` **Validation rules:** * Not empty * Max length: 255 characters **Error response:** ```json { "KeyContactName": [ "'Key Contact Name' must not be empty." ] } ``` **Validation rules:** * Not empty * Must be a valid company type — see the [Company Type](https://docs.youlend.com/reference/company-types-by-country) for allowed value by country (e.g., `soleTrader`, `limitedCompany`, etc.) **Error response:** ```json { "$.companyType": [ "The JSON value could not be converted to YL.Web.Api.ThirdParty.Onboarding.Models.CompanyTypes. Path: $.companyType | LineNumber: 7 | BytePositionInLine: 26." ] } ``` **Validation rules:** * Not empty * Minimum length: 2 characters * Maximum length: 200 characters * Alphanumeric and special characters only (regex allows letters, digits, spaces, hyphens, accents, and common punctuation) **Error response:** ```json { "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 200 characters or fewer. You entered 300 characters." ] } ``` **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:** ```json { "CompanyWebsite": [ "The company website is invalid.", "The length of 'Company Website' must be 1000 characters or fewer. You entered 1200 characters." ] } ``` **Validation rules:** * Minimum length: 1 character * Maximum length: 200 characters **Error response:** ```json { "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." ] } ``` **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:** ```json { "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." ] } ``` **Validation rules:** * Minimum length: 6 * Maximum length: 14 * Matches regex: `^[a-zA-Z0-9].*` **Error response:** ```json { "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." ] } ``` **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:** ```json { "Mid": [ "The mid is invalid. Acceptable MIDs must contain at least 7 alpha-numeric characters.", "You can only use one way of specifying 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:** ```json { "MerchantIds": [ "You can only use one way of specifying MerchantIds.", "The mid is invalid. Acceptable MIDs must contain at least 7 alpha-numeric characters." ] } ``` **Validation rules:** - Not empty - Minimum length: 8 - Maximum length: 20 - Matches regex: `^[+0-9].*` **Error response:** ```json { "ContactPhoneNumber": [ "The length of 'Contact Phone Number' must be 20 characters or fewer. You entered 49 characters.", "The company contact phone number is invalid." ] } ``` **Validation rules:** - Not empty - Maximum length: 255 - Must contain exactly one `@` symbol (ASP.NET Core compatible email validation) **Error response:** ```json { "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." ] } ``` **Validation rules:** * Required when `CountryISOCode` is `USA` * Must be a valid IP address **Error response:** ```json { "SignupClientIp": [ "Signup Client Ip is invalid", "Signup Client Ip cannot be empty" ] } ``` **Validation rules:** * Required when `CountryISOCode` is `USA` and `CompanyType` is not `soleTrader` * Matches regex: `^\d{2}-\d{7}` (format: `XX-XXXXXXX`) **Error response:** ```json { "EmployerIdentificationNumber": [ "Employer Identification Number is invalid", "Employer Identification Number cannot be empty" ] } ``` *** # [Update significant persons](https://docs.youlend.com/reference/put_leads-leadid-significantpersons) validation The following table lists each property in the [Update significant persons](https://docs.youlend.com/reference/put_leads-leadid-significantpersons) 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: ```text - ´ ' ' , . @ & ¿ ? ¡ ! " " £ $ % ^ * _ : ; # + = ( ) \ / ` ``` **Validation rules:** * Not empty * Max length: 255 characters * Supports the significant person text field characters listed above **Error response:** ```json { "SignificantPersons[0].FirstName": [ "'First Name' must not be empty.", "The length of 'First Name' must be 255 characters or fewer. You entered 1501 characters." ] } ``` **Validation rules:** * Not empty * Max length: 255 characters * Supports the significant person text field characters listed above **Error response:** ```json { "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." ] } ``` **Validation rules:** * Not empty * Must be a valid person type — see the [`typeOfPerson` enums](https://docs.youlend.com/reference/type-of-person) for allowed values. **Error response:** ```json { "$.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." ] } ``` **Validation rules:** * The person must be at least 18 years old based on the provided date **Error response:** ```json { "SignificantPersons[0].DateOfBirth.Year": [ "'Year' must be less than or equal to '2006'." ] } ``` **Validation rules:** * Not empty * Max length: 255 characters * Generic text (standard alphanumeric and common characters) **Error response:** ```json { "SignificantPersons[0].Address.Line1": [ "'Line1' must not be empty.", "The length of 'Line 1' must be 255 characters or fewer. You entered 1501 characters." ] } ``` **Validation rules:** * Maximum length: 255 characters * Optional fields (not required) **Error response:** ```json { "SignificantPersons[0].Address.Line2": [ "The length of 'Line 2' must be 255 characters or fewer. You entered 1501 characters." ] } ```