Skip to main content
The Humanos API uses date-based versioning (YYYY-MM-DD). A new version is created whenever the API changes - this includes breaking changes, new endpoints, new optional fields, and new response fields. Any modification to the API specification triggers a new dated version.

​
The API-Version header

Include the API-Version header in your requests to pin your integration to a specific version: 
const response = await fetch("https://api.humanos.id/requests", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "X-Timestamp": timestamp.toString(),
    "X-Signature": signature,
    "API-Version": "2026-03-03",
  },
});

​
Version resolution

The API resolves the version for each request using the following priority:
PrioritySourceDescription
1API-Version headerExplicitly set per request
2Pinned versionAutomatically set to the latest version available at your first request
On your first API request, the latest available version is pinned to your organization. All subsequent requests use that pinned version unless you explicitly send an API-Version header. To upgrade, send the desired version in the header.
Sending an API-Version date in the future will return a 400 Bad Request error.

​
Webhook versioning

Webhooks are versioned independently from the API. Each organization has its own webhook version, which you can manage in the Humanos Dashboard. Every webhook payload includes an api_version field indicating which version format it uses: 
{
  "eventType": "credential",
  "api_version": "2026-03-03",
  "requestId": "68c42ec3e47c9a7f9241e0ba",
  ...
}
Pin your webhook version to avoid unexpected payload changes. Update it on your own schedule after reviewing the changelog.

​
Best practices

  • Pin a version via the API-Version header when you go to production. Your organization is automatically pinned to the version available at your first request, but explicitly setting it in the header gives you full control.
  • Test version upgrades before switching. Use the API-Version header to test against a newer version without affecting your default pinned version.
  • Keep webhook and API versions in sync unless you have a specific reason not to. This avoids confusion when correlating API responses with webhook payloads.