---
updatedAt: 2026-09-28T09:43:57.000Z
agentTools:
  projectIndex: https://docs.youlend.com/llms.txt
---

# Create a lead.

Notice that the 200 response includes the signUpURL to redirect a merchant to their application in the YouLend hosted journey.

Partners can use the variable `thirdPartyCustomerId` to share their own internal customer ID for the merchant, making it easier for partners to match the lead to their internal systems.

<Callout icon="📘" theme="info">
  ### Good to know

  For Embedded components please Include `"leadType": "Embedded"` in every Create Lead request. This classifies newly created leads as Embedded. API partners do not need to change their requests: when `leadType` is omitted or empty, it defaults to `Api`.
</Callout>

<Callout icon="🚧" theme="warn">
  ### weBe aware (USA)

  1. In the USA,`employerIdentificationNumber` param is mandatory unless `companyType` is `SoleTrader`**.**
  2. When submitting an Address, the `region` param is mandatory and must correspond to a valid State (eg. "New York"), or a valid ANSI 2 letter State code (eg. "NY").
  3. `signupClientIp` is required for USA leads.
</Callout>

<Callout icon="📘" theme="info">
  ### Good to know

  The `companyWebsite` parameter is optional but strongly recommended. Including it in the Create Lead request helps YouLend verify the business and significantly reduces the likelihood of pushbacks. Please provide this value whenever possible.
