GoliathDevelopersGet an API key
Guides / Properties API

Properties API

Search properties, count signal events, manage saved filters and folders, organize lists, and skip-trace owners through the Goliath developer API

About

Programmatic access to the property database: search by address, parcel, or MLS id, fetch property details and attributes, run your saved property filters, count signal events, organize properties with tags and lists, and skip-trace owners. Shared filter-authoring operations also support CONTACT and DEAL filters.

All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Operations

Lookup and search (READ scope)

operationId What it does
getProperty Fetch one property by id — address, skip-trace status, signal recency, and visible tags/lists, each with id, name, and isEditable. Lists include read-only system ingestion lists; only reuse list ids for writes when isEditable is true. Other organizations’ private tags/lists are excluded.
getPropertyOwners Fetch a property’s known people — owners and relatives from deed records and public-record signals, merged with your organization’s skip-trace results. Names can appear without a trace; phone numbers (incl. DNC status) and emails are generally populated only after skipTraceProperty. crmContacts lists your organization’s contacts already linked to the property — each with relation, matchedBy, the contact’s id, name, doNotContact, phones (with DNC status) and emails — so check it before creating a duplicate contact. Reading never consumes a credit.
getPropertySignals A property’s filings (newest 50) — the distress signals behind it, with the notice text in adBody. A row with suppressedReason set is not live.
findProperties Search properties by (partial) address. Returns address suggestions with the property id to use in getProperty.
findPropertiesByParcel Search properties by (partial) parcel id.
findPropertiesByMlsId Search properties by (partial) MLS id.
findPropertiesNearPoint The properties around a map point (latitude, longitude): the parcel the point falls on first, then the nearest buildings within about 150 m, each with id, address, owner of record and estimated value. limit defaults to 5 (max 10).
getRelatedProperties Batch property attributes by id — beds/baths/size, year built, last sale, estimated value, occupancy.
getZoningCodes List the zoning codes available for a location (state + city id or county FIPS).
searchCities Find US cities by (partial) name — returns each match’s id, name, and state. This is how you identify a city for a filter. Include the state in the term (e.g. Memphis TN) when a name is common. Capped at 10 matches.
searchCounties Find US counties by (partial) name — returns each match’s name, fullName, state, and 5-digit fips. Include the state in the term (e.g. Orange County FL) when a name is common. Capped at 10 matches.

Signal event counts (READ scope)

operationId What it does
countPropertySignals Count signal events in an area using a saved property filterId or inline filterTree. Optional signalTypes narrows the types; from and to are inclusive publication days (YYYY-MM-DD), with open ends when omitted. Returns totalEvents, distinct propertyCount, and byType with events and properties per type. Read-only; spends no credits. Pass inSavedAreas: true to count only inside the organization’s saved areas of operation (an organization with none is refused, never widened).

An event is a property’s signal of one type on one publication day; one property can contribute several events. Standing conditions such as absentee ownership are not events. This differs from filterProperties.total, which counts distinct matching properties. Express the area in the PROPERTY filter DSL: use a county’s fips from searchCounties or a city’s id from searchCities. includeIncompleteRecords widens the same completeness gate as on filterProperties.

Saved filters (READ + WRITE scopes)

filterProperties checks the resolved criteria against your organization’s plan, for both saved filterId and inline filterTree requests. A field the plan excludes causes an operation error with code PLAN_ENTITLEMENT_REQUIRED; it does not return an empty match set. Saving a filter does not preserve access to a feature your plan no longer includes.

