Skip to main content
Nova automatically handles criteria versioning internally, so you don’t need to track versions yourself. This page explains how versioning works and why we chose this approach.

​
How Versioning Works

When you generate or update criteria, Nova:
  1. Stores the new version linked to your jobId
  2. Records a timestamp for when the version was created
  3. Links each score to the exact criteria version used
You don’t need to track criteria versions yourself. Each score knows which criteria version was used, and we maintain full audit trails internally.

​
What This Means for You

​
Existing Scores Are Preserved

When you update criteria:
  • Previous scores retain their original criteria version
  • You can still see what criteria were used for any historical score
  • New scores use the updated criteria
Re-scoring after criteria updates: To re-score existing candidates with new criteria, set rescore: true in your scoring request. This counts as an additional application scored for billing purposes. See Idempotency for details.

​
Simple API

You just work with “current criteria” via the CRUD endpoints:
  • GET /v1/jobs/{jobId}/criteria - Get current criteria
  • POST/PATCH /v1/jobs/{jobId}/criteria - Update criteria
  • POST /v1/criteria/generate - Generate new criteria
Version management happens automatically behind the scenes.

​
Audit Compliance

For compliance and audit purposes:
  • Every score is traceable to its exact criteria version
  • Criteria changes are timestamped
  • Historical criteria are never deleted, only superseded

​
Common Questions

Not in v1 of the API. Scores always use the current active criteria for the job. If you need to re-score with older criteria, contact us to discuss your use case.
The assessment in each score result reflects the criteria that were active at scoring time. For detailed audit trails, contact us through the Embed Portal.
Any candidates already queued for scoring will use the criteria that were active when they were queued. New submissions will use the updated criteria.
Not directly. To restore previous criteria, you would need to add them back via POST /v1/jobs/{jobId}/criteria. We recommend keeping a copy of criteria you may want to restore.

​
Why Server-Side Versioning?

We chose to manage criteria versioning on our side for several reasons:
BenefitDescription
Simpler integrationYou don’t need to store or track version IDs
Guaranteed traceabilityEvery score links to its criteria - no drift possible
Reduced errorsNo risk of scoring with wrong or outdated criteria
Compliance readyFull audit trails without any extra work
During the API design phase, we considered two approaches for criteria versioning. This section preserves that discussion for reference.

​
Option A: Criteria Set Reference

In this approach, partners would pass a criteriaSetId to the scoring endpoint instead of the full criteria array. We would look up the criteria server-side.

​
How It Would Work

​
Tradeoffs

AdvantagesConsiderations
Full traceability from score to criteriaRequires API call whenever criteria change
Immutable criteria versionsYou depend on our stored criteria
Cleaner API (no large criteria array in requests)Must keep your system in sync with ours
We can show criteria details in Embed Portal

​
Option B: Inline Criteria with Optional Tracking

In this approach, partners would always pass the full criteria array (the original behavior), with optional criteriaSetId for correlation.

​
How It Would Work

​
Tradeoffs

AdvantagesConsiderations
Full control over criteriaLarger request payloads
No sync required with NovaYou’re responsible for criteria versioning
/v1/criteria/generate becomes optionalcriteriaSetId can drift from actual criteria used
Flexible for custom criteria workflowsLess visibility for us to help debug

​
Our Decision

We chose a hybrid approach that combines the best of both options:
  • Server-side storage (from Option A): Criteria are stored and versioned by Nova
  • No criteriaSetId in API (simplified): Partners just reference jobs by jobId
  • Internal versioning: We track versions for audit purposes, but don’t expose version IDs in v1
This gives partners the simplest possible integration while maintaining full traceability internally. We may expose version pinning and version IDs in a future API version based on partner feedback.