Partner API

The Benefits Wayfinder Partner API provides approved partner organizations with secure access to published Benefits Wayfinder content.

Intended use

The Partner API is intended for approved organizations with specific use cases, such as incorporating selected Benefits Wayfinder content into an existing website, service, or digital tool. It is designed for periodic, low-volume access to published benefit information rather than high-volume or general-purpose data distribution.

Organizations requiring broader datasets, high-volume access, or other integration patterns should contact the Benefits Wayfinder team to discuss their needs.

Getting started

Partner applications can retrieve published benefit content from the Partner API without accessing the internal Benefits Wayfinder Contentful environment.

Base URL:

https://hub.benefitswayfinder.org

Current API version:

/api/v1

Initial endpoint:

GET /api/v1/benefits

Authentication

All API requests require an API key.

Send the key using the following request header:

x-api-key: bw_live_your_api_key

Example:

GET /api/v1/benefits?province=ON&lang=en
x-api-key: bw_live_your_api_key

Keep API keys secure.

Do not expose API keys in public client-side code or commit them to source control. If a key is lost or compromised, contact Prosper Canada to have it revoked and replaced.

Benefits endpoint

GET /api/v1/benefits

Returns published Benefits Wayfinder benefit content.

Query parameters

Parameter	Required	Description
`lang`	No	`en` or `fr`. Defaults to `en`.
`province`	No	Province or federal code, such as `ON`, `QC`, or `CA`.
`city`	No	City name, such as `Waterloo` or `Toronto`.
`limit`	No	Number of records to return. Default `100`, maximum `500`.
`offset`	No	Pagination offset. Default `0`.

Province codes use Canadian province and territory abbreviations. Federal benefits use CA.

Example requests

Retrieve Ontario benefits in English:

GET /api/v1/benefits?province=ON&lang=en
x-api-key: bw_live_your_api_key

Retrieve federal benefits in French:

GET /api/v1/benefits?province=CA&lang=fr
x-api-key: bw_live_your_api_key

Retrieve Waterloo benefits:

GET /api/v1/benefits?province=ON&city=Waterloo&lang=en
x-api-key: bw_live_your_api_key

Retrieve a paginated result set:

GET /api/v1/benefits?limit=25&offset=50&lang=en
x-api-key: bw_live_your_api_key

Example response

{
  "version": "1.0",
  "total": 61,
  "limit": 2,
  "offset": 0,
  "lang": "en",
  "items": [
    {
      "id": "68yNZ7Uy67GiOxt7GgKS3L",
      "title": "Affordable Food",
      "slug": "affordable-food",
      "acronym": null,
      "provinceCode": "ON",
      "authority": "Ontario",
      "city": "Waterloo",
      "lead": "If you live in the Region of Waterloo...",
      "headlineValue": null,
      "introduction": "Markdown content may be included.",
      "eligibility": "Eligibility information may be included.",
      "howToApply": "Application instructions may be included.",
      "taxFilingUnlocks": false,
      "taxFilingApplication": false,
      "taxFilingAndApplication": false,
      "categories": [
        {
          "id": "10jjQrukVoc4DvK2DzYbV0",
          "title": "General"
        }
      ],
      "requiredIdentification": [],
      "sourceUpdatedAt": "2026-02-09T14:09:22.595Z"
    }
  ]
}

Long text fields may contain Markdown. Partner applications are responsible for rendering Markdown appropriately.

Error codes

Status	Meaning
`200`	Request successful.
`401`	Missing or invalid API key.
`403`	API key is disabled, expired, or partner access is disabled.
`429`	Rate limit exceeded, if rate limiting is enabled.
`500`	Unexpected server error.

Example error response:

{
  "error": "Invalid API key"
}

Changelog

Version 1.0

Initial Partner API release.

GET /api/v1/benefits
API key authentication
English and French responses
Province filtering
City filtering
Pagination
Categories
Required identification
Source update timestamps

FAQ

Is this the same as accessing Contentful directly?

No. The Partner API provides a curated data model for partner integrations. Partners do not access the Benefits Wayfinder production Contentful environment directly.

What is the source of truth?

Benefits Wayfinder Contentful remains the source of truth. The Partner API serves synchronized published content.

Are draft benefits included?

No. Only published benefit content is available through the Partner API.

What languages are supported?

The API currently supports English (en) and French (fr).

What does province=CA mean?

CA represents federal, Canada-wide benefits.

Can we cache responses?

Yes. Partner applications may cache responses. The sourceUpdatedAt field can be used to determine when the source content was last updated.

Developer resources

The Benefits Wayfinder Partner API is described using the OpenAPI 3.1 specification.

Developers can import the specification into Postman, Insomnia, or other API tools, or browse the interactive API reference.

Download OpenAPI specification Interactive API reference

The API requires a valid x-api-key to access protected endpoints.