Prepared for NestDash, Thursday April 30 call

VetFlow API Docs

Integration reference for VetScore, applicant scraping, and white-label deployment. This page reflects the current partner payloads available on https://vetflow.nanocorp.app.

Base URL

https://vetflow.nanocorp.app

Partner Contact

alex@vetflow.com

Updated

April 29, 2026

Endpoint

VetScore API

Use `POST /api/free-screening` to submit an applicant and property pair and receive a first-pass VetScore, recommendation, and supporting risk signals. Reuse the returned `propertyId` when screening multiple applicants for the same unit.

Method: POST

Path: /api/free-screening

Content-Type: application/json

Request Body

NestDash can map the full applicant and property intake form directly into this payload.

Field	Type	Required	Description
`email`	string	Yes	Landlord or operator email used to deliver the result and create the lead record.
`applicantName`	string	Recommended	Applicant full name shown in the VetScore result. If omitted, VetFlow falls back to "Applicant".
`applicantEmail`	string	Yes	Applicant email used for identity matching and duplicate-screen prevention within a property.
`applicantDob`	string (YYYY-MM-DD)	Yes	Applicant date of birth in ISO date format.
`applicantAddress`	string	Yes	Applicant current street address.
`applicantCity`	string	Yes	Applicant current city.
`applicantState`	string	Yes	Two-letter US state code, for example `TX` or `OH`.
`applicantPostalCode`	string	Yes	US ZIP code, `12345` or `12345-6789`.
`propertyAddress`	string	Yes	Rental property street address.
`propertyCity`	string	Yes	Rental property city.
`propertyState`	string	Yes	Two-letter US state code for the property.
`propertyPostalCode`	string	Yes	Property ZIP code.
`monthlyRent`	integer	Yes	Monthly rent in USD. Current validation minimum is `300`.
`monthlyIncome`	integer	Yes	Monthly applicant income in USD. Current validation minimum is `1000`.
`propertyId`	string (UUID)	Optional	Property comparison key. Reuse the same `propertyId` to screen and rank multiple applicants for one property.

Response Envelope

Field	Type	Required	Description
`ok`	boolean	Always	True when the request completed successfully.
`existingRequest`	boolean	Always	True when the applicant was already screened for the same property and VetFlow returned the saved result.
`message`	string	Always	Human-readable summary for operators or logs.
`result`	object	Always	VetScore outcome payload described below.

VetScore Result Fields

The current breakdown is returned through `factors` plus the verified credit, eviction, criminal, and provider score fields below.

Field	Type	Required	Description
`propertyId`	string (UUID)	Always	Property grouping key returned by VetFlow.
`applicantName`	string	Always	Applicant name displayed on the VetScore result.
`vetScore`	integer	Always	Composite VetScore from `0` to `100`.
`recommendation`	string	Always	Plain-English recommendation, for example approval or manual review.
`tierLabel`	string	Always	High-level fit label for the applicant profile.
`factors`	string[]	Always	Short explanation list that acts as the score breakdown returned today.
`screeningSourceLabel`	string	Always	Label describing the scoring or screening source used by VetFlow.
`verificationStatus`	`verified` \| `mock`	Always	Whether the provider response is live-verified or currently running in mock mode.
`screeningReportStatus`	string	Always	Upstream screening report status, for example `COMPLETE`.
`verifiedCreditScore`	integer \| null	Always	Verified or estimated credit score when available.
`verifiedCreditBand`	string	Always	Normalized band used in the score: `760_plus`, `700_759`, `640_699`, `580_639`, or `below_580`.
`verifiedCreditLabel`	string \| null	Always	Readable label for the credit outcome, such as `Good`.
`verifiedEvictionRisk`	`clear` \| `review` \| `hit`	Always	Eviction-risk flag in the VetScore breakdown.
`verifiedCriminalRisk`	`clear` \| `review` \| `hit`	Always	Background-risk flag in the VetScore breakdown.
`providerScore`	integer \| null	Always	Upstream provider score when available.
`providerScoreLabel`	string \| null	Always	Readable provider score label, such as `Strong` or `Moderate`.

Example Request

cURLExample

curl -X POST "https://vetflow.nanocorp.app/api/free-screening" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_PARTNER_KEY" \
  -d '{
    "email": "ops@nestdash.com",
    "applicantName": "Jordan Lee",
    "applicantEmail": "jordan.lee@example.com",
    "applicantDob": "1993-08-14",
    "applicantAddress": "1824 Willow Ave",
    "applicantCity": "Columbus",
    "applicantState": "OH",
    "applicantPostalCode": "43215",
    "propertyAddress": "900 Summit St Apt 4B",
    "propertyCity": "Columbus",
    "propertyState": "OH",
    "propertyPostalCode": "43215",
    "monthlyRent": 1800,
    "monthlyIncome": 6400
  }'

Example Response

JSONExample

