Banknotes

Banknote Assessment

The assessment resource returned for banknote workflows.

A banknote assessment identifies and grades one paper-money note from a photo of its front and a photo of its back, and returns it as the items entry.

Image guidance

Submit exactly two photos of one note: its front first, then its back. Each photo should show the entire note, loose or in its holder, with some space around it. Both photos must use the same input type: two URLs, two base64 images or two image_ref values. A base64 image or an image_ref can carry a clockwise rotation (0, 90, 180 or 270) when it was captured sideways or upside down.

A request with one photo or more than two is refused with a 400. When a photo cannot be read, downloaded or found, or shows no note, the assessment is rejected: assessment is null and issues says why.

Assessment sections

Banknote assessments support these result sections. If your integration only needs one of them, pass include with that section.

SectionDescription
identityThe note's identity, with a confidence.
gradeThe note's numerical grade.

A section you did not request is omitted from the item.

Identity fields

Every identity field is present in every response. A field the note has no value for is null.

FieldMeaning
nameComplete grade-independent note name, including its date and issuer.
typeThe note's design: its country, denomination and issuer, with the design's name or commemoration when it has one.
variantThe specific issue within the design, such as its watermark or variety.
yearThe Gregorian year of the printed date, such as 1994.
seriesThe date or series as printed, such as 1934A or BE2537 (1994).
countryThe issuing country.
regionThe period or part of the country the note belongs to, such as Weimar Rep..
denominationFace-value denomination, including its currency, such as $10 or 100 Baht.
issuerThe issuing bank, treasury or authority, such as Bank of Thailand.
catalog_referenceThe standard catalogue number, such as Pick 97 or Fr. 1535.
note_typeThe class of note, such as Silver Certificate or National Bank Note.
varietyThe note's variety, such as Star Note.
signaturesThe signature combination on the note.
printerThe printer of the note.
issuer_cityThe city of the issuing bank.
issuer_stateThe state of the issuing bank.
charter_numberThe issuing bank's charter number, on U.S. National Bank Notes.
confidenceConfidence in the returned banknote identity, from 0 to 1. See below.

Confidence

confidence is a score from 0 to 1 for the identity as a whole. It is not a probability that the identity is right, and it says nothing about the grade beside it. It is null when the identity comes with no score.

Grade fields

FieldMeaning
gradeThe numerical grade on the 70-point scale, as a string: 64.

Example

{
  "assessment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "external_id": "note-123",
  "status": "completed",
  "created_at": "2026-06-09T19:12:42.548Z",
  "completed_at": "2026-06-09T19:13:12.548Z",
  "assessment": {
    "items": [
      {
        "identity": {
          "name": "BE2537 (1994) Thailand 100 Baht, Bank of Thailand",
          "type": "Thailand 100 Baht, Bank of Thailand (Pick 97)",
          "variant": "Wmk: King Rama IX · Security Thread Only",
          "year": "1994",
          "series": "BE2537 (1994)",
          "country": "Thailand",
          "region": null,
          "denomination": "100 Baht",
          "issuer": "Bank of Thailand",
          "catalog_reference": "Pick 97",
          "note_type": null,
          "variety": "Wmk: King Rama IX",
          "signatures": null,
          "printer": null,
          "issuer_city": null,
          "issuer_state": null,
          "charter_number": null,
          "confidence": 0.81
        },
        "grade": {"grade": "64"}
      }
    ]
  },
  "issues": []
}

Response structure

A response is partial when a requested section could not be produced. It still carries everything that could be assessed.

FieldMeaning
assessment.itemsThe assessed note.
issuesResponse-level limitations or rejection reasons.
model_versionThe release of our models that produced the assessment.

Check status and the top-level issues before using a result. A rejected response has no assessment, and issues explains why.

Resource

Full banknote assessment responses use this schema:

assessment_id*uuid

Unique Vardera assessment ID.

external_id?string

Caller-provided ID, if supplied.

status*enum

Final assessment outcome.

Value in"completed" | "partial" | "rejected"
created_at*timestamp

RFC 3339 timestamp for when Vardera created the assessment.

FormatRFC 3339 timestamp
completed_at?timestamp

RFC 3339 timestamp for when processing finished, regardless of outcome.

FormatRFC 3339 timestamp
assessment?object | null

Banknote assessment details grouped by requested section.

issues?array<string>

Human-readable limitations or rejection reasons.

model_version?string

The release of Vardera's models that produced this assessment. Store it with the result to trace the answer to the models, thresholds and settings behind it.

Show example
{
  "assessment": {
    "items": [
      {
        "grade": {
          "grade": "64"
        },
        "identity": {
          "catalog_reference": "Pick 97",
          "confidence": 0.81,
          "country": "Thailand",
          "denomination": "100 Baht",
          "issuer": "Bank of Thailand",
          "name": "BE2537 (1994) Thailand 100 Baht, Bank of Thailand",
          "series": "BE2537 (1994)",
          "type": "Thailand 100 Baht, Bank of Thailand (Pick 97)",
          "variant": "Wmk: King Rama IX · Security Thread Only",
          "variety": "Wmk: King Rama IX",
          "year": "1994"
        }
      }
    ]
  },
  "assessment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "completed_at": "2026-06-09T19:13:12.548Z",
  "created_at": "2026-06-09T19:12:42.548Z",
  "external_id": "note-123",
  "issues": [],
  "model_version": "banknotes-3f9a1c2",
  "status": "completed"
}