> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses and Links

> Representations, views, links, includes and the formats every value uses

These standards apply to every endpoint under `https://api.quidkey.com/v1`. An endpoint that departs from one says so in its reference, and why.

* **One shape per resource.** A resource is represented the same way by every endpoint that returns it.
* **One document shape.** Every successful JSON response has the same structure, whether it holds one resource or a hundred.
* **Invalid input is refused.** An unknown field, an ambiguous value or an amount we can't represent answers an error. It's never guessed at, rounded or dropped.
* **Changes.** We add to the API without notice, and change or remove what's published only as [Versioning](https://docs.quidkey.com/api-v1/standards/versioning.md) describes.

## Representations and Views

Each resource has a **full** representation, and some also have a **summary**, with the fields needed to display or choose between resources. The view a response holds is in its `_view` field. A single read takes `?view=` to choose any view the resource documents, and a list returns its documented view.

* A summary is a strict subset of the full representation, with the same names, types and meanings.
* A representation looks the same wherever it appears: from a list, a read, a create, an update or an action.
* A representation doesn't vary by caller. If you can read a resource, you see what anyone else who can read it sees.
* **Every field is always present.** An empty value is `null`, and an empty collection is `[]`. The one exception is a one-time value, such as a secret, which appears only in the response that issues it. See [Idempotency](https://docs.quidkey.com/api-v1/standards/idempotency.md#one-time-values).
* Sensitive values, such as bank account numbers, aren't returned in full.

Every resource carries these fields:

| Field | Meaning |
| - | - |
| `_type` | The resource type, such as `transaction`. Tells resources apart without inspecting their fields. |
| `_uri` | The resource's canonical URI. |
| `_view` | The representation returned, such as `full` or `summary`. |
| `id` | The resource's stable identifier. Store it, and quote it to support. A singleton sub-resource's `id` is its parent's, so `_type` and `id` together identify a resource. |
| `created_at`, `updated_at` | Timestamps. `null` where Quidkey holds no such time, as on reference data and computed resources. |

Fields starting with an underscore belong to the protocol. All other fields belong to the resource.

## Links

A relationship is always a link object, never a bare ID, with the same shape for every resource:

```json theme={null}
"merchant": {
  "_link": "/merchants/m_1",
  "_type": "merchant",
  "id": "m_1"
}
```

Anything else in a link object describes the relationship, not the target, such as `is_default` on a country's payment scheme.

| Case | What you get |
| - | - |
| No link | The field is `null`. |
| A target the API doesn't publish, such as a partner | `_type` and `id`, with no `_link`. It can't be fetched, and including it lists it in `not_included`. |
| A singleton sub-resource | A link whose `id` is the parent's: `{ "_link": "/transactions/tx_1/customer-details", "_type": "customer_details", "id": "tx_1" }`. |
| A small set | An array of links. |
| A collection | A link with `_type: "collection"`, such as `{ "_link": "/merchants/m_1/transactions", "_type": "collection" }`. Follow it to get the list. |
| In a request body | The same object, where only `id` is required: `{ "agreement": { "id": "agr_1" } }`. A target that doesn't exist, or that you can't reach, answers 400. |
| In a query string | Filter by ID, such as `?payment_link_id=pl_1`. |

A link gives no access of its own. A response can link to a resource you can't read, and fetching it answers 403 or 404.

### URIs

A resource has exactly one canonical URI, flat wherever its ID is unique, such as `/transactions/tx_1`. A sub-collection such as `/merchants/m_1/transactions` returns resources carrying those canonical URIs.

URIs are relative to the version root and don't contain `/v1`, so resolve one against your base URL, `https://api.quidkey.com/v1`. A URI never changes for the life of the resource.

## Response Documents

A successful response has three parts:

* `result` holds what you asked for: one resource, or an array for a list.
* `entities` holds linked resources, keyed by URI: those the endpoint includes by default, and those you ask for with `include`.
* `not_included` lists the links that should have been included but couldn't be.

Reading a refund, with `?view=summary` to keep it short:

```json theme={null}
{
  "result": {
    "_type": "transaction",
    "_uri": "/transactions/tx_2",
    "_view": "summary",
    "id": "tx_2",
    "type": "refund",
    "is_test": false,
    "transaction_number": "QK-10042",
    "status": "processing",
    "amount": { "value": 1050, "currency": "EUR" },
    "payout_amount": null,
    "exchange_rate": null,
    "routing": "virtual_account",
    "refund_status": null,
    "can_refund": false,
    "order": null,
    "platform": null,
    "merchant": { "_link": "/merchants/m_1", "_type": "merchant", "id": "m_1" },
    "customer_details": null,
    "payout": null,
    "created_at": "2026-11-02T10:00:00.000Z",
    "updated_at": "2026-11-02T10:01:00.000Z"
  },
  "entities": {},
  "not_included": []
}
```

The same read with `?include=merchant` leaves `result` unchanged and fills `entities`, so a client finds a linked resource the same way every time:

```javascript theme={null}
const merchant = response.entities[response.result.merchant._link];
```

A list is an array of the same representation in `result`, with `pagination` beside it. See [Collections](https://docs.quidkey.com/api-v1/standards/collections.md).

### Including Linked Resources

* `include` takes a comma-separated list of link fields, one level deep: `?include=merchant,customer_details`. An unknown field answers 400. Each endpoint's reference lists what it can include.
* Sending `include` replaces the endpoint's default inclusions, so `?include=` with no value includes nothing.
* Including an array of links hydrates each one. A collection link can't be included: follow it instead.
* Each URI appears once in `entities`, however many links point to it. An included resource is in `entities` even when it's also in `result`.
* A representation is identical in `result`, in `entities` and when you fetch its `_uri` with the same view.
* A direct read and the response to a write are authoritative. A resource in a list can be slightly older than a direct read.

### Links Not Included

A resource that should be included but can't be read is left out of `entities` and listed in `not_included`, with its link and a `reason`. `result` stays the same.

```json theme={null}
"not_included": [
  {
    "link": { "_type": "partner", "id": "p_1" },
    "reason": "not_published"
  }
]
```

| `reason` | Meaning |
| - | - |
| `no_permission` | Your credential can't read it. Fetching it answers 403, or 404 where a 403 would reveal that it exists. |
| `not_published` | The API doesn't show it: a type it doesn't publish, or a record it doesn't show, such as a failed payout. Fetching it answers 404. |

A link you didn't include has no entity. Fetch its URI if you need it.

## Formats

### Money

Money is always an object, with an integer `value` in the currency's ISO 4217 minor units and its currency code:

```json theme={null}
"amount": { "value": 4500, "currency": "GBP" }
```

* GBP 45.00 is `4500`. Each amount carries its own currency, so two amounts in one resource can differ.
* The same form is used in requests and responses. Two places write money otherwise: a [file](https://docs.quidkey.com/api-v1/standards/collections.md#files) writes an amount as a decimal in major units, and an event's [earlier fields](https://docs.quidkey.com/api-v1/webhooks.md#the-earlier-format) write it in their own forms, such as a string of minor units with its currency beside it.
* A decimal value is refused, not rounded, and so is a currency we can't process.

### Rates

A rate is a decimal string holding a fraction: `"0.0500"` means 5%. Parse it as a decimal, and don't assume a number of places: it has at most 8, and trailing zeros aren't significant. A field holding a percentage is named `*_percent`, such as `ownership_percent`.

### Points

Reward points, as in `extra_rewards` and `total_rewards`, are a decimal string, not money: `"12.50"`. A response gives exactly 2 decimal places, and a request takes at most 2.

### Dates and Times

| Kind | Format | Field name | Example |
| - | - | - | - |
| Instant | RFC 3339, in UTC with `Z` | `*_at` | `2026-11-02T10:00:00.000Z` |
| Calendar date | `YYYY-MM-DD` | `*_date`, and `date_of_birth` | `1990-04-21` |
| Duration | An integer, its unit in the field name | `*_seconds`, `*_ms` | |

A timestamp means what its name says: `sent_at` is when a payout was sent, never when its record last changed.

### Other Values

| Type | Format |
| - | - |
| Identifier | An opaque string. Don't parse it or validate its format, which can change. An ID is never reused. |
| Country | ISO 3166-1 alpha-2, uppercase |
| Currency | ISO 4217, uppercase |
| Region | ISO 3166-2, such as `AU-NSW` |
| Phone | E.164, such as `+442071234567` |
| Language | BCP 47, such as `en-GB` |
| URL | Absolute HTTPS, except resource URIs, which are relative |

Input is parsed and output is canonical, so a time sent with `+00:00` comes back with `Z`. A value we can't represent is refused, never dropped.

### Names

* Fields and parameters are `snake_case`, and path segments are `kebab-case`.
* An action is named in `lowerCamelCase`, after a colon: `:issueCheckout`.
* Collections are plural and singletons are singular, as in `/merchants/m_1/onboarding`.
* Booleans read as predicates: `is_test`, `has_more`, `can_refund`.
* Enum values are lowercase `snake_case`. We spell `cancelled` with two Ls.
* A resource that reports why something failed carries `failure`, an object with at least `code` and `message`, or `null`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.