Lead Input Schema

The LeadInput type defines all fields accepted by the createLead mutation. This page provides a complete reference for each field.

Required Fields

These fields must be provided for every lead submission.

Field	Type	Format	Description
firstName	String!	Text	Applicant’s first name
lastName	String!	Text	Applicant’s last name
email	String!	Email	Valid email address
homePhone	String!	10 digits	Phone number (no formatting)
address1	String!	Text	Street address
city	String!	Text	City name
state	String!	2 chars	State code (e.g., CA, TX)
zipCode	String!	5 digits	ZIP code

Service-Managed Fields

The following fields are NOT part of LeadInput and are automatically set by the service: - leadSourceId - Determined from your partner credentials - productCodes - Configured during partner onboarding - mode, campaignCode - Internal processing configuration - All status fields (resultCode, verificationStatus, etc.)

Personal Information Fields

Name and Contact

Field	Type	Required	Description
firstName	String!	Yes	First name (1-50 chars)
lastName	String!	Yes	Last name (1-50 chars)
email	String!	Yes	Email address
homePhone	String!	Yes	Primary phone (10 digits)
cellPhone	String	No	Cell phone (10 digits)
workPhone	String	No	Work phone (10 digits)

Date of Birth

Field	Type	Required	Format	Example
dateOfBirth	String	No	YYYY-MM-DD	1985-06-15

Note

Date of birth is optional — Monevo no longer requires this field. When provided, it must be in ISO 8601 format (YYYY-MM-DD). Invalid formats will be rejected.

Social Security Number

Field	Type	Required	Format	Example
socialSecurityNumber	String	No	9 digits	123456789

Note

SSN is optional, but recommended

Address Fields

Primary Address

Field	Type	Required	Description
address1	String!	Yes	Street address
address2	String	No	Apt, suite, unit, etc.
city	String!	Yes	City name
state	String!	Yes	2-letter state code
zipCode	String!	Yes	5-digit ZIP code

Residence Details

Field	Type	Required	Description
residenceTypeId	Int	No	Type of residence (see Reference IDs)
monthsAtAddress	Int	No	Months at current address
monthlyRent	Int	No	Monthly rent/mortgage (dollars)

Employment & Income Fields

Field	Type	Required	Description
incomeSourceId	Int	No	Income source type (see Reference IDs)
payFrequencyId	Int	No	Pay frequency (see Reference IDs)
monthlyIncome	Int	No	Monthly income (dollars)
grossAnnualIncome	Int	No	Gross annual income (dollars)
employerName	String	No	Employer name
monthsAtEmployer	Int	No	Months at current employer

Loan & Debt Fields

Field	Type	Required	Description
loanAmount	Int	No	Requested loan amount (dollars)
loanPurposeId	Int	No	Loan purpose (see Reference IDs)
estimatedDebt	Int	No	Estimated total debt amount (dollars)

Estimated Debt Resolution

The estimatedDebt field is used as a fallback when the system cannot determine debt from other sources. The service resolves estimated debt using a 3-tier priority chain:

1. Product code mapping (from credit qualification) — highest priority
2. Credit data (unsecuredDebtTotal from credit pull)
3. Partner-supplied estimatedDebt — lowest priority

You do not need to provide this field if the lead will go through credit qualification, but it is recommended as a safety net for cases where credit data is unavailable.

Consent Fields

Field	Type	Required	Default	Description
termsConsent	Boolean	No	false	Terms and conditions consent
marketingOptIn	Boolean	No	false	Marketing communications opt-in

Tracking Fields

Field	Type	Required	Description
affiliateAppID	String	No	Affiliate application ID
siteURL	String	No	URL where lead was captured
siteIP	String	No	Server IP address
clientIP	String	No	Client IP address
ref	String	No	Reference/tracking parameter
leadId	String	No	Your external lead ID
trustedformCertificateID	String	No	TrustedForm certificate URL

Co-Applicant Fields

Include these fields when the application has a co-applicant.

Field	Type	Required	Description
coApplicant	Boolean	No	Has co-applicant flag
coApplicantFirstName	String	No	Co-applicant first name
coApplicantLastName	String	No	Co-applicant last name
coApplicantDateOfBirth	String	No	Co-applicant DOB (YYYY-MM-DD)
coApplicantAnnualIncome	Int	No	Co-applicant annual income
coApplicantAddress1	String	No	Co-applicant address
coApplicantAddress2	String	No	Co-applicant address line 2
coApplicantCity	String	No	Co-applicant city
coApplicantState	String	No	Co-applicant state
coApplicantZipCode	String	No	Co-applicant ZIP code

Complete Example

{
  "input": {
    "firstName": "John",
    "lastName": "Test",
    "email": "john.doe@gmail.com",
    "homePhone": "8166999999",
    "address1": "1230 Public Lane 456",
    "city": "Dallas",
    "state": "OH",
    "zipCode": "65542",
    "dateOfBirth": "1970-01-26",
    "socialSecurityNumber": "123456789",
    "incomeSourceId": 1,
    "residenceTypeId": 2,
    "payFrequencyId": 1,
    "monthlyIncome": 4000,
    "loanAmount": 5000,
    "loanPurposeId": 1,
    "estimatedDebt": 25000,
    "siteURL": "yoursite.com",
    "clientIP": "107.77.220.32",
    "affiliateAppID": "YOUR-AFFILIATE-APP-ID",
    "leadId": "YOUR-EXTERNAL-LEAD-ID",
    "trustedformCertificateID": "https://cert.trustedform.com/abc123"
  }
}

Recommended Fields

While only the basic contact and address fields are required, providing these optional fields improves lead qualification: - dateOfBirth - Improves deduplication accuracy - socialSecurityNumber - Required for credit pull and qualification - incomeSourceId, monthlyIncome - Income verification - affiliateAppID - Partner tracking - trustedformCertificateID - Lead validation

Validation Rules

Field Formats

Field	Validation
email	Valid email format
homePhone	10 digits, no formatting
dateOfBirth	YYYY-MM-DD (when provided)
state	2-letter state code
zipCode	5 digits
socialSecurityNumber	9 digits

State Codes

Valid 2-letter state codes:

AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA,
HI, ID, IL, IN, IA, KS, KY, LA, ME, MD,
MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ,
NM, NY, NC, ND, OH, OK, OR, PA, RI, SC,
SD, TN, TX, UT, VT, VA, WA, WV, WI, WY,
DC, PR, VI, GU

Related

• createLead - Submit leads
• Reference IDs - Lookup values
• Result Codes - Processing outcomes