Reading a record
A field-by-field walkthrough of one project record — including the fields that come back empty, and why.
Data and PropTech platformsHomebuilders and developers
Who this is for
Anyone mapping Boardwalk records into their own schema. Read this once and the field dictionary becomes a lookup rather than a puzzle.
One record, in full
Your first search
bash
curl 'https://api.boardwalkai.com/api/v1/projects/search?states=UT&assetClasses=Apartment%20Building&meetingDateFrom=2026-05-01&totalUnitCountMin=50&limit=1' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY'Response · HTTP 200
json
{
"data": [
{
"id": 184203,
"recordType": "project",
"projectName": "Alta Ridge Phase II",
"projectHeadline": "Planning Commission approved 240 apartments with conditions",
"boardwalkLink": "https://boardwalkai.com/map/#project=184203",
"mergedFrom": [
184203,
184987
],
"lastUpdated": "2026-06-18T09:22:41Z",
"meetingDate": "2026-06-17",
"delivery": {
"alreadyExported": false,
"updatedSinceExport": null,
"lastExportedAt": null,
"billed": true
},
"address": "3600 S Constitution Blvd, West Valley City, UT",
"city": "West Valley City",
"county": "Salt Lake",
"state": "UT",
"postalCode": "84119",
"latitude": 40.6916,
"longitude": -112.0011,
"locationPrecision": "address",
"locationPrecisionLabel": "Address",
"isApproximate": false,
"parcelApn": [
"15-27-301-004"
],
"inOpportunityZone": true,
"inFemaFloodZone": false,
"propertyType": "residential",
"propertyTypeLabel": "Residential",
"propertySubtype": "multifamily",
"propertySubtypeLabel": "Multifamily",
"assetClass": "Apartment Building",
"assetClassLabel": "Apartment Building",
"leadType": "private",
"leadTypeLabel": "Private",
"stage": "entitlement",
"stageLabel": "Entitlement",
"landUses": [
{
"type": "residential",
"typeLabel": "Residential",
"subtype": "multifamily",
"subtypeLabel": "Multifamily",
"assetClass": "Apartment Building",
"assetClassLabel": "Apartment Building",
"matchedOn": []
}
],
"status": "approved_with_conditions",
"statusLabel": "Approved with Conditions",
"statusSummary": "The commission approved the preliminary plat subject to eight conditions.",
"requestType": "final_plat",
"requestTypeLabel": "Final Plat",
"decisionBody": "Planning Commission",
"caseNumbers": [
"PLAT-2026-0142"
],
"acreage": 9.8,
"squareFootage": null,
"unitMix": [
{
"count": 240,
"type": "apartment",
"typeLabel": "Apartment"
}
],
"totalUnitCount": 240,
"bedroomCount": null,
"buildingStories": null,
"floorCount": null,
"buildingHeightFeet": null,
"parkingSpaces": 372,
"existingZoning": "A-1",
"proposedZoning": "RM-16",
"isRezone": true,
"constructionType": "new_building",
"constructionTypeLabel": "New Building",
"projectSize": null,
"projectSizeLabel": null,
"developerCompany": "Alta Ridge Development LLC",
"developerCompanyRole": "developer",
"developerCompanyRoleLabel": "Developer",
"contacts": [
{
"name": "Rachel Okafor",
"title": "Director of Development",
"role": "developer",
"roleLabel": "Developer",
"partyClass": "external",
"partyClassLabel": "External Party",
"entityType": "person",
"company": "Alta Ridge Development LLC",
"email": "r.okafor@example.com",
"emailSource": "filing",
"phone": "+1-555-0142",
"phoneSource": "filing",
"linkedinUrl": null,
"linkedinSource": null,
"contactProvenance": "filing",
"enrichmentSource": null,
"enrichedAt": null,
"enrichmentStatus": "not_requested",
"contactsWithheldReason": null
}
],
"contactEnrichment": {
"status": "not_requested",
"statusLabel": "Not Requested",
"attemptedAt": null,
"contactsFound": 0,
"source": "registry"
},
"companyEnrichment": [],
"publicOfficials": [
{
"name": "Dana Whitfield",
"title": "Senior Planner",
"role": "city_planner",
"roleLabel": "City Planner",
"partyClass": "government",
"organization": "West Valley City"
}
],
"contactSummary": {
"externalCount": 1,
"governmentCount": 1,
"unclassifiedCount": 0,
"withEmail": 1,
"withPhone": 1,
"withLinkedin": 0,
"enrichedCount": 0,
"lowConfidenceWithheld": 0,
"withheldCount": 0,
"withheldReason": null
},
"keyFacts": [
{
"fact": "240 apartment units across six buildings",
"category": "unit_mix",
"categoryLabel": "Unit Mix"
}
],
"evidence": "Commissioner Reyes moved to approve subject to conditions 1-8.",
"summary": "A 240-unit garden-style apartment community on 9.8 acres.",
"voteSummary": {
"yes": 2,
"no": 1,
"abstain": 0,
"absent": 1,
"total": 4,
"isUnanimous": false,
"meetingDate": "2026-06-17"
},
"sourceDocumentUrl": "https://www.example-city.gov/media/agendas/2026-06-17-planning-commission-packet.pdf"
}
],
"meta": {
"schemaVersion": "2026-09-16",
"representation": "standard",
"total": 1,
"pageCount": 1,
"hasMore": true,
"limit": 1,
"offset": 0,
"creditsUsed": 0,
"creditsRemaining": 2500,
"trialTruncation": null,
"searchMethod": "redisearch",
"appliedFilters": {
"states": [
1
],
"assetClasses": [
"Apartment Building"
],
"meetingDateFrom": "2026-05-01T00:00:00+00:00",
"totalUnitCountMin": 50
},
"appliedDefaults": [
"taxonomyMatchMode=primary_only",
"includeGovernmentDecisions=false",
"leadTypes=private",
"sort=meetingDate",
"order=desc"
],
"resolvedFrom": {
"states": [
{
"input": "UT",
"id": 1
}
]
},
"warnings": [],
"matchCount": null,
"matchCountIsExact": false,
"matchCountBasis": "not_computed",
"duplicatesCollapsed": 0,
"collapseApplied": true,
"delivery": {
"mode": "all",
"notPreviouslyExported": 1,
"previouslyExported": 0,
"updatedSinceExport": 0,
"billed": 0,
"notRebilled": 1,
"ledgerApplied": true
}
}
}Record bodies on this page were produced by running Boardwalk's production response mapper over a documented sample project, so the field set, the labels and the empty fields are exactly what the API emits. The project itself is a sample, not a real filing.
The five conventions
| Convention | What it looks like | Why |
|---|---|---|
| Enums ship twice | "status": "approved_with_conditions" beside "statusLabel": "Approved with Conditions" | The token is frozen and safe to branch on. The label is display copy and may be reworded. Changing a label is then not a breaking change. |
| Ids are integers | "id": 184203 | Not a numeric string. Every generated client and every MCP schema expects an integer, and mixing the two is the classic source of failed joins. |
| Timestamps are ISO-8601 | "lastUpdated": "2026-06-18T09:22:41Z" | One format across every date-time field. meetingDate is a plain calendar date because a meeting happened on a day, not at an instant. |
| The vocabulary is the CSV's | acreage, totalUnitCount, existingZoning | A column in your CSV export and a field in the API are the same concept under the same name, so reconciling an export against an API pull is a join, not a mapping exercise. |
| A merged record says so | "mergedFrom": [184203, 184987] | Two filings for one development are collapsed into one record and billed once. mergedFrom is how you reconcile against ids you held before the merge. |
Now read one we could not fully establish
This is the more important example of the two. Boardwalk extracts from meeting minutes, and minutes are not uniform: some record the acreage and the asset class, some do not. When our current extraction standard produced no value for an attribute, the field is empty. We do not fall back to an older or superseded reading of the same document to fill it.
A record we could not fully establish
bash
curl 'https://api.boardwalkai.com/api/v1/projects/search?states=UT&cities=Provo&limit=1' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY'Response · HTTP 200
json
{
"data": [
{
"id": 191774,
"recordType": "project",
"projectName": "Foothill Commons",
"projectHeadline": "Concept plan continued to a future meeting",
"boardwalkLink": "https://boardwalkai.com/map/#project=191774",
"mergedFrom": [
191774
],
"lastUpdated": "2026-06-24T14:08:03Z",
"meetingDate": "2026-06-23",
"delivery": {
"alreadyExported": false,
"updatedSinceExport": null,
"lastExportedAt": null,
"billed": true
},
"address": null,
"city": "Provo",
"county": "Utah",
"state": "UT",
"postalCode": "84606",
"latitude": 40.2338,
"longitude": -111.6585,
"locationPrecision": "city_centroid",
"locationPrecisionLabel": "City Centroid",
"isApproximate": true,
"parcelApn": [],
"inOpportunityZone": null,
"inFemaFloodZone": null,
"propertyType": "residential",
"propertyTypeLabel": "Residential",
"propertySubtype": "multifamily",
"propertySubtypeLabel": "Multifamily",
"assetClass": null,
"assetClassLabel": null,
"leadType": "private",
"leadTypeLabel": "Private",
"stage": "entitlement",
"stageLabel": "Entitlement",
"landUses": [
{
"type": "residential",
"typeLabel": "Residential",
"subtype": "multifamily",
"subtypeLabel": "Multifamily",
"assetClass": null,
"assetClassLabel": null,
"matchedOn": []
}
],
"status": "continued",
"statusLabel": "Continued",
"statusSummary": "The item was continued; no decision was recorded.",
"requestType": "concept_plan",
"requestTypeLabel": "Concept Plan",
"decisionBody": "Planning Commission",
"caseNumbers": [],
"acreage": null,
"squareFootage": null,
"unitMix": [],
"totalUnitCount": null,
"bedroomCount": null,
"buildingStories": null,
"floorCount": null,
"buildingHeightFeet": null,
"parkingSpaces": null,
"existingZoning": null,
"proposedZoning": null,
"isRezone": null,
"constructionType": null,
"constructionTypeLabel": null,
"projectSize": null,
"projectSizeLabel": null,
"developerCompany": null,
"developerCompanyRole": null,
"developerCompanyRoleLabel": null,
"contacts": [],
"contactEnrichment": {
"status": "not_requested",
"statusLabel": "Not Requested",
"attemptedAt": null,
"contactsFound": 0,
"source": "registry"
},
"companyEnrichment": [],
"publicOfficials": [],
"contactSummary": {
"externalCount": 0,
"governmentCount": 0,
"unclassifiedCount": 0,
"withEmail": 0,
"withPhone": 0,
"withLinkedin": 0,
"enrichedCount": 0,
"lowConfidenceWithheld": 0,
"withheldCount": 0,
"withheldReason": null
},
"keyFacts": [],
"evidence": "The chair continued the item to a date uncertain.",
"summary": "The item was continued; no decision was recorded.",
"voteSummary": null,
"sourceDocumentUrl": null
}
],
"meta": {
"schemaVersion": "2026-09-16",
"representation": "standard",
"total": 1,
"pageCount": 1,
"hasMore": true,
"limit": 1,
"offset": 0,
"creditsUsed": 1,
"creditsRemaining": 294,
"trialTruncation": null,
"searchMethod": "redisearch",
"appliedFilters": {
"states": [
1
],
"cities": [
31955
]
},
"appliedDefaults": [
"taxonomyMatchMode=primary_only",
"includeGovernmentDecisions=false",
"leadTypes=private",
"dateRange=last_1_year",
"sort=meetingDate",
"order=desc"
],
"resolvedFrom": {
"states": [
{
"input": "UT",
"id": 1
}
],
"cities": [
{
"input": "Provo",
"id": 31955
}
]
},
"warnings": [
{
"code": "default_date_window_applied",
"message": "No date filter was given, so the last 12 months of meetings were searched — the same window the product shows. Pass dateRange=all to search everything.",
"params": [
"meetingDateFrom"
]
}
],
"matchCount": null,
"matchCountIsExact": false,
"matchCountBasis": "not_computed",
"duplicatesCollapsed": 0,
"collapseApplied": true,
"delivery": {
"mode": "all",
"notPreviouslyExported": 1,
"previouslyExported": 0,
"updatedSinceExport": 0,
"billed": 1,
"notRebilled": 0,
"ledgerApplied": true
}
}
}Record bodies on this page were produced by running Boardwalk's production response mapper over a documented sample project, so the field set, the labels and the empty fields are exactly what the API emits. The project itself is a sample, not a real filing.
Note assetClass: null and acreage: null on a record that plainly has a property type and a subtype. That is the contract working. The alternative — inferring a plausible acreage — is how an API reports 1,500 acres for a 1,500 square-foot building, and once is enough to lose the account.
What it costs
Credit costFree — 0 creditsCounty, State, and National: free. Standalone API Only and the free trial: 1 credit per delivered record that is new to this pool or changed since last delivery; unchanged owned records are free. `format=csv` queues the full filter match and returns HTTP 202 with poll/download URLs. Find Contact Info is billed separately on County/State/National, and included on API Only records already purchased.
The record above cost 1 credit. It would have cost 1 credit in compact, and 1 credit in full with the meeting transcript attached. You are billed for the record, not the bytes.
Next
Ready to make a call?
A free Boardwalk trial includes API access, 50 record-export credits (search, CSV, MCP), and 5 Find Contact Info lookups. Counting, taxonomy, location lookups and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.