Changelog

How this changelog works

Entries are newest first. Each entry gives a date, a change type, and what you need to do. Breaking changes are called out first inside each date block.

Change types:

API versioning and how versions are pinned are covered in api-conventions. If a change below refers to a request or response shape, that page defines the shape.

What counts as breaking

These are treated as breaking and get advance notice:

• Removing a field from a response, or removing an endpoint.
• Changing the type of an existing field.
• Adding a required request parameter.
• Changing the meaning of an existing enum value.
• Changing an HTTP status code returned for an existing condition.

These are not treated as breaking, and can ship without notice:

• Adding a new field to a response body.
• Adding a new value to an existing enum.
• Adding a new optional request parameter.
• Adding a new webhook event type.
• Changing the wording of an error message string. The code is stable, the message is not. See api-errors.

The consequence for you: your JSON parsing must tolerate unknown fields, and your webhook handler must ignore event types it does not recognize rather than erroring. A handler that throws on an unknown event type will start failing and get retried on a schedule you did not choose. See webhook-events and webhook-retries.

A tolerant handler looks like this:

import express from "express";

const app = express();

app.post("/finn/webhook", express.json(), (req, res) => {
  const event = req.body;

  switch (event.type) {
    case "call.completed":
      handleCallCompleted(event);
      break;
    default:
      // Unknown or newly added event type. Acknowledge, do not throw.
      console.log("unhandled event type", event.type);
  }

  res.status(200).send();
});

function handleCallCompleted(event: unknown) {
  // your logic
}

app.listen(3000);

Entries

Dated entries have not been backfilled into this page yet. Until they are, the sources below are authoritative for what changed:

• The dashboard release notes panel, which is where product changes are announced first. This is a dashboard surface, not an API endpoint. There is no endpoint that returns the changelog.
• Deprecation headers on API responses. When an endpoint or parameter is scheduled for removal, responses carry a deprecation header. Log those headers in your client so you find out from your own logs rather than from a failure.

Read a deprecation header like this:

curl -i https://api.hirefinn.ai/v1/finns \
  -H "Authorization: Bearer $FINN_API_KEY" \
  | grep -i '^deprecation\|^sunset\|^link'

If your key or base URL differs from the above, take both from authentication. Do not hardcode a base URL from a code sample if the authentication page states a different one for your region. Region matters for where your data lives and which host you call. See data-residency.

How to find out before something breaks

Polling this page is the weakest option. Better, in order:

1. Log every response header whose name starts with deprecation or sunset, and alert on a non-empty value. This tells you about your own usage specifically, not about changes to endpoints you never call.
2. Pin an API version if api-conventions offers version pinning for your account, then upgrade deliberately. An unpinned client takes changes on the platform's schedule.
3. Keep a staging workspace with a separate API key and run your integration against it before you promote. See local-development for running against your own machine.

Things that change without a changelog entry

Some behavior is per-workspace and will not appear here at all, because it is configuration rather than platform change:

If a call started failing and nothing on this page explains it, the cause is usually one of the above rather than a platform change. Start at troubleshooting, then check api-errors for the specific code you got back. If neither resolves it, support covers what to include in a report. Include the request ID from the failing response. Without it, a report about an intermittent failure is not actionable.