# suggestCode

query · in the family [Reading your records](/reference/reading-your-records/)

## What it does

Suggest a code for a record, built from its name — and free to take where codes must be unique.

Suggest a FREE code for a record from its name. DETERMINISTIC, no AI call, nothing metered: the name's words uppercase and join with hyphens (bounded 24 chars; diacritics fold), numbered -2, -3, … when taken. For families whose codes are unique (Organization — unique across the whole platform) every candidate is checked against the SAME reservation the save enforces, so the answer is free AT ANSWER TIME — a race can still take it before you save, and the save then refuses honestly (CONFLICT/IDENTITY_TAKEN, nothing changes). Families whose codes are freely chosen answer the derivation directly. `type` must name a code-bearing record family (the declared roster — an unknown family refuses VALIDATION/INVALID); `text` is the name to derive from (<= 500 chars; must contain a letter or digit). NOTHING auto-applies — the answer pre-fills the code input. Requires authentication (user sessions).

## What happens

A drafting assist: the suggestion only fills the code box, and nothing saves until you press Change code. Where codes are unique (an organization’s code is unique across the whole platform) the suggestion is checked against the same register the save enforces — though a code can still be taken by someone else between suggesting and saving, and the save then refuses honestly. No AI is involved.

## Who may call it

Capability area: **Reading your records** — Looking up and listing the records of your organization.

- Owner
- System Administrator
- Manager
- Associate Manager
- Warehouse Associate
- Sales Associate
- An API key whose scope allows `api:suggestCode`

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `type` | [String](/types/#scalars) `String!` | yes | No further notes. |
| `text` | [String](/types/#scalars) `String!` | yes | No further notes. |

## Returns

[SuggestedCode](/types/SuggestedCode/) `SuggestedCode!` — The code suggest's answer: ONE derived code, free against its family's declared uniqueness scope AT ANSWER TIME (a race can still take it before you save — the save then refuses honestly). It pre-fills the code input — NOTHING auto-applies.

## Example request

```graphql
query ExampleSuggestCode($type: String!, $text: String!) {
  suggestCode(type: $type, text: $text) {
    suggestion
  }
}
```

Variables:

```json
{
  "type": "<type>",
  "text": "Restock before the weekend."
}
```

## Example response

```json
{
  "data": {
    "suggestCode": {
      "suggestion": "<suggestion>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

## Errors this call can answer

- `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/))
- `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/))
- `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/))
- `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/))