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

# Refresh Custom Fields

> Refresh the cached contact custom fields used by SMS journeys.

Scans contacts in your account's sending lists, stores unique field names in sorted order, and returns the result. No request body is required. Restricted keys may refresh the cache when their scopes permit the operation.

Declares the `journeys.write` scope. Authenticate with `X-Api-Key`; see [Authentication](/api-reference/authentication).

Requests are limited to 5 per minute per API key unless that key has a custom rate-limit override. A request over the limit returns HTTP 429 with `code: "rate_limit_exceeded"` and a `Retry-After` header giving the number of seconds to wait.

## Response

<ResponseField name="success" type="boolean">
  True when the scan completes. False when a refresh is already running; that response still uses HTTP 200.
</ResponseField>

<ResponseField name="message" type="string">
  Summary of the scan result or running state.
</ResponseField>

<ResponseField name="fields" type="array of strings">
  Sorted field names after completion; omitted when a refresh is already running.
</ResponseField>

<ResponseField name="status" type="string">
  idle after completion, or running when a refresh is already in progress.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "message": "Found 2 custom fields",
    "fields": [
      "region",
      "tier"
    ],
    "status": "idle"
  }
  ```
</ResponseExample>

If no sending lists exist, the response has `success: true`, `message: "No sending lists found"`, `fields: []`, and `status: "idle"`.

An in-progress response is:

```json theme={null}
{"success": false, "message": "Refresh already in progress", "status": "running"}
```

A failed scan, including one that cannot finish within its time budget, resets the scan state to idle and returns HTTP 500 with an `error` string and `code: "custom_fields_refresh_failed"`.