Launching soon in Gainesville. Get first access

Developers

Listings Ingestion API

Bulk-load or continuously sync listings using RESO Data Dictionary field names, idempotent retries, and clear, machine-readable errors.

RESO-aligned

Property and Media fields use RESO Data Dictionary 2.x names and lookups — map once from your MLS or CRM export.

Idempotent

Send an Idempotency-Key and retry freely. Same key + body replays the original response.

Dry runs

Add ?dryRun=true to validate payloads and get field-level errors without saving.

Moderated

New listings wait for review unless your key is trusted. Withdrawals apply instantly.

Quickstart

Create or update a listing

  1. 1

    Get an API key

    Keys are issued by the GNV.Properties team per data source. Keep them server-side.

  2. 2

    POST the listing

    Send one RESO Property object. Re-sending the same ListingKey updates it.

  3. 3

    Photos download automatically

    Each Media[].MediaURL is fetched in the background — check progress with GET.

  4. 4

    Review & publish

    After approval, your future updates go live on their own.

curl -X POST https://gnv.properties/api/v1/listings \
  -H "Authorization: Bearer $GNV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "ListingKey": "ACME-10442",
    "StandardStatus": "Active",
    "PropertyType": "Residential",
    "PropertySubType": "SingleFamilyResidence",
    "ModificationTimestamp": "2026-11-10T14:03:00Z",
    "UnparsedAddress": "611 NE 5th Ave",
    "City": "Gainesville",
    "PostalCode": "32601",
    "ListPrice": 479000,
    "BedroomsTotal": 3,
    "BathroomsFull": 2,
    "LivingArea": 1540,
    "Media": [
      { "MediaURL": "https://cdn.example.com/10442/front.jpg", "Order": 0,
        "ShortDescription": "White craftsman cottage with a covered porch" }
    ]
  }'

Bulk loads

Imports: up to 250 listings per request

Send { "value": [ … ] } (RESO Web API collection shape) or NDJSON. Every row is processed independently and reported with its own outcome: created, updated, unchanged, or error.

# Validate a file first (nothing is saved)
curl -X POST "https://gnv.properties/api/v1/imports?dryRun=true" \
  -H "Authorization: Bearer $GNV_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @listings.ndjson

# Then import (≤ 250 rows per request)
curl -X POST https://gnv.properties/api/v1/imports \
  -H "Authorization: Bearer $GNV_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  -H "Idempotency-Key: batch-2026-11-11-001" \
  --data-binary @listings.ndjson

Errors

RFC 9457 problem details

Every error is application/problem+json. Validation errors list each field with a machine-readable code.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://gnv.properties/developers#errors-validation-failed",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "LeaseRateFrequency", "code": "invalid_enum",
      "message": "LeaseRateFrequency must be Annually or Monthly." }
  ]
}
400Malformed JSON, bad parameter, or invalid Idempotency-Key
401Missing, invalid, or revoked API key
403Key lacks the required scope
404No listing/import with that id for your source
409Same Idempotency-Key still in progress — retry shortly
413More than 250 rows or 5 MB (imports) / 1 MB (single)
415Wrong Content-Type
422Validation failed (see errors[]), or Idempotency-Key reused with a different body
429Rate limit exceeded — wait Retry-After seconds
503Temporarily unavailable — retry with backoff and the same Idempotency-Key

Field mapping

RESO fields at a glance

ConceptRESO field(s)Notes
IdentityListingKeyYour stable id; upsert key (with your source system)
StatusStandardStatusActive, ComingSoon, ActiveUnderContract, Pending, Closed, Withdrawn, Expired, Canceled…
TypePropertyType · PropertySubTypeResidential, ResidentialLease, CommercialSale, CommercialLease, Land… · SingleFamilyResidence, Condominium, Office, Retail…
Sale priceListPriceRequired for sale types
Monthly rentListPriceFor ResidentialLease, ListPrice is the monthly rent
Commercial rateLeaseRate + LeaseRateUnit + LeaseRateFrequency24.5 + SquareFeet + Annually = $24.50/SF/yr; omit unit for a flat $/mo
ExpensesGNV_ExpenseStructure · GNV_ExpensesNoteGross, ModifiedGross, NNN, Unknown
AddressUnparsedAddress (or StreetNumber + StreetName) · UnitNumber · City · PostalCodeFlorida listings only
SizeLivingArea · BuildingAreaTotal · LotSizeAcresSquare feet; commercial uses BuildingAreaTotal
RoomsBedroomsTotal · BathroomsFull · BathroomsHalfHalf baths count as 0.5
PhotosMedia[].MediaURL · Order · ShortDescriptionhttps JPEG/PNG/WebP ≤ 15 MB; ShortDescription becomes alt text
ContactListAgentFullName · ListAgentEmail · ListAgentStateLicense · ListOfficeNameShown as the listing contact
FreshnessModificationTimestampOlder payloads are ignored
AreaGNV_AreaSlugdowntown, duck-pond, grove-street, midtown, northwest, uf-area, southeast, haile-plantation, tioga

Full schema, enums, and examples in the API reference. Standards: RESO Data Dictionary, RFC 9457, Idempotency-Key.

Building an AI agent integration?

  • Give the agent the OpenAPI spec (/api/v1/openapi.yaml) or /llms.txt as its tool definition.
  • Always dryRun first, fix every errors[] item, then submit.
  • Generate one Idempotency-Key per logical listing change and reuse it on retries.
  • Never invent facts. Omit unknown fields instead of guessing — missing data is fine, wrong data isn’t.
  • Write PublicRemarks that describe the property, not who it’s “for” (fair housing).

Data rights & limits

  • Submit only listings you’re authorized to market. MLS/IDX data requires a redistribution agreement.
  • Default rate limit: 120 requests/minute per key (see RateLimit-* headers). Use imports for bulk.
  • Up to 40 photos per listing; you must hold the rights to every image.
  • Need a key or higher limits? Contact us.