Collections

A collection is a saved configuration that defines which data points to pull from the Fordje platform. Think of it as a reusable template — you define the set of questions once, then run it against any group of AHJs on demand. Collections bundle two things into a named, reusable package:

Data point type IDs — the specific regulatory questions you want answered (e.g., “Is a permit required?”, “What is the minimum insulation R-value?”)
Category IDs — the regulatory topics the data points belong to (e.g., Permitting, Inspections, Building Standards)

You create collections in the Fordje platform and access them read-only through the API. This separation keeps your integration simple — your code never needs to manage collection definitions, just execute them.

The workflow

Collections follow a define-once, run-anywhere pattern:

Define a collection in the Fordje platform. Pick the data point types and categories you care about, give it a name and description. For example, you might create a “Permitting Requirements” collection that includes data point types for permit applications, fee schedules, and turnaround times across the Permitting category.
Execute the collection via the API. Pass in a set of AHJ IDs and the API returns only the data points that match the collection’s filters. You can run the same collection against different AHJs each time — new project in a new city, same collection, fresh results.
Optionally export as CSV. If your downstream tools (spreadsheets, project management systems, compliance trackers) need a flat file, you can export the collection results as CSV directly from the API.

Collections are scoped to your organization. You can only see and execute collections that belong to your org, and results are further filtered to AHJs in your subscription. See AHJ access control for details.

When to use collections vs ad-hoc queries

Both approaches give you access to the same underlying data. The difference is in how you specify what you want. Use collections when:

You pull the same set of data points regularly — every new project needs the same permit data, every quarterly audit checks the same compliance fields
Multiple team members or systems need to run the same query — the collection acts as a shared definition
You want to keep your API calls consistent and avoid drift between integrations

Use ad-hoc queries when:

You are doing exploratory work — browsing what data is available for a new jurisdiction
You need a one-off lookup that does not fit an existing collection
You are prototyping and the set of data points you need is still changing

Start with ad-hoc queries on GET /v1/data-points to explore what is available. Once you know which data point types and categories you need repeatedly, create a collection in the Fordje platform and switch your integration to use it.

Working with collections

List your collections

To see all collections your organization has created, call the list endpoint:

curl -X GET "https://connect.fordje.com/v1/collections?page_size=10" \
  -H "X-API-Key: your-api-key"

{
  "response_type": "success",
  "description": "Retrieved 2 collection(s)",
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "organization_id": "org-uuid-here",
        "name": "Permitting Requirements",
        "description": "Permit applications, fees, and turnaround times",
        "data_point_type_ids": [10, 11, 12],
        "category_ids": [53],
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-15T12:00:00Z"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "organization_id": "org-uuid-here",
        "name": "Solar Installation Basics",
        "description": "Setback, interconnection, and permitting for residential solar",
        "data_point_type_ids": [20, 21, 22, 23],
        "category_ids": [16],
        "created_at": "2025-02-01T00:00:00Z",
        "updated_at": "2025-02-10T09:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 2,
      "total_pages": 1
    }
  }
}

The data_point_type_ids and category_ids fields tell you exactly what filters the collection applies. You can cross-reference these with the reference data endpoints — GET /v1/data-points/types and GET /v1/categories — to see their human-readable names.

Execute a collection

To run a collection against a set of AHJs, call the data endpoint with the AHJ IDs you want to query:

curl -X GET "https://connect.fordje.com/v1/collections/a1b2c3d4-e5f6-7890-abcd-ef1234567890/data?ahj_ids=1,2,3&page_size=10" \
  -H "X-API-Key: your-api-key"