operationId Scope What it does
listPropertyFilters READ List saved property filters visible to the key owner: shared organization filters plus their own private ones. Rows include the owner’s userId; check it before changing a teammate’s filter. Read the definition separately with getFilter.
listFilterFieldNames READ The compact vocabulary of filterable fields for CONTACT, PROPERTY, or DEAL: fieldId, label, category, and component. Use this to discover names before fetching authoring details; it does not return hidden.
listFilterFields READ Full authoring metadata for selected fields — component, options, hidden, retired, and valueShapes, including each mutually exclusive union arm and its required keys. fieldIds is required — discover names with listFilterFieldNames first and narrow here.
getFilter READ Fetch one saved CONTACT, PROPERTY, or DEAL filter by id including its full root criteria tree. Also returns queryOptions; a property’s includeIncompleteRecords option changes execution outside the criteria tree.
filterProperties READ Run a saved filterId or an unsaved filterTree with limit/offset pagination (default 25, max 100). Returns a page plus total/hasMore. Supports sort: { field, direction } and includeIncompleteRecords. inSavedAreas: true ANDs in the organization’s saved areas (regions and drawn polygons) on the server.
saveFilter WRITE Create a saved filter with type: CONTACT, PROPERTY, or DEAL, for filterContacts, filterProperties, or filterDeals. Optionally set folderId. Parses root strictly — an unknown field or invalid value rejects the save. Relay any returned warnings; they are non-fatal advisories about criteria such as same-named counties across states. For a PROPERTY filter, inSavedAreas: true saves it inside the organization’s saved areas — pass the same flag you counted with.
updateFilter WRITE Edit a saved filter in place by id (any type). This is how you change its criteria, name, description, folder, or visibility — calling saveFilter again creates a second filter. Everything except the id is optional; root replaces the whole tree and is strictly validated. Relay returned warnings. inSavedAreas works as on saveFilter.
deleteFilter WRITE Delete a saved filter by filterId (any type — property, contact, or deal). Returns true when a row was deleted. A filter outside your organization (or an unknown id) is rejected with 403 forbidden.
listFilterFolders READ List folders for type: PROPERTY, CONTACT, or DEAL, including empty folders: shared organization folders plus your own private ones. Rows include parentId, isPrivate, and displayOrder.
createFilterFolder WRITE Create a folder with scope: PROPERTY, CONTACT, or DEAL and name. personal: true makes a root folder private; otherwise it is shared. A child created with parentId inherits the parent’s visibility. Returns the folder id.
renameFilterFolder WRITE Rename a filter folder (folderId from listFilterFolders). Renaming onto a sibling’s name merges into it.
deleteFilterFolder WRITE Delete a filter folder; its contents move up a level.

File a filter with saveFilter.folderId or updateFilter.folderId; explicit null on update removes it from its folder. Reuse a folder only when its name, parent, and privacy match. Deal filters run over one separately supplied pipeline; see the Deals API.

filterProperties.sort.direction is ASC or DESC. Supported fields are spicy_lead_score, estimated_value_dollars, estimatedRent, last_property_signal_date (or lastPropertySignalDate), closed_date (or closedDate), unit_count (or unitCount), latestListingStatusDate (or z_latest_listing_status_date), fsboListedDate, frboListedDate, fsboListingRemovedDate, frboListingRemovedDate, listingRemovedDate, listingRemovedRentDate, listingRemovedSaleDate, and auction_date (earliest upcoming auction, properties with none last). Unknown fields are silently ignored, leaving the default order.

includeIncompleteRecords: true includes properties normally hidden because they lack both parcel identity and a signal. It widens results and cannot turn off the same option already enabled in a saved filter’s queryOptions. Use the same option when previewing and submitting a filter-based list action.

Saved-filter groups can carry negated: true to invert the whole group, including its nested groups and conditions. It is a group-level option; omitting it leaves the group uninverted.

Tags and lists (READ + WRITE scopes)

operationId Scope What it does
searchPropertyTags READ Search property tags and lists by name. Use a tag id with addPropertyTags, a list id with addPropertiesToList.
addPropertyTags WRITE Add existing tag(s) (by tag id) to a property.
removePropertyTag WRITE Remove one tag (by tag id) from a property.
addPropertiesToList WRITE Add properties to one or more listIds, using explicit propertyIds or a filter selection. Async — returns mode and bulkTaskId; poll getBulkTask before reading back membership.
createPropertyList WRITE Get or create an org-wide property list by exact listName. Returns list { id, name } and created — report a new list only when created is true.
removePropertiesFromList WRITE Remove properties from one listId, using the same selection rules as adding. Async; poll getBulkTask. Missing membership is skipped. The list and properties themselves are preserved.

Selecting properties for a list action