{
  "ok": true,
  "existingRequest": false,
  "message": "Your VetScore is ready. Review the first-pass summary below.",
  "result": {
    "propertyId": "b6f30b02-1ba6-4f08-ae1f-f96e8c45f90d",
    "applicantName": "Jordan Lee",
    "vetScore": 82,
    "recommendation": "Approve with standard deposit.",
    "tierLabel": "Strong fit",
    "factors": [
      "3.6x income-to-rent coverage stood out",
      "Verified 742 credit lifted the profile",
      "Clear eviction screening helped this applicant"
    ],
    "screeningSourceLabel": "VetFlow pre-screening profile",
    "verificationStatus": "mock",
    "screeningReportStatus": "COMPLETE",
    "verifiedCreditScore": 742,
    "verifiedCreditBand": "700_759",
    "verifiedCreditLabel": "Good",
    "verifiedEvictionRisk": "clear",
    "verifiedCriminalRisk": "clear",
    "providerScore": 84,
    "providerScoreLabel": "Strong"
  }
}

Authentication

Partner authentication is documented as an API-key header: send x-api-key on every request. VetFlow will issue a dedicated key to NestDash before production launch.

Current status: the public partner docs reflect the production plan, while pilot access is still coordinated directly with VetFlow. NestDash should build against the header now so no integration changes are needed when enforcement is enabled.

Endpoint

Scraper API

Use `POST /api/scrape` to enrich a target market with current rental or applicant-style leads from supported sources. VetFlow returns normalized city metadata, persisted lead records, and non-fatal scrape warnings.

Method: POST

Path: /api/scrape

Sources: craigslist, zillow, or both

Request Schema

Field	Type	Required	Description
`city`	string	Yes	Target market, for example `Columbus` or `Columbus, OH`. VetFlow normalizes this before scraping.
`source`	`craigslist` \| `zillow` \| `both`	Yes	Requested lead source or combined scrape mode.

Response Envelope

Field	Type	Required	Description
`ok`	boolean	Always	True when the scrape request completed successfully.
`city`	string	Always	Normalized market label returned by VetFlow.
`leads`	ScrapedLead[]	Always	Persisted lead records returned from the selected source(s).
`warnings`	ScrapeWarning[]	Always	Non-fatal scrape warnings, typically used when a source is partially blocked or returns no parsable data.

Lead Object

Field	Type	Required	Description
`id`	string	Always	VetFlow database identifier for the stored lead.
`city`	string	Always	Normalized city or market label.
`source`	`craigslist` \| `zillow`	Always	Source that produced the lead.
`name`	string \| null	Always	Lead or listing title when available.
`contact`	string \| null	Always	Public contact details when they can be extracted.
`url`	string	Always	Source URL for the lead.
`rawData`	object	Always	Unmodified structured scrape payload retained for downstream mapping.
`scrapedAt`	string (ISO timestamp)	Always	Timestamp when VetFlow stored or refreshed the lead.

Warning Object

Field	Type	Required	Description
`source`	`craigslist` \| `zillow`	Always	Source that generated the warning.
`message`	string	Always	Human-readable warning text for observability and fallback handling.

Example Request

cURLExample

curl -X POST "https://vetflow.nanocorp.app/api/scrape" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_PARTNER_KEY" \
  -d '{
    "city": "Columbus, OH",
    "source": "both"
  }'

Example Response

JSONExample

{
  "ok": true,
  "city": "Columbus, OH",
  "leads": [
    {
      "id": "8d2477df-3ac4-4f3e-9730-98674fe4a31d",
      "city": "Columbus, OH",
      "source": "craigslist",
      "name": "2 bed / 1 bath duplex ready now",
      "contact": "614-555-0139",
      "url": "https://columbus.craigslist.org/apa/d/example-listing/1234567890.html",
      "rawData": {
        "title": "2 bed / 1 bath duplex ready now",
        "postedAt": "2026-04-29T14:08:00.000Z"
      },
      "scrapedAt": "2026-04-29T14:09:12.841Z"
    }
  ],
  "warnings": [
    {
      "source": "zillow",
      "message": "Zillow returned anti-bot protection for this market; no leads were parsed."
    }
  ]
}

Deployment

White-label & Integration Notes

NestDash can integrate VetScore in two practical ways: a fast hosted embed for near-term launch, or an API-first implementation for deeper product ownership.

Option 1

Hosted iframe

Fastest path for a pilot. VetFlow can host the screening experience and NestDash can embed it in an iframe or modal container inside its existing landlord workflow. This keeps score logic on the VetFlow side and minimizes frontend work.

Option 2

API-first

Best fit when NestDash wants full control of UI and data orchestration. Collect applicant and property data in NestDash, call `POST /api/free-screening`, then render the returned VetScore, factors, and recommendation directly in the NestDash product.

Webhooks roadmap

Webhook delivery is on the near-term partner roadmap for asynchronous events such as screening completion, rescore, and scrape-job completion. The intended model is a partner-managed HTTPS endpoint with signed event delivery and retry support.

Today, the recommended integration is synchronous request/response. Once webhooks are live, NestDash will be able to receive events without polling and update its UI automatically.

Commercial

Rev-share Program

VetFlow offers a partner rev-share for referred conversions.

NestDash can enroll in a 20% to 30% revenue share on referred conversions. To activate the program, contact alex@vetflow.com.