{
  "response_type": "success",
  "description": "Collection 'Permitting Requirements' executed: 6 result(s)",
  "data": {
    "collection_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "collection_name": "Permitting Requirements",
    "items": [
      {
        "id": 1001,
        "ahj": { "id": 1, "name": "City of Los Angeles" },
        "data_point_type": {
          "id": 10,
          "name": "Permit Required",
          "unit_of_measure": "boolean",
          "category_ids": [53]
        },
        "value": "Yes",
        "reference": "Los Angeles Municipal Code",
        "section": "91.106.1.1",
        "updated_at": "2025-01-10T08:30:00Z"
      },
      {
        "id": 1002,
        "ahj": { "id": 2, "name": "City of Houston" },
        "data_point_type": {
          "id": 10,
          "name": "Permit Required",
          "unit_of_measure": "boolean",
          "category_ids": [53]
        },
        "value": "Yes",
        "updated_at": "2025-01-12T14:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 6,
      "total_pages": 1
    }
  },
  "warnings": null
}

The response contains the matching published data point values, each tied to its AHJ and data point type. If any of the AHJ IDs you pass are outside your subscription, you will still get results for the ones you have access to, with a warnings array listing the excluded IDs.

Target by geoID instead of AHJ IDs

ahj_ids is optional. As an alternative, pass geoids — a comma-separated list of Census GEOIDs — and the API resolves them to AHJs for you. Provide exactly one of ahj_ids or geoids:

curl -X GET "https://connect.fordje.com/v1/collections/a1b2c3d4-e5f6-7890-abcd-ef1234567890/data?geoids=17031,06001&page_size=10" \
  -H "X-API-Key: your-api-key"

GeoIDs are case-sensitive strings with significant leading zeros (06001, not 6001). Send them as-is — do not strip leading zeros.

Rules:

Request	Result
Both `ahj_ids` and `geoids` provided	`422` validation error (“Provide either ahj_ids or geoids, not both”)
Neither provided	`422` validation error (“Provide either ahj_ids or geoids”)
`geoids` provided but none resolve to an AHJ	`422` validation error (“No AHJs matched these geoids”)
Some `geoids` resolve, some do not	`200` with results for the matched ones, plus a warning carrying `unmatched_geoids`

When some geoIDs fail to resolve, the response stays 200 and reports them in the warnings array alongside any access exclusions:

{
  "response_type": "success",
  "data": { "items": ["..."], "pagination": { "...": "..." } },
  "warnings": [
    {
      "code": "GEOID_UNMATCHED",
      "message": "Some geoIDs did not resolve to an AHJ",
      "unmatched_geoids": ["9999999"]
    }
  ]
}

Run a collection for a single geoID

To run a collection against one jurisdiction by geoID, use the /v1/geoid/{geoid} namespace. The response shape is identical to GET /v1/collections/{id}/data, scoped to that single AHJ, and it inherits the page/page_size params:

curl -X GET "https://connect.fordje.com/v1/geoid/17031/collections/a1b2c3d4-e5f6-7890-abcd-ef1234567890?page_size=10" \
  -H "X-API-Key: your-api-key"

An unknown geoID returns 404; a resolved AHJ outside your subscription returns 403.

Export as CSV

For workflows that need flat files, you can export a collection’s results directly as CSV:

curl -X POST "https://connect.fordje.com/v1/collections/a1b2c3d4-e5f6-7890-abcd-ef1234567890/export?ahj_ids=1,2" \
  -H "X-API-Key: your-api-key" \
  -o permitting_requirements_export.csv

The response is a CSV file with a Content-Type: text/csv header. The filename in the Content-Disposition header is based on the collection name, so saving with -o gives you a clean local file for import into spreadsheets or other tools.

CSV exports apply the same AHJ access controls as the data endpoint. You only get data for jurisdictions in your subscription.

CSV export accepts the same geoids alternative to ahj_ids (exactly one of the two), and a single-geoID export is available under the geoID namespace:

curl -X POST "https://connect.fordje.com/v1/geoid/17031/collections/a1b2c3d4-e5f6-7890-abcd-ef1234567890/export" \
  -H "X-API-Key: your-api-key" \
  -o permitting_requirements_cook_county.csv

CSV export does not return a JSON body, so it cannot surface partial warnings — geoIDs that do not resolve are silently skipped. If every supplied geoID fails to resolve, the export fails with 422 instead. To see exactly which geoIDs resolved, call the /data endpoint first.

Next steps

List collections

Full API reference for GET /v1/collections — list your organization’s saved collections.

Execute a collection

Full API reference for GET /v1/collections/{id}/data — run a collection against AHJs.

Getting started

Core concepts

Guides

The workflow

When to use collections vs ad-hoc queries

Working with collections

List your collections

Execute a collection

Target by geoID instead of AHJ IDs

Run a collection for a single geoID

Export as CSV

Next steps

List collections

Execute a collection

​The workflow

​When to use collections vs ad-hoc queries

​Working with collections

​List your collections

​Execute a collection

​Target by geoID instead of AHJ IDs

​Run a collection for a single geoID

​Export as CSV

​Next steps

List collections

Execute a collection

The workflow

When to use collections vs ad-hoc queries

Working with collections

List your collections

Execute a collection

Target by geoID instead of AHJ IDs

Run a collection for a single geoID

Export as CSV

Next steps