Both list actions require totalCount and accept one selection form:

  • Explicit ids: send propertyIds and their count as totalCount. Omit filter and selection-window fields. To exclude a property, leave its id out.
  • Filter: send either filterId or filterTree, plus either selectAll: true or selectCount: N. A filter without either window, or with both, is rejected. Optional excludeIds applies only to this form. A saved filter must be visible to the key owner; an inline tree is strictly validated, so unknown field ids reject the call.

For select-all, read filterProperties first and pass its unsubtracted total as totalCount. This is an execution cap: understating it stops the job early. Exclusions are handled by the worker; do not subtract them. For explicit ids or selectCount, the server derives the cap from the id count or N, but totalCount remains a required, non-negative input.

selectCount takes the first N in the worker’s default traversal order; it does not use a preview’s sort. For a sorted top-N, pass the sorted page’s explicit ids. Keep includeIncompleteRecords consistent with the preview, and review the match count before submitting a filter selection that could affect thousands of properties.

Skip tracing (ADMIN scope)

operationId What it does
skipTraceProperty Skip-trace a property to discover its owner + phone numbers/emails. Returns the discovered people inline; re-read them later (free) with getPropertyOwners. Consumes one skip-trace credit (real money).
manualSkiptrace Skip-trace an explicitly-provided owner + mailing address. Consumes one skip-trace credit.
createContactFromProperty Create a CRM contact from a property. Triggers skip-trace enrichment — consumes one skip-trace credit.

Comparable sales (WRITE scope)

operationId What it does
runPropertyComparables Comparable sales for a property (its id from a property read), as the property page’s Comps tab does: each comp’s facts, distance and price per square foot, plus the medians and the subject’s implied value. Optional criteria narrow the comps; every bound you send is required. Spends no credits.

Folders (READ + WRITE scopes)

Folders organize saved filters, lists, forms, content templates, library files and workflow groups. Each surface (scope) has an organization-wide shared tree plus each user’s personal tree.

operationId Scope What it does
listFolders READ Every folder on one surface (scope, any FolderScope including FORM), as a flat list: the shared tree plus the key owner’s personal one, with ownerUserId, parentId, displayOrder and itemCount.
renameFolder WRITE Rename a folder on any surface (folderId from listFolders). A name already used by a sibling is refused.
moveFolder WRITE Re-parent a folder (parentId, null for the root). Refused across personal and shared trees, into itself, or past the depth limit.
deleteFolder WRITE Delete a folder on any surface. Irreversible; its subfolders and items always move up a level.
moveItemsToFolder WRITE File filters, lists, forms, templates, library files or workflow groups into a folder (folderId, null to unfile), all or nothing. A filter’s privacy follows the folder it lands in.
reorderFolders WRITE Rewrite the order of one sibling set, identified by scope, parentId and personal; pass every sibling id in orderedIds.
reorderFolderItems WRITE Order the items inside one folder. Templates and forms are refused.
reorderFilters WRITE Set the display order of saved filters. Every filterId is org-guarded.

Data coverage requests (READ + WRITE + ADMIN scopes)

Ask Goliath to start collecting a property signal where your organization works. The current coverage of each signal is on the Coverage API.

operationId Scope What it does
listMyCoverageRequests READ Your organization’s coverage requests: signal family and county (countyFips), when it was asked, status, expectedBy and liveSince. Read it before asking again.
requestCoverage WRITE Ask for coverage of places (locations, e.g. "Cook County, IL"; anything that is not a county comes back in gaps) for signals by name (signals, send [] when asking by family) or for whole families: FORECLOSURE, PREFORECLOSURE, PROBATE, PREPROBATE, TAX_DELINQUENCY, CODE_VIOLATION. A family already requested is not requested again. Any other signal is recorded, but no read returns it.
requestSignalsInMyCounties WRITE Ask for signal types that are not live yet in every county your organization works, as the builders’ “Request it” button does. Optional context names what was being built (workflowGroup:<id>, filter:<id>).
cancelCoverageRequest ADMIN Withdraw your organization’s request for one family in one county (countyFips). The request is deleted; asking again starts a new one. Returns false when there was none. The key owner must be an org admin.

Example

Run a saved filter and page through the matches:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "listPropertyFilters", "variables": {} }'

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "filterProperties", "variables": { "filterId": "FILTER_ID", "limit": 50, "offset": 0 } }'

Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.