Skip to content
Peritus
DocsSign up
Concepts

Reading a response

What each part of the envelope says, and what it does not.

The envelope

Every query route returns the same envelope. A route adds its own parts, such as plan and answer for Ask, but never removes one. Each marker leads to its part below.

  1. 1response_idResponseIDA response's ID. It replays and compares that exact response.
  2. 2statusanswered · partial · abstainedWhether there is an answer.
  3. 3as_ofAsOfWhen the answer applies (valid_at), and what the record held then (known_at).
  4. 4modestrict · standard · broadWhich items could be served. Each mode returns everything the one before it does.
  5. 5presetstring · nullableThe key's preset, if any.
  6. 6itemsItem[]The cited facts.
  7. 7abstentionsAbstention[]Why part of the question has no answer.
  8. 8negative_resultsNegativeResult[]What was searched, and found nothing.
  9. 9withheldWithheld[]Items left out, by reason and count.
  10. 10attributionsAttribution[]Text to repeat where you show the data.
  11. 11metaMetaThe policy version, the index versions, and the milliseconds the server took.
Fig. 01 · The response envelope, from the Envelope schema
6 · items

Items

An item is one fact about one entity. It holds the value; the source by name, linked to its terms; the tier; the claim type, with the claimant for an attributed claim; when the fact held (valid time) and when it was recorded; and the exact passage it was read from, behind the marker beside the value.

MOA NICKEL SA

ent_06GR5VVHPDW2Q1HYD75X1W4YNM · org · sanctions.listing_status

Tier verifiedClaim type fact
list
SDN List
status
listed
measures
Block
legal_bases
Cuban Assets Control Regulations (CACR)Executive Order 14404 (Cuba)
SourceOFAC Sanctions List Service (SDN and Consolidated non-SDN lists)(terms, opens in a new tab)
Valid timeFrom 1995-05-23, no end dateDay precision
Recorded time2026-10-28 14:33 UTCWhen Peritus knew it
Sample response · GET /v1/samples/ask · item 1Fig. 02

Repeat the source's name and link wherever you show the value, and keep both times: a value without its valid time cannot be checked.

8 · negative_results

Negative results

A negative result records a search that found nothing: the subject, each list searched with its version, whether it was readable, and its row count, the time, and the method.

The fields of a negative result
FieldHolds
subjectThe entity, field, reference, or mention searched for
listssource_id · version · readable · row_count for each list
as_ofThe time the lists were read
methodexact_id · name_candidates · criteria · full_text
It saysThe subject was not found on the lists and versions it names, at its time, by its method.
It does not sayThat the subject is not sanctioned, or is absent from any list it does not name. Never turn it into “not sanctioned”.

A recorded example of a negative result is coming.

7 · abstentions

Abstentions

When the data cannot support an answer, the response abstains and says why. An abstention is a normal result with HTTP 200, not an error. Its code names the reason, its detail code narrows it, checked lists what was checked, and resolution_hint says what would resolve it.

Data is older than the caller or the source allows.

Abstained: STALECALLER_MAX_AGE

MOA NICKEL SAsanctions.listing_status

What was checked
CheckNoteResult
coveragefield, entity, source, and time range coveredpassed
subjectone entitypassed
timetime specification resolvedpassed
freshnesslast verified 1m0.590493s ago; max_age is 1sfailed

ResolutionRaise max_age, or ask again after the source's next verification.

Sample response · GET /v1/samples/abstention_stale

More than one entity could be meant.

Abstained: AMBIGUOUS_SUBJECTNAME_ONLY_MATCH

MOA NICKEL

What was checked
CheckNoteResult
coveragefield, entity, source, and time range coveredpassed
subjectsubject is not one entityfailed

ResolutionPass a kind hint or a discriminator such as an identifier, or choose a candidate by its ID.

Sample response · GET /v1/samples/abstention_ambiguous_subject

The question is outside what is ingested.

Abstained: NOT_COVEREDNO_SUCH_FIELD

hts 8413.70.20tariff.base_rate

