---
title: "Set the object's analytics setup — the field roles shared by every chart and view (amount, stage, won/lost/converted values, stageProbabilities, closeDate, recurrence, owner, location). Replaces the mapping; with merge: true only the keys given change and null clears one"
method: PUT
path: "/crm/objects/{objectName}/analytics/roles"
tags: ["crm"]
---

# Set the object's analytics setup — the field roles shared by every chart and view (amount, stage, won/lost/converted values, stageProbabilities, closeDate, recurrence, owner, location). Replaces the mapping; with merge: true only the keys given change and null clears one

`PUT /crm/objects/{objectName}/analytics/roles`

## Request

- Base URL: `https://www.dench.com/api/v1`
- URL: `https://www.dench.com/api/v1/crm/objects/{objectName}/analytics/roles`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Set the object's analytics setup — the field roles shared by every chart and view (amount, stage, won/lost/converted values, stageProbabilities, closeDate, recurrence, owner, location). Replaces the mapping; with merge: true only the keys given change and null clears one.

## Path parameters

- `objectName` string, required

## Request body

- object
  - `fieldRoles` object, required: Field roles as an edit: the same keys; null clears one. Applied onto the stored mapping with merge: true, otherwise replaces it.
    - `amount` string, nullable: Numeric field holding the deal value ("Amount") — the "Value field" in the setup sheet.
    - `stage` string, nullable: Enum field driving the pipeline ("Stage" / "Status") — the "Progress field".
    - `wonValues` string[], nullable: `stage` options that count as won (closed, successful).
    - `lostValues` string[], nullable: `stage` options that count as lost (closed, gone).
    - `convertedValues` string[], nullable: `stage` options that count as converted (a lead reached "Qualified").
    - `closeDate` string, nullable: Date field for time bucketing, forecasts and the period pill (falls back to $createdAt).
    - `owner` string, nullable: User field naming who owns each record ("Owner"). Rankings on it default to a narrow card and draw member faces.
    - `location` string, nullable: Place-name field maps plot. May be a relation path like "Account.HQ Location" (one hop through a relation).
    - `recurrence` 'monthly' | 'annual' | 'one_time', nullable: How a won amount recurs: annual treats Amount as ARR, monthly as MRR, one_time disables MRR/ARR panels.
    - `stageProbabilities` object, nullable: Chance of closing per OPEN stage, 0..1, for the weighted forecast. Unlisted stages are spaced evenly; won = 1, lost = 0.
  - `merge` boolean: true: change only the keys given (null clears one). Default replaces the whole mapping.

## Response `200`

Successful response

- object
  - `ok` boolean, required
  - `fieldRoles` object, required: The mapping as stored after the write.
    - `amount` string: Numeric field holding the deal value ("Amount") — the "Value field" in the setup sheet.
    - `stage` string: Enum field driving the pipeline ("Stage" / "Status") — the "Progress field".
    - `wonValues` string[]: `stage` options that count as won (closed, successful).
    - `lostValues` string[]: `stage` options that count as lost (closed, gone).
    - `convertedValues` string[]: `stage` options that count as converted (a lead reached "Qualified").
    - `closeDate` string: Date field for time bucketing, forecasts and the period pill (falls back to $createdAt).
    - `owner` string: User field naming who owns each record ("Owner"). Rankings on it default to a narrow card and draw member faces.
    - `location` string: Place-name field maps plot. May be a relation path like "Account.HQ Location" (one hop through a relation).
    - `recurrence` 'monthly' | 'annual' | 'one_time': How a won amount recurs: annual treats Amount as ARR, monthly as MRR, one_time disables MRR/ARR panels.
    - `stageProbabilities` object: Chance of closing per OPEN stage, 0..1, for the weighted forecast. Unlisted stages are spaced evenly; won = 1, lost = 0.

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid authentication
- `404`: Operation or resource not found
- `500`: Server error

---

[API](https://skmtc.dev/dench/apis/dench-api.md) - [All operations](https://skmtc.dev/dench/apis/dench-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dench/apis/dench-api/revisions/4a145b38f19c?raw)