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 metered call
bash
curl 'https://api.boardwalkai.com/api/v1/projects/search?states=UT&assetClasses=Apartment%20Building&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
],
"createdAt": "2026-05-04T00:00:00Z",
"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"
],
"propertyType": "residential",
"propertyTypeLabel": "Residential",
"propertySubtype": "multifamily",
"propertySubtypeLabel": "Multifamily",
"assetClass": "Apartment Building",
"assetClassLabel": "Apartment Building",
"status": "approved_with_conditions",
"statusLabel": "Approved with Conditions",
"statusDetail": "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,
"unitCount": [
{
"count": 240,
"type": "apartment",
"typeLabel": "Apartment"
}
],
"totalUnitCount": 240,
"existingZoning": "A-1",
"proposedZoning": "RM-16",
"isRezone": true,
"constructionType": "new_building",
"constructionTypeLabel": "New Building",
"ownerType": "private",
"ownerTypeLabel": "Private",
"constructionDescription": "A 240-unit garden-style apartment community on 9.8 acres.",
"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",
"emailConfidence": "high",
"emailSource": "filing",
"phone": "+1-555-0142",
"phoneConfidence": "high",
"phoneSource": "filing",
"linkedinUrl": null,
"linkedinConfidence": 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"
},
"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.",
"voteSummary": {
"yes": 2,
"no": 1,
"abstain": 0,
"absent": 1,
"total": 4,
"isUnanimous": false,
"meetingDate": "2026-06-17"
}
}
],
"meta": {
"schemaVersion": "2026-08-02",
"representation": "standard",
"total": 1,
"limit": 1,
"offset": 0,
"creditsUsed": 1,
"creditsRemaining": 299,
"trialTruncation": null,
"searchMethod": "redisearch",
"appliedFilters": {
"states": [
44
],
"assetClasses": [
"Apartment Building"
]
},
"appliedDefaults": [
"dateRange=last_1_year"
],
"resolvedFrom": {
"states": {
"UT": 44
}
},
"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"
]
},
{
"code": "filter_evidence_unconfirmed",
"message": "These filters currently match our full index. A returned record with a null value for the attribute you filtered on is a record we could not confirm.",
"params": [
"assetClasses"
]
}
],
"matchCount": 250,
"matchCountIsExact": true,
"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.
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
],
"createdAt": "2026-06-02T00:00:00Z",
"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": [],
"propertyType": "residential",
"propertyTypeLabel": "Residential",
"propertySubtype": "multifamily",
"propertySubtypeLabel": "Multifamily",
"assetClass": null,
"assetClassLabel": null,
"status": "continued",
"statusLabel": "Continued",
"statusDetail": "The item was continued; no decision was recorded.",
"requestType": "concept_plan",
"requestTypeLabel": "Concept Plan",
"decisionBody": "Planning Commission",
"caseNumbers": [],
"acreage": null,
"unitCount": [],
"totalUnitCount": null,
"existingZoning": null,
"proposedZoning": null,
"isRezone": null,
"constructionType": null,
"constructionTypeLabel": null,
"ownerType": null,
"ownerTypeLabel": null,
"constructionDescription": null,
"developerCompany": null,
"developerCompanyRole": null,
"developerCompanyRoleLabel": null,
"contacts": [],
"contactEnrichment": {
"status": "not_requested",
"statusLabel": "Not Requested",
"attemptedAt": null,
"contactsFound": 0,
"source": "registry"
},
"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.",
"voteSummary": null
}
],
"meta": {
"schemaVersion": "2026-08-02",
"representation": "standard",
"total": 1,
"limit": 1,
"offset": 0,
"creditsUsed": 1,
"creditsRemaining": 294,
"trialTruncation": null,
"searchMethod": "redisearch",
"appliedFilters": {
"states": [
44
],
"cities": [
31955
]
},
"appliedDefaults": [
"dateRange=last_1_year"
],
"resolvedFrom": {
"states": {
"UT": 44
},
"cities": {
"Provo": 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": 61,
"matchCountIsExact": true,
"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 cost1 credit per record deliveredCharged for the records actually delivered on the page, after duplicate projects are collapsed and after records you already hold unchanged are excluded. Zero results cost nothing.
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 and a sandbox key. Counting, filtering, the location tree and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.