API Reference

Fordje Connect is a RESTful API that provides programmatic access to AHJ (Authority Having Jurisdiction) data, code requirement data points, reports, and saved collections. All endpoints return JSON and are versioned under /v1/.

Base URL

https://connect.fordje.com

Authentication

Every request to a /v1/ endpoint must include your API key in the X-API-Key header:

curl -X GET "https://connect.fordje.com/v1/ahjs" \
  -H "X-API-Key: your-api-key"

API keys are managed through the Fordje platform. See the Authentication guide for details on key management and security best practices.

Endpoints

AHJs

Method	Endpoint	Description
`GET`	`/v1/ahjs`	List AHJs in your subscription
`GET`	`/v1/ahjs/{ahj_id}`	Get full detail for a single AHJ

GeoID

Method	Endpoint	Description
`GET`	`/v1/geoid/{geoid}`	Resolve a Census GEOID to its AHJ (full detail)
`GET`	`/v1/geoid/{geoid}/collections/{collection_id}`	Run a saved collection against one geoID
`POST`	`/v1/geoid/{geoid}/collections/{collection_id}/export`	Export a collection for one geoID as CSV

Data Points

Method	Endpoint	Description
`GET`	`/v1/data-points`	Query data point values with filtering
`GET`	`/v1/data-points/types`	List available data point type definitions

Reference Data

Method	Endpoint	Description
`GET`	`/v1/categories`	List categories (e.g. Permitting, Inspections)
`GET`	`/v1/units-of-measure`	List units of measure for data point values

Reports

Method	Endpoint	Description
`POST`	`/v1/reports/matrix`	Generate an AHJ x data point comparison grid
`POST`	`/v1/reports/export`	Export a comparison report as CSV

Collections

Method	Endpoint	Description
`GET`	`/v1/collections`	List your organization’s saved collections
`GET`	`/v1/collections/{collection_id}`	Get a collection’s definition
`GET`	`/v1/collections/{collection_id}/data`	Execute a collection against AHJs (`ahj_ids` or `geoids`)
`POST`	`/v1/collections/{collection_id}/export`	Export collection results as CSV (`ahj_ids` or `geoids`)

Response format

All successful responses use a standard envelope:

{
  "response_type": "success",
  "description": "Human-readable result summary",
  "data": { ... },
  "warnings": []
}

Field	Type	Description
`response_type`	string	`"success"` or `"error"`
`description`	string	Human-readable summary of the result
`data`	object	The response payload
`warnings`	array or null	Access warnings when some requested AHJs were excluded (see below)

Pagination

List endpoints return paginated results. Control pagination with page and page_size query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`page_size`	integer	`100`	Items per page (max 500)

Every paginated response includes a pagination object in data:

{
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "page_size": 100,
      "total": 142,
      "total_pages": 2
    }
  }
}

Access warnings

When a request includes AHJ IDs that your subscription doesn’t cover, the API returns data for the authorized AHJs and includes a warnings array:

{
  "response_type": "success",
  "data": { ... },
  "warnings": [
    {
      "code": "AHJ_ACCESS_DENIED",
      "message": "Your subscription does not include the following AHJs",
      "excluded_ahj_ids": [45, 89]
    }
  ]
}

When you address collections by geoids, the warning can also include unmatched_geoids — the geoIDs that did not resolve to any AHJ:

{
  "code": "GEOID_UNMATCHED",
  "message": "Some geoIDs did not resolve to an AHJ",
  "unmatched_geoids": ["9999999"]
}

Single-AHJ endpoints (/v1/ahjs/{id}) return 403 outright if the AHJ isn’t in your subscription.

Error handling

Error responses follow the same envelope with additional fields:

{
  "response_type": "error",
  "description": "Access denied",
  "error": "AHJ_ACCESS_DENIED",
  "status_code": 403
}

Status codes

Code	Meaning	When it happens
`401`	Unauthorized	Missing, invalid, expired, or revoked API key
`403`	Forbidden	AHJ not included in your subscription
`404`	Not found	Resource doesn’t exist or doesn’t belong to your organization
`422`	Validation error	Invalid request parameters (details in `details` array)
`429`	Rate limited	Too many requests — see Rate Limits below
`500`	Server error	Unexpected internal error
`502`	Bad gateway	Backend service unavailable

Rate limits

Requests are rate-limited per API key across three windows:

Window	Limit
Per minute	60
Per hour	1,000
Per day	10,000

Every response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the current window resets
`Retry-After`	Seconds until the current window resets

When the limit is exceeded, the API returns 429 Too Many Requests. See Rate Limiting for strategies on handling limits.

Overview

AHJs

GeoID

Data Points

Reference Data

Reports

Collections

Utility

Base URL

Authentication

Endpoints

AHJs

GeoID

Data Points

Reference Data

Reports

Collections

Response format

Access warnings

Error handling

Status codes

Rate limits

​Base URL

​Authentication

​Endpoints

​AHJs

​GeoID

​Data Points

​Reference Data

​Reports

​Collections

​Response format

​Pagination

​Access warnings

​Error handling

​Status codes

​Rate limits

Base URL

Authentication

Endpoints

AHJs

GeoID

Data Points

Reference Data

Reports

Collections

Response format

Pagination

Access warnings

Error handling

Status codes

Rate limits