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
Get an API key
Keys are issued by the GNV.Properties team per data source. Keep them server-side.
- 2
POST the listing
Send one RESO Property object. Re-sending the same ListingKey updates it.
- 3
Photos download automatically
Each Media[].MediaURL is fetched in the background — check progress with GET.
- 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." }
]
} | 400 | Malformed JSON, bad parameter, or invalid Idempotency-Key |
| 401 | Missing, invalid, or revoked API key |
| 403 | Key lacks the required scope |
| 404 | No listing/import with that id for your source |
| 409 | Same Idempotency-Key still in progress — retry shortly |
| 413 | More than 250 rows or 5 MB (imports) / 1 MB (single) |
| 415 | Wrong Content-Type |
| 422 | Validation failed (see errors[]), or Idempotency-Key reused with a different body |
| 429 | Rate limit exceeded — wait Retry-After seconds |
| 503 | Temporarily unavailable — retry with backoff and the same Idempotency-Key |
Field mapping
RESO fields at a glance
| Concept | RESO field(s) | Notes |
|---|---|---|
| Identity | ListingKey | Your stable id; upsert key (with your source system) |
| Status | StandardStatus | Active, ComingSoon, ActiveUnderContract, Pending, Closed, Withdrawn, Expired, Canceled… |
| Type | PropertyType · PropertySubType | Residential, ResidentialLease, CommercialSale, CommercialLease, Land… · SingleFamilyResidence, Condominium, Office, Retail… |
| Sale price | ListPrice | Required for sale types |
| Monthly rent | ListPrice | For ResidentialLease, ListPrice is the monthly rent |
| Commercial rate | LeaseRate + LeaseRateUnit + LeaseRateFrequency | 24.5 + SquareFeet + Annually = $24.50/SF/yr; omit unit for a flat $/mo |
| Expenses | GNV_ExpenseStructure · GNV_ExpensesNote | Gross, ModifiedGross, NNN, Unknown |
| Address | UnparsedAddress (or StreetNumber + StreetName) · UnitNumber · City · PostalCode | Florida listings only |
| Size | LivingArea · BuildingAreaTotal · LotSizeAcres | Square feet; commercial uses BuildingAreaTotal |
| Rooms | BedroomsTotal · BathroomsFull · BathroomsHalf | Half baths count as 0.5 |
| Photos | Media[].MediaURL · Order · ShortDescription | https JPEG/PNG/WebP ≤ 15 MB; ShortDescription becomes alt text |
| Contact | ListAgentFullName · ListAgentEmail · ListAgentStateLicense · ListOfficeName | Shown as the listing contact |
| Freshness | ModificationTimestamp | Older payloads are ignored |
| Area | GNV_AreaSlug | downtown, 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.txtas its tool definition. - Always
dryRunfirst, fix everyerrors[]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
PublicRemarksthat 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.