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

# Point a lookup key

> Name the configuration version you sell under a word of your own that is the same in every environment.

A lookup key is your word for a product you sell — `meses`, `quincenas` — pointed at one version of one configuration. Your code holds the key; the platform answers which configuration and version it names. The configuration keeps the identifier the platform composed for it: a key is a tag beside it, not a new name.

A key names a **version**, not a configuration in general. Writing a new version sells nothing until you point a key at it.

<Warning>
  Moving a key changes what the next borrower is offered. A key that already names another version moves only when the body states `transfer: true`. On a live Tenancy an agent cannot point or remove a key — a person or your own key does.
</Warning>

## Path parameters

<ParamField path="tenant_id" type="string" required>
  The Tenancy pointing the key.
</ParamField>

<ParamField path="lookup_key" type="string" required>
  Your word: 1 to 64 letters, digits, `-` and `_`, case-sensitive, unique within your Tenancy. A word shaped like an identifier the platform composes (`inst-000001`) or mints (a UUID) is refused.
</ParamField>

## Body

<ParamField body="configuration_id" type="string" required>
  The configuration the key sells.
</ParamField>

<ParamField body="configuration_version" type="integer" required>
  The version of it the key sells.
</ParamField>

<ParamField body="transfer" type="boolean">
  `true` to move a key that names another version. Absent or `false`, that key is refused `lookup_key_taken`.
</ParamField>

## Response

The key as it now stands — the same answer as [reading it](/api-reference/product-lookup-keys/read).

| The key now | `transfer` | Answer |
| - | - | - |
| does not exist, or was removed | any | <Badge color="green">201</Badge>, pointed |
| names this version | any | <Badge color="green">200</Badge>, nothing recorded |
| names another version | `true` | <Badge color="green">200</Badge>, moved |
| names another version | absent or `false` | <Badge color="orange">409</Badge> `lookup_key_taken` |

Every pointing is recorded and none is rewritten, so what a key named on any past day is on record.

The key is in the path, so a retry is safe by itself: it finds the key where the first attempt left it. An `Idempotency-Key` is ignored.

## Refusals

| Status | Code | When |
| - | - | - |
| 409 | `lookup_key_taken` | The key names another version and `transfer` is not `true`. `details.recorded_id` is the configuration it names, `details.recorded_value` the version. |
| 404 | `no_configuration` | Your Tenancy holds no such configuration at that version. |
| 422 | `invalid_identifier` | The key breaks the grammar or has an identifier's shape. |
| 422 | `missing_field` | The body names no configuration or no version. |

<RequestExample>
  ```bash Point meses at version 3 theme={null}
  BODY='{"configuration_id": "inst-000003", "configuration_version": 3}'

  curl -X PUT "https://api.capcells.com/v1/tenants/$TENANT_ID/product-lookup-keys/meses" \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" PUT "/v1/tenants/$TENANT_ID/product-lookup-keys/meses" "$BODY")" \
    -H "Content-Type: application/json" \
    -d "$BODY"
  ```

  ```bash Move it to version 4 theme={null}
  BODY='{"configuration_id": "inst-000003", "configuration_version": 4, "transfer": true}'

  curl -X PUT "https://api.capcells.com/v1/tenants/$TENANT_ID/product-lookup-keys/meses" \
    -H "Authorization: $(capcells_sign "$CAPCELLS_API_KEY" PUT "/v1/tenants/$TENANT_ID/product-lookup-keys/meses" "$BODY")" \
    -H "Content-Type: application/json" \
    -d "$BODY"
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "lookup_key": "meses",
    "configuration_id": "inst-000003",
    "configuration_version": 3,
    "pointed_at": "2026-10-16T15:04:05.123456Z",
    "latest_version": 4,
    "version": {
      "id": "inst-000003",
      "tenant_id": "t-0001",
      "archetype": "instalment",
      "created_at": "2026-10-01T10:00:00Z",
      "version": 3,
      "values": {
        "principal_min": { "minor_units": 100000, "currency": "MXN" },
        "principal_max": { "minor_units": 2000000, "currency": "MXN" },
        "rate_min": "36",
        "rate_max": "60",
        "penalty_rate_min": "36",
        "penalty_rate_max": "90",
        "day_count_basis": "actual_360",
        "terms": [6, 12, 18],
        "schedule": { "kind": "anchored_monthly" }
      }
    }
  }
  ```

  ```json 409 theme={null}
  {
    "error": "product: the lookup key names another configuration version: lookup_key \"meses\" names inst-000003 version 3; state transfer true to move it",
    "code": "lookup_key_taken",
    "retry": "after_change",
    "details": {
      "field": "configuration_version",
      "recorded_id": "inst-000003",
      "recorded_value": "3",
      "stated_value": "4"
    },
    "request_id": "0b9a1c2e-5d6f-4a7b-8c9d-0e1f2a3b4c5d"
  }
  ```
</ResponseExample>


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