What was checked
CheckNoteResult
coveragenot covered: NO_SUCH_FIELDfailed

ResolutionAsk for a field in the catalog.

Sample response · GET /v1/samples/abstention_not_covered
9 · withheld

Withheld

Items your key may not see are left out and counted, by reason. ATTESTATION_REQUIRED is the only reason disclosed at launch.

A recorded example of a withheld count is coming.

10 · attributions

Attributions

One text per source in the response. Repeat each one where you show the data.

ofac_sls
U.S. Department of the Treasury, Office of Foreign Assets Control (OFAC), Sanctions List Service
Sample response · GET /v1/samples/ask
1 · response_id

The response ID

Keep the response_id of any answer you rely on. POST /v1/compare takes it and says what changed since, and why. A report of a wrong fact names it.

response_idresp_06GR5VVKH9TSQAMANY5B2VQ7R4

Modes and presets

A mode sets which items may be served. Modes only add: whatever strict returns, standard returns too, and broad returns everything standard does. Strict returns only the verified tier. A key's preset sets its default mode and its exclusions.

Presets
PresetDefault modeOverrides and exclusions
trade_procurementstandardnone
sanctions_compliancestrictreconciliation required for legal-effect fields
travel_securitystandardnone
political_risk_insurancestrictstandard for conflict events. Excludes tags NO_INSURANCE_USE and SOCIAL_SOURCED
research_agentsbroadnone
newsroom_ngobroadnone

As-of queries

An as-of query takes two dates: valid_at, for when something applied, and known_at, for what the record held at that moment. Together they ask what was true on a date as it was known then. Fetch and Resolve take as_of; every response states the pair it used.

The nine abstention codes

Abstention codes
CodeMeaningDetail codes
Abstained: NOT_COVEREDThe question is outside what is ingested.NO_SUCH_FIELD, SOURCE_NOT_ACTIVE, BEFORE_CAPTURE, BEFORE_VALID_COVERAGE, OUTSIDE_DECLARED_COVERAGE, ASOF_NAME_SEARCH_UNSUPPORTED, UNSUPPORTED_QUESTION, SYNTHESIS_UNVERIFIED
Abstained: STALEData is older than the caller or the source allows.CALLER_MAX_AGE, FIELD_STALENESS, SOURCE_STALE, SOURCE_UNREADABLE, INDEX_BEHIND, SOURCE_DISCONTINUED
Abstained: BELOW_TIERVerification tier is under the mode or preset floor.EXTRACTED_NOT_PROMOTED, NOT_CROSS_CHECKED
Abstained: AMBIGUOUS_SUBJECTMore than one entity could be meant.MULTIPLE_CANDIDATES, NAME_ONLY_MATCH, HEADLINE_WORD
Abstained: CONFLICTSources or reconciliation disagree.RECONCILIATION_DISAGREED, SOURCE_DISAGREEMENT
Abstained: DATE_UNRESOLVEDThe time specification cannot be resolved.RELATIVE_PHRASE, AMBIGUOUS_FORMAT
Abstained: UNRESOLVED_CONDITIONSA carve-out, threshold, or licence is unresolved.FOOTNOTE_UNRESOLVED, LICENCE_REQUIRED
Abstained: PENDINGAn indexing job is running and nothing usable exists yet.JOB_RUNNING
Abstained: RECONCILIATION_PENDINGOur change has not been confirmed against the publisher's delta.RUN_UNRECONCILED

The three tiers

Tier extracted
Machine-extracted from the publisher's text and not yet confirmed.
Tier cross_checked
Confirmed by independent publisher families; several feeds of one outlet count once.
Tier verified
Verified against the primary text. Strict mode returns only this tier.

Claim types

fact
What the publisher's record states.
attributed_claim
What someone said. The item names the claimant; show it with the value.
assessment
A labeled computation over other facts, such as a count of changes.

Freshness

Each item's source carries its freshness, and its times say when it was fetched and last verified. Strict mode abstains STALE instead of serving old data as fresh.

  • fresh
  • lagging
  • stale
  • unavailable
  • discontinued