Prospect Data Requirements

This page describes the data Greenlight needs to determine whether a renter can be offered a Greenlight Deposit or Greenlight Guarantee. Final underwriting and pricing happen later, once the renter is in the enrollment flow.

Field names below are exactly as they appear in the Partner Prospect API request body. If you are sending partner webhook events, you keep your own field names and Greenlight's normalizer maps them onto these — so read this page as the set of values your events need to convey between them, not as a schema to conform to.

There are two distinct bars to clear:

1. Validation — three fields, without which the prospect cannot be written at all. Over the API this is a 422; over events it is a dropped or dead-lettered message.
2. Completeness — the larger set below, without which the prospect is accepted but sits at incomplete and never becomes eligible to enroll.

Required to accept the request

Field	Format	Notes
source	string	Your partner code, assigned by Greenlight
source_prospect_id	string	Your identifier. Unique per property owner and source.
terms_accepted_at	ISO 8601 timestamp	When the renter accepted Greenlight's terms in your flow

Although source_prospect_id only has to be unique within a property owner, use an identifier that is unique across your whole system. If you later serve a second property owner through Greenlight, reused IDs make your own logs and webhook handling ambiguous long before Greenlight rejects anything.

Required for the prospect to become eligible

A prospect moves from incomplete to processing only once all of these are present:

Identity

Field	Format	Notes
first_name	string	Legal first name
last_name	string	Legal last name
email	string	Also the key the renter uses to open their enrollment link
phone	string	Exactly 10 digits, no country code, no formatting (e.g. 5559876543)
birthdate	YYYY-MM-DD

Lease

Field	Format	Notes
lease_start_date	YYYY-MM-DD
lease_end_date	YYYY-MM-DD
monthly_rent_cents	integer	Cents. 200000 is $2,000.00.
deposit_amount_cents	integer	Required for completeness on a deposit-product prospect. Not required when guarantor_coverage is true.

deposit_amount_cents isn't required when guarantor_coverage is true, and Greenlight ignores it either way for Greenlight Guarantee: Greenlight Guarantee coverage comes from Greenlight's guarantor application rule (or property default) and monthly_rent_cents, not that field.

Underwriting

Field	Format	Notes
screening_result	enum	approved, conditional, or denied
employment_status	enum	full_time_student, employed, self_employed, unemployed, retired, corporation
yearly_income	integer	Whole dollars, not cents
has_ssn	boolean	See below
social_security_number	string	Required when has_ssn is true

Note the units asymmetry: yearly_income is in dollars while every *_cents field is in cents.

Optional ingest fields: when an enrollment source allows optional ingest fields, screening_result, employment_status, and yearly_income are not required for completeness. If screening_result is omitted, Greenlight treats it as approved. Employment and income are collected later in the purchase flow when missing. Confirm with your Partner Success Manager whether this applies to your integration.

The SSN pair

has_ssn and social_security_number must agree, and this is enforced as a validation rather than treated as incompleteness:

• has_ssn: true requires a non-blank social_security_number
• has_ssn: false requires social_security_number to be absent
• Leaving has_ssn unset keeps the prospect incomplete

Sending has_ssn: false is a valid, complete state — Greenlight underwrites renters without an SSN.

Conditionally required

PMS identifiers

Field	Format	Notes
pms_type	enum	Currently only yardi
pms_property_id	string	Property code in the PMS
pms_unit_id	string	Unit code in the PMS
pms_prospect_id	string	Prospect/resident code in the PMS

These are optional by default. When all of pms_type, pms_property_id, and pms_unit_id are supplied, Greenlight matches the prospect to a specific property and unit, which improves pricing accuracy and lets webhook payloads carry PMS codes back to you.

Some property owners require them. When a property owner is configured that way, a prospect without them is marked ineligible: when guarantor_coverage is false, the reason appears in sdi_ineligibility_reasons; when true, in rg_ineligibility_reasons. Confirm with your Partner Success Manager whether this applies to the owners you work with.

Optional

Product selection

Field	Format	Notes
guarantor_coverage	boolean	When true, Greenlight evaluates Greenlight Guarantee and marks Greenlight Deposit and cash deposit ineligible. Default false. Not required for completeness.

Underwriting details

Field	Format	Notes
education_level	enum	high_school, associate_degree, bachelor_degree, masters_degree, doctoral_degree
citizenship	enum	us_or_green_card, non_us

education_level and citizenship refine underwriting but never block eligibility. If you omit them, Greenlight collects them from the renter during enrollment.

Formats

• Dates — YYYY-MM-DD
• Timestamps — ISO 8601, e.g. 2026-07-24T15:04:05Z
• Money — integer cents on *_cents fields, no symbols, separators, or decimals
• Phone — exactly 10 digits, no country code, no punctuation or spaces. +15559876543 and (555) 987-6543 are both a 422, not a normalized value.
• Enums — lowercase snake_case, exactly as listed. An unrecognized value is a 422, not a silent fallback.

Sending null for a field is not the same as omitting it — omitted fields leave the stored value untouched, while null clears it and can push a ready prospect back to incomplete.

Handling PII

You are sending SSNs and dates of birth, so treat these requests accordingly:

• All traffic is HTTPS; Greenlight rejects plaintext HTTP
• Never place prospect PII in URL query strings or path segments — only in the request body
• Do not log request bodies containing social_security_number
• Greenlight stores SSNs encrypted at rest and does not return them in any API response or webhook payload

Greenlight handles FCRA adverse-action notices for declined applications directly with the renter. Your integration does not need to surface a decline reason, and none is provided in the API or webhook payloads.

Next steps

• Partner Webhook Events — the preferred way to send this data
• Partner Prospect API — sending it over HTTP instead
• Integration Types Overview — choosing an enrollment flow