# The source field

Every number in an Acquestor response is a Figure, and every Figure points to a dated source listed once in the same response. Identifiers, result counts and pagination are the only numbers exempt. A contract test runs over API responses in CI and fails any response that holds a number without a dated source.

## Figure

```json
{"value": 383401, "unit": "USD", "source": "c1"}
```

| Field | Meaning |
| --- | --- |
| `value` | The number, or `null` when there is none (a gap explains why). |
| `unit` | One of `USD`, `x` (a multiple), `rate` (0.10 is 10%), `percent`, `count`, `months`, `years`, `days`, `share` (0 to 1). |
| `source` | The `id` of an entry in the response's `sources`, or of its `computation`. |
| `as_of` | Optional, when this figure's date differs from its source's. |
| `note` | Optional, up to 280 characters. |

Money is in whole US dollars as numbers, never strings. Rates and shares are fractions.

## Source

```json
{
  "id": "s1",
  "source_id": "frb-h15-prime",
  "name": "H.15 Selected Interest Rates: bank prime loan rate",
  "publisher": "Board of Governors of the Federal Reserve System",
  "dataset": "H.15 bank prime loan rate",
  "basis": "public_record",
  "route": "served_directly",
  "licence_status": "cleared",
  "as_of": "2026-10-02",
  "url": "https://www.federalreserve.gov/releases/h15/",
  "line": "Source: Federal Reserve, H.15 bank prime loan rate, as of Oct 2, 2026",
  "retrieved_at": "2026-10-05"
}
```

`as_of` is always present. What it dates depends on the kind of source:

| `basis` | What it is | `as_of` is |
| --- | --- | --- |
| `public_record` | A federal dataset Acquestor loads and serves | The data's vintage |
| `rule` | A rule set: an SBA SOP or notice, a tax table | The rule's effective date |
| `computed` | An Acquestor computation | The computation date |
| `assumption` | A default you can change, itself sourced (the BLS median manager wage for an area, for example) | The source's vintage |
| `broker_submitted` | A figure from a broker's listing | When the broker last updated it |
| `user_upload` | A figure read from a document in a deal; `document_id` and `page` say where | The upload date |
| `user_entered` | Typed by the user on acquestor.com | The entry date |
| `client_supplied` | Passed in by an API caller or an AI client | The request date |

`client_supplied` figures serve that request, or the one deal it names. They aren't added to your account, to aggregates or to any other deal. Two exceptions: a run you save keeps its inputs in that deal, and a request sent with an `Idempotency-Key` keeps its response for 24 hours so a retry can replay it.

A source whose publisher requires a notice carries it in `notice`: SOFR carries the New York Fed's, and BLS wage data carries BLS's. Show it wherever you show that figure.

Other fields: `name`, `dataset`, `url`, `retrieved_at`, `effective_from` and `effective_to` (rules), `document_id` and `page` (documents), and `notice`, above.

`line` is the source line ready to show beside the figure, in the format below: "Source: Federal Reserve, H.15 bank prime loan rate, as of Oct 2, 2026", "Source: SBA SOP 50 10 8.1, effective Oct 1, 2026", or "Supplied by the calling AI client or API caller, Oct 5, 2026; used for this request only".

`GET /sources/{source_id}` (MCP: `get_source`) explains a registry source: its publisher, terms link, licence status, refresh cadence and the date of its most recent data (`latest_as_of`). `GET /sources` lists them all, and acquestor.com/sources shows the same table.

## Route

`route` records how the data reached you, and billing follows it.

| `route` | Meaning | During the beta |
| --- | --- | --- |
| `served_directly` | Public data, data users submit, and Acquestor's own computations | Every source |
| `resold` | Data licensed for resale, at vendor cost plus a margin | None |
| `user_key` | A vendor reached on the user's own licence | None |

## Licence status

Each registry source has a licence status, and Acquestor checks it before a figure enters a tool or a table.

| `licence_status` | Tools and tables | Text answers |
| --- | --- | --- |
| `cleared` | Yes | Yes |
| `cite_only` | No | One attributed figure with a link |
| `link_only` | No | The publication's name and link, no figures |

Federal data and Acquestor's computations are cleared. Market reports whose terms don't allow redistribution start as `link_only`.

## Computation

```json
{
  "id": "c1",
  "method": "sba_ceiling",
  "method_version": "1.0.0",
  "computed_at": "2026-10-05T15:02:11Z",
  "rule_sets": ["sba-sop-50-10-8.1@2026-09-25", "sba-rate-caps@2026-03-01"],
  "inputs": {"sde": {"value": 156000, "unit": "USD", "source": "u1"}}
}
```

A computed result names the rule sets it used, each with the version date, and lists every input as a Figure. Rerun the same inputs with the same `as_of` against the same rule-set versions and you get the same result.

## Gaps

When data doesn't exist, the response says so instead of estimating.

```json
"gaps": [{"field": "state_tax", "reason": "state_not_modelled", "detail": "..."}]
```

| `reason` | Meaning |
| --- | --- |
| `no_data` | No source has this |
| `insufficient_records` | Too few records to show without exposing any one of them |
| `licence_restricted` | A source has it, but its terms don't let Acquestor serve the figure |
| `state_not_modelled` | Acquestor doesn't model this state yet; the federal part still runs |
| `not_yet_supported` | Planned, not built |
| `field_unconfirmed` | The field a computation needs isn't confirmed in the source |

A run that returns no result, with only a gap, isn't charged.

## The envelope

Computed tools and lookups return this shape:

| Field | Always | Holds |
| --- | --- | --- |
| `data` | Yes | The result, made of Figures |
| `sources` | Yes | Every source the result cites |
| `gaps` | Yes | What's missing and why; often empty |
| `disclaimer` | Yes | `informational` |
| `computation` | Computed tools | Method, rule sets and inputs |
| `warnings` | When there are any | Codes such as a price over the launch market |
| `charge` | Priced calls | Credits charged and the price class |
| `card` | Most results | The display model acquestor.com renders |
| `run_id` | When `deal_id` was passed | The saved run |

Build on `data`, `sources` and `computation`. `card` is a display model whose layout fields can change within a version.

## Showing figures to people

If your product shows Acquestor figures to people, show the source with each one. The format acquestor.com uses:

**Source: publisher, dataset or document, as of Mon D, YYYY**

- Name the original publisher, not the pipe the data came through.
- Use absolute dates. Rules say "effective": SBA SOP 50 10 8.1, effective Oct 1, 2026.
- A computed number says "Computed by Acquestor from the inputs above", and each input carries its own source line.
- Round headline dollar figures to the nearest $1,000 and keep the exact value one step away.