</Callout>

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Onboarding",
    "description": "Through this API you can can initiate the process of onboarding a borrower with YouLend",
    "contact": {
      "name": "Mark Ufland",
      "email": "mark.ufland@youlend.com"
    },
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://partners.staging-youlendapi.com/onboarding"
    }
  ],
  "paths": {
    "/Leads": {
      "post": {
        "tags": [
          "Create an Application"
        ],
        "summary": "Create a lead.",
        "parameters": [
          {
            "name": "api-version",
            "in": "header",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "A YL.Web.Api.ThirdParty.Onboarding.Models.ThirdPartyOnboardingModel containing the data required to create the lead.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThirdPartyOnboardingModel"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns a CreateThirdPartyAdvanceOnboardingResultModel.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateThirdPartyAdvanceOnboardingResultModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/CreateThirdPartyAdvanceOnboardingResultModel"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AddressModel": {
        "required": [
          "areaCode",
          "city",
          "line1"
        ],
        "type": "object",
        "properties": {
          "line1": {
            "maxLength": 255,
            "minLength": 1,
            "type": "string",
            "description": "Gets or sets Address Line 1."
          },
          "line2": {
            "type": "string",
            "description": "Gets or sets Address Line 2.",
            "nullable": true
          },
          "line3": {
            "type": "string",
            "description": "Gets or sets Address Line 3.",
            "nullable": true
          },
          "city": {
            "maxLength": 255,
            "minLength": 1,
            "type": "string",
            "description": "Gets or sets the City."
          },
          "region": {
            "type": "string",
            "description": "Gets or sets the Region.",
            "nullable": true
          },
          "areaCode": {
            "maxLength": 255,
            "minLength": 1,
            "type": "string",
            "description": "Gets or sets the Area Code."
          },
          "country": {
            "type": "string",
            "description": "Gets or sets the Country. Cannot be null or empty if YL.Web.Api.ThirdParty.Onboarding.Models.AddressModel.CountryISOCode is not set. If both are set, we use YL.Web.Api.ThirdParty.Onboarding.Models.AddressModel.Country.",
            "nullable": true
          },
          "countryISOCode": {
            "enum": [
              "GBR",
              "IRL",
              "NLD",
              "BEL",
              "POL",
              "USA",
              "DEU",
              "FRA",
              "ESP",
              "DNK"
            ],
            "type": "string",
            "description": "Gets or sets the CountryISOCode. Cannot be null or empty if YL.Web.Api.ThirdParty.Onboarding.Models.AddressModel.Country is not set. If both are set, we use YL.Web.Api.ThirdParty.Onboarding.Models.AddressModel.Country."
          }
        },
        "additionalProperties": false,
        "description": "Address Data Model."
      },
      "CreateThirdPartyAdvanceOnboardingResultModel": {
        "type": "object",
        "properties": {
          "leadId": {
            "type": "string",
            "description": "Gets or sets the Lead Id.",
            "format": "uuid"
          },
          "leadURL": {
            "type": "string",
            "description": "Gets or sets the Lead redirect URL.",
            "nullable": true
          },
          "signUpURL": {
            "type": "string",
            "description": "Gets or sets the broker redirect URL.",
            "nullable": true
          },
          "openBankingURL": {
            "type": "string",
            "description": "Gets or sets the Open Banking Url.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "The result of creating a third party lead."
      },
      "Industry": {
        "required": [
          "code",
          "description"
        ],
        "type": "object",
        "properties": {
          "code": {
            "minLength": 1,
            "type": "string",
            "description": "Gets or sets the SIC code for the industry."
          },
          "description": {
            "maxLength": 255,
            "minLength": 1,
            "type": "string",
            "description": "Gets or sets the description of the industry."
          }
        },
        "additionalProperties": false,
        "description": "Model representing an industry."
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "detail": {
            "type": "string",
            "nullable": true
          },
          "instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": {}
      },
      "RenewalModel": {
        "type": "object",
        "properties": {
          "isRenewalLead": {
            "type": "boolean",
            "description": "Gets or sets a value indicating whether a lead is renewal."
          },
          "previousLeadId": {
            "type": "string",
            "description": "Gets or sets the previous lead id.",
            "format": "uuid"
          }
        },
        "additionalProperties": false,
        "description": "Renewal data model."
      },
      "SecondaryLendingPartnerDetailsModel": {
        "type": "object",
        "properties": {
          "secondaryLendingPartnerId": {
            "type": "string",
            "description": "Gets or sets the secondary lending partner id.",
            "nullable": true
          },
          "secondaryLendingPartnerName": {
            "type": "string",
            "description": "Gets or sets the secondary lending partner name.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Secondary lending partner details model."
      },
      "ThirdPartyOnboardingModel": {
        "required": [
          "companyName",
          "companyType",
          "contactEmailAddress",
          "contactPhoneNumber",
          "countryISOCode",
          "keyContactName",
          "loanCurrencyISOCode",
          "registeredAddress",
          "thirdPartyCustomerId"
        ],
        "type": "object",
        "properties": {
          "thirdPartyCustomerId": {
            "minLength": 1,
            "type": "string",
            "description": "Gets or sets the third party's unique id for a merchant."
          },
          "companyName": {
            "maxLength": 200,
            "minLength": 2,
            "type": "string",
            "description": "Gets or sets the merchant's company name."
          },
          "countryISOCode": {
            "minLength": 1,
            "enum": [
              "GBR",
              "IRL",
              "NLD",
              "BEL",
              "POL",
              "USA",
              "DEU",
              "FRA",
              "ESP",
              "DNK"
            ],
            "type": "string",
            "description": "Gets or sets the ISO country code for the merchant."
          },
          "loanCurrencyISOCode": {
            "minLength": 1,
            "type": "string",
            "description": "Gets or sets the ISO currency code for the merchant."
          },
          "keyContactName": {
            "maxLength": 255,
            "minLength": 1,
            "type": "string",
            "description": "Gets or sets the key merchant contact who will be applying for the loan."
          },
          "companyType": {
            "minLength": 1,
            "enum": [
              "Ltd",
              "Plc",
              "Llp",
              "SoleTrader",
              "Partnership",
              "Llc",
              "BusinessCorporation",
              "Dac",
              "Eenmanszaak",
              "Bv",
              "Cv",
              "Nv",
              "Vof",
              "NaamlozeVennootschap",
              "SpZoo",
              "SpkSpj",
              "Scspp",
              "SaSKA",
              "Jdg",
              "GmbhUg",
              "EK",
              "Gewerbebetrieb",
              "GbrOhg",
              "Gbr",
              "EGbr",
              "Ohg",
              "Kg",
              "Aktiengesellschaft",
              "SlSlne",
              "SociedadColectiva",
              "SociedadComanditaria",
              "EIAutonomo",
              "SociedadCivil",
              "SociedadCooperativa",
              "SARL",
              "EINomPropre",
              "SNC",
              "SocieteCooperative",
              "SA",
              "SAS",
              "EURL",
              "SCP",
              "SCS",
              "SASU",
              "AS",
              "ApS",
              "KS",
              "PS",
              "Fmba",
              "Andelsselskab",
              "Amba",
              "ErhvervsdrivendeFond",
              "IS",
              "Smba",
              "SI",
              "SelvstændigOffentligVirksomhed",
              "Partrederi",
              "Filial",
              "Enkeltmandsvirksomhed",
              "PMV",
              "Forening"
            ],
            "type": "string",
            "description": "Gets or sets the key merchant company type."
          },
          "registeredAddress": {
            "$ref": "#/components/schemas/AddressModel"
          },
          "contactPhoneNumber": {
            "maxLength": 20,
            "minLength": 8,
            "type": "string",
            "description": "Gets or sets the merchant's contact phone number."
          },
          "contactEmailAddress": {
            "maxLength": 255,
            "minLength": 1,
            "type": "string",
            "description": "Gets or sets the merchant's key contact email address.",
            "format": "email"
          },
          "confirmedCreditSearch": {
            "type": "boolean",
            "description": "Gets or sets a value indicating whether the lead has given their consent for a credit search. This parameter has to be true in order for the lead to be able to submit the application (stage 1)."
          },
          "thirdPartyLeadId": {
            "type": "string",
            "description": "Gets or sets the third party's id for the specific application (lead).",
            "nullable": true
          },
          "monthlyCardRevenue": {
            "type": "number",
            "description": "Gets or sets the monthly card revenue for the merchant.",
            "format": "double"
          },
          "numberOfPaymentsPerMonth": {
            "type": "integer",
            "description": "Gets or sets the number of payments a merchant has each month.",
            "format": "int32"
          },
          "sweepPercentage": {
            "type": "number",
            "description": "Gets or sets the percentage of daily sales the merchant wants to use to pay back the loan.",
            "format": "double"
          },
          "monthsTrading": {
            "type": "integer",
            "description": "Gets or sets the number of months the merchant has been trading.",
            "format": "int32"
          },
          "loanAmount": {
            "type": "number",
            "description": "Gets or sets the size of loan the merchant wants.",
            "format": "double"
          },
          "companyWebsite": {
            "type": "string",
            "description": "Gets or sets the merchants company website URL.",
            "nullable": true
          },
          "companyNumber": {
            "type": "string",
            "description": "Gets or sets the registered company number for the merchant.",
            "nullable": true
          },
          "vatNumber": {
            "type": "string",
            "description": "Gets or sets the VAT number for the merchant.",
            "nullable": true
          },
          "mid": {
            "type": "string",
            "description": "Gets or sets the MID for the merchant.",
            "nullable": true
          },
          "merchantIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Gets or sets the MerchantIds for the merchant if there is more than one.",
            "nullable": true
          },
          "additionalInfo": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Gets or sets a list of key values pairs representing any additional lead data not already covered.",
            "nullable": true
          },
          "signupClientIp": {
            "type": "string",
            "description": "Gets or sets the Ip address of the merchant.",
            "nullable": true
          },
          "notificationURL": {
            "type": "string",
            "description": "(DEPRECATED - please see https://docs.youlend.com/reference/webhooks-intro for how to subscribe to notifications).",
            "nullable": true
          },
          "employerIdentificationNumber": {
            "type": "string",
            "description": "Gets or sets the merchant's tax identification number (required for USA).",
            "nullable": true
          },
          "renewal": {
            "$ref": "#/components/schemas/RenewalModel"
          },
          "tradingAddress": {
            "$ref": "#/components/schemas/AddressModel"
          },
          "tradingName": {
            "maxLength": 200,
            "minLength": 1,
            "type": "string",
            "description": "Gets or sets the merchant's trading name.",
            "nullable": true
          },
          "preApprovalId": {
            "type": "string",
            "description": "Gets or sets the PreApprovalId.",
            "format": "uuid"
          },
          "leadType": {
            "enum": [
              "Api",
              "Embedded"
            ],
            "type": "string",
            "description": "Gets or sets the lead type. Defaults to Api when omitted.",
            "nullable": true
          },
          "ownerUserId": {
            "type": "string",
            "description": "Gets or sets the OwnerUserId.",
            "format": "uuid"
          },
          "preferredLanguageCode": {
            "enum": [
              "EN",
              "NL",
              "NL_BE",
              "ES",
              "DE",
              "PL",
              "EN_US",
              "FR",
              "DA"
            ],
            "type": "string",
            "description": "Gets or sets the PreferredLanguageCode.",
            "nullable": true
          },
          "preferredRepaymentMethod": {
            "enum": [
              "SBR",
              "DD",
              "SalesBasedRepaymentManagingProcessor"
            ],
            "type": "string",
            "description": "Gets or sets the preferred repayment method for the merchant.\r\nAccepted values: \"Sales-Based Repayment\", \"Direct Debit Fixed\".",
            "nullable": true
          },
          "secondaryLendingPartnerDetails": {
            "$ref": "#/components/schemas/SecondaryLendingPartnerDetailsModel"
          },
          "industries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Industry"
            },
            "description": "Gets or sets the Industries.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Third party onboarding model for create a Youlend lead."
      }
    },
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://youlend-stag.eu.auth0.com/oauth/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "security": [
    {
      "oauth2": []
    }
  ],
  "tags": [
    {
      "name": "Create an Application"
    }
  ]
}
```