> For the complete documentation index, see [llms.txt](https://developers.gleantap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gleantap.com/api-reference-v3/scorecards.md).

# Scorecards

Account-wide metrics tables broken down by responsible user, location, or workroom (a reporting view, not contact scoring). Metric values are computed in the background, so a new or edited scorecard shows `calculation_status: "pending"` until the next calculation run.

## List the account's formula metrics.

> Metrics computed from other metrics rather than from a query. Same records \`listCustomMetrics\` returns with \`filter\[kind]=formula\`; this route is the formula-only view.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"CustomMetric":{"type":"object","properties":{"object":{"type":"string","enum":["custom_metric"]},"id":{"type":"string"},"name":{"type":"string","description":"Unique per account. This is what a scorecard's `metrics[]` stores."},"kind":{"type":"string","enum":["segment","formula"],"description":"`segment` counts contacts matching a query and is writable here. `formula` computes from other metrics and is writable via `/scorecards/formulas`.\n"},"metric_date":{"type":"string","nullable":true,"description":"Which date field constrains the metric to the scorecard's window. `\"\"` means no date constraint. Null means the field is absent, which the calculator treats as `add_date`.\n"},"is_formula_referenceable":{"type":"boolean","description":"Whether this metric's name contains only characters supported in formula references."},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages, e.g. when the metric name contains hyphens or symbols and cannot be referenced from formulas."},"query":{"type":"object","nullable":true,"description":"Present for `segment` metrics. Same shape as a segment's query.","properties":{"segment_users":{"type":"array","items":{"type":"object"}},"with_or_segment_users":{"type":"array","nullable":true,"items":{"type":"object"}}}},"formula":{"type":"string","description":"Present for `formula` metrics. References other metrics in braces."},"prefix":{"type":"string","description":"Display prefix for a formula metric."},"suffix":{"type":"string","description":"Display suffix for a formula metric","e.g. \"%\".":null}}}}},"paths":{"/scorecards/formulas":{"get":{"tags":["Scorecards"],"operationId":"listFormulaMetrics","summary":"List the account's formula metrics.","description":"Metrics computed from other metrics rather than from a query. Same records `listCustomMetrics` returns with `filter[kind]=formula`; this route is the formula-only view.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"}],"responses":{"200":{"description":"A page of formula metrics.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomMetric"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}}}}}}}
```

## Create a formula metric.

> Defines a metric as an arithmetic expression over other metrics, referenced in braces:\
> \
> &#x20;   ({New Contacts} / {Total Contacts}) \* 100      with suffix "%"\
> &#x20;   round({New Leads} / {Total Leads}, 2)\
> \
> A \`{reference}\` resolves against three things, in the order the calculator tries them: a built-in metric name, one of the account's own custom metrics, then a workroom attribute key. \`listScorecardMetrics\` returns the first two.\
> \
> \*\*Every reference is checked at write time, because nothing checks it later.\*\* The calculator substitutes each reference for its value and evaluates the result inside a catch-all that yields 0 on any error, and an unresolvable reference itself resolves to 0. So a formula with a mistyped metric name does not fail — \`({New Contactz} / {Total Contacts}) \* 100\` computes \`(0 / 5000) \* 100\` and reports \`0%\`, which looks like a real answer. The dashboard's own save path performs none of these checks.\
> \
> Also rejected: a formula with no references (that is a constant), self-reference, unbalanced braces or parentheses, and anything the calculator's sanitiser would strip — only \`+ - \* / . ( ) ,\`, digits and the functions \`round\`, \`ceil\`, \`floor\` survive outside a reference, so a formula containing more than that would be stored and then silently evaluated as something else.\
> \
> \`prefix\` and \`suffix\` are display-only, e.g. \`suffix: "%"\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"FormulaMetricWrite":{"type":"object","properties":{"name":{"type":"string","description":"Unique per account (case-insensitive); scorecards and other formulas reference metrics by this name."},"formula":{"type":"string","description":"Arithmetic over other metrics, each referenced in braces. Outside a reference only digits, `+ - * / . ( ) ,` and the functions `round`, `ceil`, `floor` are permitted — anything else is stripped by the calculator and is rejected here rather than stored.\n"},"prefix":{"type":"string","description":"Display prefix, e.g. \"$\"."},"suffix":{"type":"string","description":"Display suffix, e.g. \"%\"."}}},"CustomMetric":{"type":"object","properties":{"object":{"type":"string","enum":["custom_metric"]},"id":{"type":"string"},"name":{"type":"string","description":"Unique per account. This is what a scorecard's `metrics[]` stores."},"kind":{"type":"string","enum":["segment","formula"],"description":"`segment` counts contacts matching a query and is writable here. `formula` computes from other metrics and is writable via `/scorecards/formulas`.\n"},"metric_date":{"type":"string","nullable":true,"description":"Which date field constrains the metric to the scorecard's window. `\"\"` means no date constraint. Null means the field is absent, which the calculator treats as `add_date`.\n"},"is_formula_referenceable":{"type":"boolean","description":"Whether this metric's name contains only characters supported in formula references."},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages, e.g. when the metric name contains hyphens or symbols and cannot be referenced from formulas."},"query":{"type":"object","nullable":true,"description":"Present for `segment` metrics. Same shape as a segment's query.","properties":{"segment_users":{"type":"array","items":{"type":"object"}},"with_or_segment_users":{"type":"array","nullable":true,"items":{"type":"object"}}}},"formula":{"type":"string","description":"Present for `formula` metrics. References other metrics in braces."},"prefix":{"type":"string","description":"Display prefix for a formula metric."},"suffix":{"type":"string","description":"Display suffix for a formula metric","e.g. \"%\".":null}}}}},"paths":{"/scorecards/formulas":{"post":{"tags":["Scorecards"],"operationId":"createFormulaMetric","summary":"Create a formula metric.","description":"Defines a metric as an arithmetic expression over other metrics, referenced in braces:\n\n    ({New Contacts} / {Total Contacts}) * 100      with suffix \"%\"\n    round({New Leads} / {Total Leads}, 2)\n\nA `{reference}` resolves against three things, in the order the calculator tries them: a built-in metric name, one of the account's own custom metrics, then a workroom attribute key. `listScorecardMetrics` returns the first two.\n\n**Every reference is checked at write time, because nothing checks it later.** The calculator substitutes each reference for its value and evaluates the result inside a catch-all that yields 0 on any error, and an unresolvable reference itself resolves to 0. So a formula with a mistyped metric name does not fail — `({New Contactz} / {Total Contacts}) * 100` computes `(0 / 5000) * 100` and reports `0%`, which looks like a real answer. The dashboard's own save path performs none of these checks.\n\nAlso rejected: a formula with no references (that is a constant), self-reference, unbalanced braces or parentheses, and anything the calculator's sanitiser would strip — only `+ - * / . ( ) ,`, digits and the functions `round`, `ceil`, `floor` survive outside a reference, so a formula containing more than that would be stored and then silently evaluated as something else.\n\n`prefix` and `suffix` are display-only, e.g. `suffix: \"%\"`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormulaMetricWrite"}}}},"responses":{"201":{"description":"The created formula metric.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomMetric"}}}}}}}}}
```

## Retrieve one formula metric.

> The expression and its display prefix/suffix.

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"CustomMetric":{"type":"object","properties":{"object":{"type":"string","enum":["custom_metric"]},"id":{"type":"string"},"name":{"type":"string","description":"Unique per account. This is what a scorecard's `metrics[]` stores."},"kind":{"type":"string","enum":["segment","formula"],"description":"`segment` counts contacts matching a query and is writable here. `formula` computes from other metrics and is writable via `/scorecards/formulas`.\n"},"metric_date":{"type":"string","nullable":true,"description":"Which date field constrains the metric to the scorecard's window. `\"\"` means no date constraint. Null means the field is absent, which the calculator treats as `add_date`.\n"},"is_formula_referenceable":{"type":"boolean","description":"Whether this metric's name contains only characters supported in formula references."},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages, e.g. when the metric name contains hyphens or symbols and cannot be referenced from formulas."},"query":{"type":"object","nullable":true,"description":"Present for `segment` metrics. Same shape as a segment's query.","properties":{"segment_users":{"type":"array","items":{"type":"object"}},"with_or_segment_users":{"type":"array","nullable":true,"items":{"type":"object"}}}},"formula":{"type":"string","description":"Present for `formula` metrics. References other metrics in braces."},"prefix":{"type":"string","description":"Display prefix for a formula metric."},"suffix":{"type":"string","description":"Display suffix for a formula metric","e.g. \"%\".":null}}}}},"paths":{"/scorecards/formulas/{id}":{"get":{"tags":["Scorecards"],"operationId":"retrieveFormulaMetric","summary":"Retrieve one formula metric.","description":"The expression and its display prefix/suffix.","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The formula metric.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomMetric"}}}}}}}}}
```

## Update a formula metric.

> Patches \`name\`, \`formula\`, \`prefix\` or \`suffix\`. Omitted fields are left unchanged. A changed \`formula\` is re-validated in full.\
> \
> Renaming \*\*cascades\*\*, exactly as it does for segment metrics: scorecards holding the old name in \`metrics\[]\`/\`metrics\_columns\[]\` are rewritten, and any other formula metric referencing \`{old name}\` is rewritten too. Affected scorecards are queued for recalculation. Without that they would keep the old name and silently resolve it to 0.\
> \
> A segment-based custom metric is rejected here; use \`updateCustomMetric\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"FormulaMetricWrite":{"type":"object","properties":{"name":{"type":"string","description":"Unique per account (case-insensitive); scorecards and other formulas reference metrics by this name."},"formula":{"type":"string","description":"Arithmetic over other metrics, each referenced in braces. Outside a reference only digits, `+ - * / . ( ) ,` and the functions `round`, `ceil`, `floor` are permitted — anything else is stripped by the calculator and is rejected here rather than stored.\n"},"prefix":{"type":"string","description":"Display prefix, e.g. \"$\"."},"suffix":{"type":"string","description":"Display suffix, e.g. \"%\"."}}},"CustomMetric":{"type":"object","properties":{"object":{"type":"string","enum":["custom_metric"]},"id":{"type":"string"},"name":{"type":"string","description":"Unique per account. This is what a scorecard's `metrics[]` stores."},"kind":{"type":"string","enum":["segment","formula"],"description":"`segment` counts contacts matching a query and is writable here. `formula` computes from other metrics and is writable via `/scorecards/formulas`.\n"},"metric_date":{"type":"string","nullable":true,"description":"Which date field constrains the metric to the scorecard's window. `\"\"` means no date constraint. Null means the field is absent, which the calculator treats as `add_date`.\n"},"is_formula_referenceable":{"type":"boolean","description":"Whether this metric's name contains only characters supported in formula references."},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages, e.g. when the metric name contains hyphens or symbols and cannot be referenced from formulas."},"query":{"type":"object","nullable":true,"description":"Present for `segment` metrics. Same shape as a segment's query.","properties":{"segment_users":{"type":"array","items":{"type":"object"}},"with_or_segment_users":{"type":"array","nullable":true,"items":{"type":"object"}}}},"formula":{"type":"string","description":"Present for `formula` metrics. References other metrics in braces."},"prefix":{"type":"string","description":"Display prefix for a formula metric."},"suffix":{"type":"string","description":"Display suffix for a formula metric","e.g. \"%\".":null}}}}},"paths":{"/scorecards/formulas/{id}":{"patch":{"tags":["Scorecards"],"operationId":"updateFormulaMetric","summary":"Update a formula metric.","description":"Patches `name`, `formula`, `prefix` or `suffix`. Omitted fields are left unchanged. A changed `formula` is re-validated in full.\n\nRenaming **cascades**, exactly as it does for segment metrics: scorecards holding the old name in `metrics[]`/`metrics_columns[]` are rewritten, and any other formula metric referencing `{old name}` is rewritten too. Affected scorecards are queued for recalculation. Without that they would keep the old name and silently resolve it to 0.\n\nA segment-based custom metric is rejected here; use `updateCustomMetric`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormulaMetricWrite"}}}},"responses":{"200":{"description":"The updated formula metric.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomMetric"}}}}}}}}}
```

## Delete a formula metric.

> Removes the formula permanently. Refused with \`409 metric\_in\_use\` while a scorecard still references it by name.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}}},"paths":{"/scorecards/formulas/{id}":{"delete":{"tags":["Scorecards"],"operationId":"deleteFormulaMetric","summary":"Delete a formula metric.","description":"Removes the formula permanently. Refused with `409 metric_in_use` while a scorecard still references it by name.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"409":{"description":"Still referenced by one or more scorecards."}}}}}}
```

## List the account's custom scorecard metrics.

> Account-defined metrics that a scorecard can reference. Two kinds share this listing, told apart by \`kind\`:\
> \
> &#x20; \- \`segment\` — counts the contacts matching \`query.segment\_users\`, the same condition DSL segments use, within the window \`metric\_date\` selects. Writable through these endpoints.\
> &#x20; \- \`formula\` — computed from other metrics, e.g. \`({New Contacts} / {Total Contacts}) \* 100\`. Writable through \`/scorecards/formulas\`.\
> \
> Filter with \`filter\[kind]=segment|formula\` and \`filter\[name]=\<prefix>\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}}},"schemas":{"CustomMetric":{"type":"object","properties":{"object":{"type":"string","enum":["custom_metric"]},"id":{"type":"string"},"name":{"type":"string","description":"Unique per account. This is what a scorecard's `metrics[]` stores."},"kind":{"type":"string","enum":["segment","formula"],"description":"`segment` counts contacts matching a query and is writable here. `formula` computes from other metrics and is writable via `/scorecards/formulas`.\n"},"metric_date":{"type":"string","nullable":true,"description":"Which date field constrains the metric to the scorecard's window. `\"\"` means no date constraint. Null means the field is absent, which the calculator treats as `add_date`.\n"},"is_formula_referenceable":{"type":"boolean","description":"Whether this metric's name contains only characters supported in formula references."},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages, e.g. when the metric name contains hyphens or symbols and cannot be referenced from formulas."},"query":{"type":"object","nullable":true,"description":"Present for `segment` metrics. Same shape as a segment's query.","properties":{"segment_users":{"type":"array","items":{"type":"object"}},"with_or_segment_users":{"type":"array","nullable":true,"items":{"type":"object"}}}},"formula":{"type":"string","description":"Present for `formula` metrics. References other metrics in braces."},"prefix":{"type":"string","description":"Display prefix for a formula metric."},"suffix":{"type":"string","description":"Display suffix for a formula metric","e.g. \"%\".":null}}}}},"paths":{"/scorecards/custom_metrics":{"get":{"tags":["Scorecards"],"operationId":"listCustomMetrics","summary":"List the account's custom scorecard metrics.","description":"Account-defined metrics that a scorecard can reference. Two kinds share this listing, told apart by `kind`:\n\n  - `segment` — counts the contacts matching `query.segment_users`, the same condition DSL segments use, within the window `metric_date` selects. Writable through these endpoints.\n  - `formula` — computed from other metrics, e.g. `({New Contacts} / {Total Contacts}) * 100`. Writable through `/scorecards/formulas`.\n\nFilter with `filter[kind]=segment|formula` and `filter[name]=<prefix>`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"name":"filter","in":"query","style":"deepObject","explode":true,"description":"Filterable fields: `kind` (`segment` or `formula`) and `name` (case-insensitive prefix match on the metric name).\n","schema":{"type":"object","additionalProperties":{"type":"string"}}}],"responses":{"200":{"description":"A page of custom metrics.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomMetric"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}}}}}}}}}}
```

## Create a segment-based custom metric.

> Defines a metric as a named query: it counts the contacts matching \`query.segment\_users\`, within the window \`metric\_date\` selects.\
> \
> \`name\` must be unique on the account — \*\*case-insensitively\*\*. "Total Visits" and "total visits" are the same metric for this check, because scorecard matching is case-sensitive and a case-only twin would silently make one of them unreachable. A collision is a 422 naming the existing metric.\
> \
> A name containing characters the formula parser cannot match — hyphens, \`%\`, \`#\` — is still accepted, because such a metric works fine on a scorecard. It comes back with \`is\_formula\_referenceable: false\` and a \`not\_formula\_referenceable:\` entry in \`warnings\[]\`, telling you it cannot be referenced from a formula metric.\
> \
> \`metric\_date\` decides what the number actually counts, and has three distinct states worth knowing apart:\
> &#x20; \- a field name, e.g. \`memberships.start\_date\` — the metric counts matches whose date falls in the scorecard's reporting window\
> &#x20; \- \`""\` — no date constraint; counts every match regardless of period\
> &#x20; \- omitted — defaults to \`add\_date\`, matching the dashboard's own calculator\
> \
> \`query\` takes the same shape as a segment's: \`segment\_users\[]\` plus optional \`with\_or\_segment\_users\[]\` for OR groups. Call \`describeSegmentSchema\` for the categories, attributes and operators available on the workroom.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"CustomMetricWrite":{"type":"object","properties":{"name":{"type":"string","description":"Unique per account (case-insensitive); scorecards reference metrics by this name. Names should contain only letters, numbers, spaces, dots, or underscores to be referenceable in formula expressions."},"metric_date":{"type":"string","enum":["add_date","memberships.start_date","memberships.end_date","contracts.start_date","contracts.end_date","purchases.last_purchase_date","visits.last_visit_date","visits.first_visit_date",""],"description":"Which date field constrains the metric to the reporting window. `\"\"` is a real choice meaning no date constraint. Omitted on create, defaults to `add_date`.\n"},"query":{"type":"object","required":["segment_users"],"properties":{"segment_users":{"type":"array","minItems":1,"items":{"type":"object"}},"with_or_segment_users":{"type":"array","nullable":true,"items":{"type":"object"}}}}}},"CustomMetric":{"type":"object","properties":{"object":{"type":"string","enum":["custom_metric"]},"id":{"type":"string"},"name":{"type":"string","description":"Unique per account. This is what a scorecard's `metrics[]` stores."},"kind":{"type":"string","enum":["segment","formula"],"description":"`segment` counts contacts matching a query and is writable here. `formula` computes from other metrics and is writable via `/scorecards/formulas`.\n"},"metric_date":{"type":"string","nullable":true,"description":"Which date field constrains the metric to the scorecard's window. `\"\"` means no date constraint. Null means the field is absent, which the calculator treats as `add_date`.\n"},"is_formula_referenceable":{"type":"boolean","description":"Whether this metric's name contains only characters supported in formula references."},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages, e.g. when the metric name contains hyphens or symbols and cannot be referenced from formulas."},"query":{"type":"object","nullable":true,"description":"Present for `segment` metrics. Same shape as a segment's query.","properties":{"segment_users":{"type":"array","items":{"type":"object"}},"with_or_segment_users":{"type":"array","nullable":true,"items":{"type":"object"}}}},"formula":{"type":"string","description":"Present for `formula` metrics. References other metrics in braces."},"prefix":{"type":"string","description":"Display prefix for a formula metric."},"suffix":{"type":"string","description":"Display suffix for a formula metric","e.g. \"%\".":null}}}}},"paths":{"/scorecards/custom_metrics":{"post":{"tags":["Scorecards"],"operationId":"createCustomMetric","summary":"Create a segment-based custom metric.","description":"Defines a metric as a named query: it counts the contacts matching `query.segment_users`, within the window `metric_date` selects.\n\n`name` must be unique on the account — **case-insensitively**. \"Total Visits\" and \"total visits\" are the same metric for this check, because scorecard matching is case-sensitive and a case-only twin would silently make one of them unreachable. A collision is a 422 naming the existing metric.\n\nA name containing characters the formula parser cannot match — hyphens, `%`, `#` — is still accepted, because such a metric works fine on a scorecard. It comes back with `is_formula_referenceable: false` and a `not_formula_referenceable:` entry in `warnings[]`, telling you it cannot be referenced from a formula metric.\n\n`metric_date` decides what the number actually counts, and has three distinct states worth knowing apart:\n  - a field name, e.g. `memberships.start_date` — the metric counts matches whose date falls in the scorecard's reporting window\n  - `\"\"` — no date constraint; counts every match regardless of period\n  - omitted — defaults to `add_date`, matching the dashboard's own calculator\n\n`query` takes the same shape as a segment's: `segment_users[]` plus optional `with_or_segment_users[]` for OR groups. Call `describeSegmentSchema` for the categories, attributes and operators available on the workroom.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomMetricWrite"}}}},"responses":{"201":{"description":"The created metric.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomMetric"}}}}}}}}}
```

## Retrieve one custom metric.

> The metric's definition. A \`formula\` metric returns its expression and display affixes; a \`segment\` metric returns its \`query\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"CustomMetric":{"type":"object","properties":{"object":{"type":"string","enum":["custom_metric"]},"id":{"type":"string"},"name":{"type":"string","description":"Unique per account. This is what a scorecard's `metrics[]` stores."},"kind":{"type":"string","enum":["segment","formula"],"description":"`segment` counts contacts matching a query and is writable here. `formula` computes from other metrics and is writable via `/scorecards/formulas`.\n"},"metric_date":{"type":"string","nullable":true,"description":"Which date field constrains the metric to the scorecard's window. `\"\"` means no date constraint. Null means the field is absent, which the calculator treats as `add_date`.\n"},"is_formula_referenceable":{"type":"boolean","description":"Whether this metric's name contains only characters supported in formula references."},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages, e.g. when the metric name contains hyphens or symbols and cannot be referenced from formulas."},"query":{"type":"object","nullable":true,"description":"Present for `segment` metrics. Same shape as a segment's query.","properties":{"segment_users":{"type":"array","items":{"type":"object"}},"with_or_segment_users":{"type":"array","nullable":true,"items":{"type":"object"}}}},"formula":{"type":"string","description":"Present for `formula` metrics. References other metrics in braces."},"prefix":{"type":"string","description":"Display prefix for a formula metric."},"suffix":{"type":"string","description":"Display suffix for a formula metric","e.g. \"%\".":null}}}}},"paths":{"/scorecards/custom_metrics/{id}":{"get":{"tags":["Scorecards"],"operationId":"retrieveCustomMetric","summary":"Retrieve one custom metric.","description":"The metric's definition. A `formula` metric returns its expression and display affixes; a `segment` metric returns its `query`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The metric.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomMetric"}}}}}}}}}
```

## Update a segment-based custom metric.

> Patches \`name\`, \`metric\_date\` or \`query\`. Omitted fields are left unchanged.\
> \
> Renaming \*\*cascades\*\*. Every scorecard whose \`metrics\[]\` or \`metrics\_columns\[]\` holds the old name is rewritten to the new one, and every formula metric whose expression references \`{old name}\` is rewritten too. Those scorecards are then queued for recalculation (\`calculation\_status\` reverts to \`pending\`), because their stored values are still keyed by the old name. Nothing is left rendering an empty tile. Delete is the operation that is refused outright while references exist (409 \`metric\_in\_use\`); rename is safe.\
> \
> Formula metrics are rejected here: they are a different shape with their own endpoints — \`POST /scorecards/formulas\` and \`PATCH /scorecards/formulas/{id}\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"CustomMetricWrite":{"type":"object","properties":{"name":{"type":"string","description":"Unique per account (case-insensitive); scorecards reference metrics by this name. Names should contain only letters, numbers, spaces, dots, or underscores to be referenceable in formula expressions."},"metric_date":{"type":"string","enum":["add_date","memberships.start_date","memberships.end_date","contracts.start_date","contracts.end_date","purchases.last_purchase_date","visits.last_visit_date","visits.first_visit_date",""],"description":"Which date field constrains the metric to the reporting window. `\"\"` is a real choice meaning no date constraint. Omitted on create, defaults to `add_date`.\n"},"query":{"type":"object","required":["segment_users"],"properties":{"segment_users":{"type":"array","minItems":1,"items":{"type":"object"}},"with_or_segment_users":{"type":"array","nullable":true,"items":{"type":"object"}}}}}},"CustomMetric":{"type":"object","properties":{"object":{"type":"string","enum":["custom_metric"]},"id":{"type":"string"},"name":{"type":"string","description":"Unique per account. This is what a scorecard's `metrics[]` stores."},"kind":{"type":"string","enum":["segment","formula"],"description":"`segment` counts contacts matching a query and is writable here. `formula` computes from other metrics and is writable via `/scorecards/formulas`.\n"},"metric_date":{"type":"string","nullable":true,"description":"Which date field constrains the metric to the scorecard's window. `\"\"` means no date constraint. Null means the field is absent, which the calculator treats as `add_date`.\n"},"is_formula_referenceable":{"type":"boolean","description":"Whether this metric's name contains only characters supported in formula references."},"warnings":{"type":"array","items":{"type":"string"},"description":"Warning messages, e.g. when the metric name contains hyphens or symbols and cannot be referenced from formulas."},"query":{"type":"object","nullable":true,"description":"Present for `segment` metrics. Same shape as a segment's query.","properties":{"segment_users":{"type":"array","items":{"type":"object"}},"with_or_segment_users":{"type":"array","nullable":true,"items":{"type":"object"}}}},"formula":{"type":"string","description":"Present for `formula` metrics. References other metrics in braces."},"prefix":{"type":"string","description":"Display prefix for a formula metric."},"suffix":{"type":"string","description":"Display suffix for a formula metric","e.g. \"%\".":null}}}}},"paths":{"/scorecards/custom_metrics/{id}":{"patch":{"tags":["Scorecards"],"operationId":"updateCustomMetric","summary":"Update a segment-based custom metric.","description":"Patches `name`, `metric_date` or `query`. Omitted fields are left unchanged.\n\nRenaming **cascades**. Every scorecard whose `metrics[]` or `metrics_columns[]` holds the old name is rewritten to the new one, and every formula metric whose expression references `{old name}` is rewritten too. Those scorecards are then queued for recalculation (`calculation_status` reverts to `pending`), because their stored values are still keyed by the old name. Nothing is left rendering an empty tile. Delete is the operation that is refused outright while references exist (409 `metric_in_use`); rename is safe.\n\nFormula metrics are rejected here: they are a different shape with their own endpoints — `POST /scorecards/formulas` and `PATCH /scorecards/formulas/{id}`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomMetricWrite"}}}},"responses":{"200":{"description":"The updated metric.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomMetric"}}}}}}}}}
```

## Delete a custom metric.

> Removes the definition permanently.\
> \
> Refused with \`409 metric\_in\_use\` while any scorecard still references the metric by name, and the error names those scorecards. Without that check the scorecard would keep the name and render an empty tile with no error anywhere.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:write"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}}},"paths":{"/scorecards/custom_metrics/{id}":{"delete":{"tags":["Scorecards"],"operationId":"deleteCustomMetric","summary":"Delete a custom metric.","description":"Removes the definition permanently.\n\nRefused with `409 metric_in_use` while any scorecard still references the metric by name, and the error names those scorecards. Without that check the scorecard would keep the name and render an empty tile with no error anywhere.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted."},"409":{"description":"Still referenced by one or more scorecards."}}}}}}
```

## List the metric names a scorecard can reference.

> Every metric name valid on this account: the built-in metrics grouped by category, plus the account's own custom and formula metrics.\
> \
> A scorecard's \`metrics\[]\` stores these names \*\*verbatim\*\* and matches them exactly. A name that is not in this catalog is rejected on create and update; before that check existed, it saved cleanly and rendered as an empty tile.\
> \
> Three groups come back:\
> &#x20; \- \`builtin\` — the fixed metrics, keyed by category (Contacts, Customers, Sales, User Activity, Contacts Activity, Business Metrics).\
> &#x20; \- \`custom\_metrics\` — account-defined metrics that count the contacts matching a saved query.\
> &#x20; \- \`formula\_metrics\` — metrics computed from other metrics, with the expression and its display prefix/suffix. The expression references other metrics in braces, e.g. \`({New Contacts} / {Total Contacts}) \* 100\`.\
> \
> \`all\_names\` is the flat union, which is what \`metrics\[]\` is validated against.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]},{"OAuth2":["scorecards:read"]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Use for third-party apps acting on behalf of a Gleantap user.\nAuthorization Code + PKCE is the only supported grant for interactive flows; refresh_token grant is supported and rotates on every use.\n","flows":{"authorizationCode":{"authorizationUrl":"https://api.gleantap.com/v3/oauth/authorize","tokenUrl":"https://api.gleantap.com/v3/oauth/token","refreshUrl":"https://api.gleantap.com/v3/oauth/token","scopes":{"contacts:read":"Read contact records.","contacts:write":"Create, update, delete contacts (soft delete).","contacts:delete_hard":"Hard-delete contacts (irreversible).","events:read":"Read event records.","events:write":"Record events.","segments:read":"Read segments and preview membership.","segments:write":"Create, update, delete segments.","templates:read":"Read message templates.","templates:write":"Create, update, delete templates.","campaigns:read":"Read campaigns and analytics.","campaigns:write":"Create, schedule, cancel campaigns.","flows:read":"Read flow definitions and analytics.","flows:write":"Create, edit, publish flows.","flows:publish":"Publish/unpublish flows (separately scoped for governance).","messaging:send":"Send transactional messages (SMS, email, voice).","conversations:read":"Read conversations and messages.","conversations:write":"Send messages, close/reopen conversations.","webhooks:manage":"Create, update, delete webhook endpoints.","forms:manage":"Create, update, delete, publish, duplicate forms; list submissions and rotate the submission_token.","campaigns:manage":"Create, schedule, cancel, duplicate campaigns; read recipients and analytics. (Supersedes the earlier `campaigns:read` + `campaigns:write` split; the split scopes still work.)","admin:impersonate:read":"Gleantap staff only — read any customer account named via `Gleantap-Account`. Not available through dynamic client registration.","admin:impersonate:write":"Gleantap staff only — required for any state-changing method while impersonating. Not available through dynamic client registration."}}}}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}}},"schemas":{"MetricCatalog":{"type":"object","description":"The metric names a scorecard may reference on this account.","properties":{"object":{"type":"string","enum":["metric_catalog"]},"builtin":{"type":"object","description":"Fixed metric names, keyed by category.","additionalProperties":{"type":"array","items":{"type":"string"}}},"custom_metrics":{"type":"array","description":"Account-defined metrics that count contacts matching a saved query.","items":{"type":"object","properties":{"name":{"type":"string"},"has_criteria":{"type":"boolean","description":"False when the metric was saved without a query, in which case it has nothing to count."}}}},"formula_metrics":{"type":"array","description":"Metrics computed from other metrics.","items":{"type":"object","properties":{"name":{"type":"string"},"formula":{"type":"string"},"prefix":{"type":"string"},"suffix":{"type":"string"}}}},"all_names":{"type":"array","items":{"type":"string"},"description":"Flat union of every valid name. This is what `metrics[]` is checked against."},"not_referenceable":{"type":"array","items":{"type":"string"},"description":"Metric names that exist and can be placed on a scorecard, but cannot be referenced inside formulas because of special characters (e.g. `%`, `#`, `-`)."},"note":{"type":"string","description":"Advisory note indicating that scorecard metrics must match `all_names` exactly and unknown names are rejected with 422."}}}}},"paths":{"/scorecards/metrics":{"get":{"tags":["Scorecards"],"operationId":"listScorecardMetrics","summary":"List the metric names a scorecard can reference.","description":"Every metric name valid on this account: the built-in metrics grouped by category, plus the account's own custom and formula metrics.\n\nA scorecard's `metrics[]` stores these names **verbatim** and matches them exactly. A name that is not in this catalog is rejected on create and update; before that check existed, it saved cleanly and rendered as an empty tile.\n\nThree groups come back:\n  - `builtin` — the fixed metrics, keyed by category (Contacts, Customers, Sales, User Activity, Contacts Activity, Business Metrics).\n  - `custom_metrics` — account-defined metrics that count the contacts matching a saved query.\n  - `formula_metrics` — metrics computed from other metrics, with the expression and its display prefix/suffix. The expression references other metrics in braces, e.g. `({New Contacts} / {Total Contacts}) * 100`.\n\n`all_names` is the flat union, which is what `metrics[]` is validated against.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"}],"responses":{"200":{"description":"The metric catalog for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricCatalog"}}}}}}}}}
```

## List scorecards.

> Account-wide — not scoped by workroom (see the Scorecards tag description and \`workroom\_scoped\` on each item). Filters: \`?filter\[breakdown]=...\`, \`?filter\[type]=...\`, \`?filter\[name]=...\` (case-insensitive prefix). Sortable fields: \`created\_at\` (default, descending), \`name\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}},"WorkroomQuery":{"name":"workroom","in":"query","required":false,"description":"Same semantics as the `Gleantap-Workroom` header, including that a write should never be sent without a workroom the user actually chose, and that an omitted workroom scopes a read to the account default rather than spanning the account. Prefer this on GETs so proxies and caches can key on it. Accepts name, prefixed ID, raw hex, or `all`.\n","schema":{"type":"string"}},"LimitParam":{"name":"limit","in":"query","required":false,"description":"Page size. Default 25, max 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"CursorParam":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a prior response's `next_cursor`, to fetch the NEXT page (alias - `after`). On listContacts and listSegmentContacts, use `before` with a `prev_cursor` to page backward; other list endpoints are forward-only.","schema":{"type":"string"}},"SortParam":{"name":"sort","in":"query","required":false,"description":"Comma-separated list of fields to sort by. Leading `-` reverses. Default `-created_at`. Sortable fields vary per resource; unsortable fields return 400 `invalid_sort_field`.\n","schema":{"type":"string"}}},"schemas":{"ListEnvelope":{"type":"object","required":["object","data","has_more","next_cursor","prev_cursor"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object"},"description":"The page of results. Item type varies per endpoint — see the specific response schema."},"has_more":{"type":"boolean","description":"True if additional records exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Opaque cursor for the next page. Null on the last page."},"prev_cursor":{"type":"string","nullable":true,"description":"Cursor for the previous page. Supported on `listContacts` and `listSegmentContacts`: pass it back as `?before=...` to page backward; `null` on the first page. On every other list endpoint paging is forward-only and this is always `null`."}}},"Scorecard":{"type":"object","description":"Account-wide metrics table. Shaped identically regardless of whether the underlying doc was created by this API or by the legacy dashboard (`Apps::ajaxSaveScorecard()`) — both write the same fields to the same `scorecards` collection.\n","properties":{"id":{"$ref":"#/components/schemas/ScorecardId"},"object":{"type":"string","enum":["scorecard"]},"name":{"type":"string"},"type":{"type":"string","description":"Chart/display type — one of `Table`, `Metric`, `Line`, `Bar`, `Trend` (the values the dashboard renders; `Trend` is legacy and charted like `Line`). Writes accept these case-insensitively (also `# Metric`, `bar_chart`, ...) and store the canonical spelling; anything else is a 422. Scorecards saved before this check may still carry another value."},"breakdown":{"type":"string","description":"How rows are sliced — one of `None` (aggregate only), `Source`, `Location`, `Workroom`, `Responsible User`. Writes accept these case-insensitively (also `responsible_user`, `staff`, `aggregate`) and store the canonical spelling; anything else is a 422. `None` is not available with type `Table` (as in the dashboard). Only `Responsible User`, `Location`, and `Workroom` have corresponding `*_type`/`*_ids` side fields (see below); `None` and `Source` leave all three side-field groups null."},"metrics":{"type":"array","items":{"type":"string"},"description":"Metric names to track (e.g. \"New Contacts\", \"Total Contacts\"). Every element must be a non-empty string — an object or other non-string element is rejected with a 400/422, not silently coerced."},"pipeline_ids":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"},"description":"Optional. Restricts pipeline-related metrics to these pipelines."},"total_rollup":{"type":"boolean","description":"Add a combined total-rollup row across all breakdown groups."},"responsible_user_role":{"type":"string","nullable":true,"description":"Only populated when `breakdown` is `Responsible User`. Dashboard UI offers All, Admin, WorkroomAdmin, Marketing, Sales, Analyst, Specific Users."},"responsible_user_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw staff-record ids (not `usr_`-prefixed) — only populated when `responsible_user_role` is `Specific Users`."},"location_type":{"type":"string","nullable":true,"description":"Only populated when `breakdown` is `Location`. Dashboard UI offers All, Specific Locations."},"location_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw location values — only populated when `location_type` is `Specific Locations`."},"workroom_type":{"type":"string","nullable":true,"description":"Report-breakdown dimension only — unrelated to the `Gleantap-Workroom` request-scoping header/query. Only populated when `breakdown` is `Workroom`. Dashboard UI offers All, Specific Workrooms."},"workroom_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw workroom ids — only populated when `workroom_type` is `Specific Workrooms`."},"workroom_scoped":{"type":"boolean","const":false,"description":"Always `false`. The underlying `scorecards` collection has no app_id/workroom field at all, so this resource is account-wide regardless of any `Gleantap-Workroom` header/`?workroom=` hint on the request — see `scope_note`."},"scope_note":{"type":"string","description":"Plain-English restatement of `workroom_scoped`, always present so a caller does not have to infer scoping behavior from testing."},"calculation_status":{"type":"string","enum":["pending","calculating","completed","error"],"description":"Derived from the same fields the existing periodic `Cron::calculateScorecards()` sweep reads/writes on this same doc — this endpoint never computes metric values itself. A fresh scorecard reads `pending` until that sweep's next pass. Editing a scorecard (PATCH) clears its last calculation time, so it reads `pending` until the sweep recalculates it. A scorecard that completed calculation but produced no metric values reads `error` with an explanation in `calculation_error`. The sweep runs overnight (01:06–09:45 UTC); until then the dashboard shows the previous values, and its refresh button recalculates on demand.\n"},"calculation_error":{"type":"string","nullable":true,"description":"Explanation when calculation_status is error (e.g. calculation failed or produced no metric values)."},"metrics_calculated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metrics_values":{"type":"object","nullable":true,"additionalProperties":true,"description":"Computed metric values, keyed and shaped per `breakdown`/`type` with numeric counts. Omitted (`null`) in list responses by default unless `include_values=true` is requested. Empty object until the first calculation pass completes."},"inactive":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"ScorecardId":{"type":"string","pattern":"^scr_[0-9a-f]{24}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"TooManyRequests":{"description":"Rate limited.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"headers":{"RetryAfter":{"description":"On 429, seconds to wait before retrying.","schema":{"type":"integer"}}}},"paths":{"/scorecards":{"get":{"tags":["Scorecards"],"operationId":"listScorecards","summary":"List scorecards.","description":"Account-wide — not scoped by workroom (see the Scorecards tag description and `workroom_scoped` on each item). Filters: `?filter[breakdown]=...`, `?filter[type]=...`, `?filter[name]=...` (case-insensitive prefix). Sortable fields: `created_at` (default, descending), `name`.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"},{"$ref":"#/components/parameters/WorkroomQuery"},{"$ref":"#/components/parameters/LimitParam"},{"$ref":"#/components/parameters/CursorParam"},{"$ref":"#/components/parameters/SortParam"},{"name":"include_values","in":"query","description":"Whether to include `metrics_values` in each scorecard item. Defaults to `false` to keep response size manageable. Set to `true` to include full calculated metric values.","schema":{"type":"boolean","default":false}},{"name":"filter","in":"query","style":"deepObject","explode":true,"description":"See operation description for filterable fields.","schema":{"type":"object","additionalProperties":{"type":"string"}}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Scorecard"}}}}]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```

## Create a scorecard.

> Writes only the scorecard definition — metric values are computed asynchronously by the existing periodic dashboard cron (\`Cron::calculateScorecards()\`), the same job that has always computed them for dashboard-created scorecards; this endpoint does not trigger it synchronously. Returns 202, not 201: the response body is the full definition with \`calculation\_status: "pending"\`, not yet-computed values. Poll \`GET /scorecards/{id}\` for \`calculation\_status\` to flip to \`completed\`.\
> \
> Requires the name and what it measures. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"ScorecardCreate":{"type":"object","required":["name","type","breakdown","metrics"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["Table","Metric","Line","Bar","Trend"],"description":"Case-insensitive; stored canonical. Any other value is a 422. See the Scorecard schema."},"breakdown":{"type":"string","enum":["None","Source","Location","Workroom","Responsible User"],"description":"Case-insensitive; stored canonical. Any other value is a 422, as is `None` with type `Table`. See the Scorecard schema."},"metrics":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Non-empty array of metric names. Every element must be a non-empty string."},"pipeline_ids":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"}},"total_rollup":{"type":"boolean","default":false},"responsible_user_role":{"type":"string","description":"Required (defaults to `All`) when `breakdown` is `Responsible User`. Use `Specific Users` with `responsible_user_ids` to restrict."},"responsible_user_ids":{"type":"array","items":{"type":"string"},"description":"Only used when `responsible_user_role` is `Specific Users`. Accepts `usr_`-prefixed or raw ids; stored raw."},"location_type":{"type":"string","description":"Required (defaults to `All`) when `breakdown` is `Location`. Use `Specific Locations` with `location_ids` to restrict."},"location_ids":{"type":"array","items":{"type":"string"},"description":"Only used when `location_type` is `Specific Locations`."},"workroom_type":{"type":"string","description":"Report-breakdown dimension only — see the Scorecard schema. Required (defaults to `All`) when `breakdown` is `Workroom`. Use `Specific Workrooms` with `workroom_ids` to restrict."},"workroom_ids":{"type":"array","items":{"type":"string"},"description":"Only used when `workroom_type` is `Specific Workrooms`. Accepts `wrm_`-prefixed or raw ids; stored raw."}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"Scorecard":{"type":"object","description":"Account-wide metrics table. Shaped identically regardless of whether the underlying doc was created by this API or by the legacy dashboard (`Apps::ajaxSaveScorecard()`) — both write the same fields to the same `scorecards` collection.\n","properties":{"id":{"$ref":"#/components/schemas/ScorecardId"},"object":{"type":"string","enum":["scorecard"]},"name":{"type":"string"},"type":{"type":"string","description":"Chart/display type — one of `Table`, `Metric`, `Line`, `Bar`, `Trend` (the values the dashboard renders; `Trend` is legacy and charted like `Line`). Writes accept these case-insensitively (also `# Metric`, `bar_chart`, ...) and store the canonical spelling; anything else is a 422. Scorecards saved before this check may still carry another value."},"breakdown":{"type":"string","description":"How rows are sliced — one of `None` (aggregate only), `Source`, `Location`, `Workroom`, `Responsible User`. Writes accept these case-insensitively (also `responsible_user`, `staff`, `aggregate`) and store the canonical spelling; anything else is a 422. `None` is not available with type `Table` (as in the dashboard). Only `Responsible User`, `Location`, and `Workroom` have corresponding `*_type`/`*_ids` side fields (see below); `None` and `Source` leave all three side-field groups null."},"metrics":{"type":"array","items":{"type":"string"},"description":"Metric names to track (e.g. \"New Contacts\", \"Total Contacts\"). Every element must be a non-empty string — an object or other non-string element is rejected with a 400/422, not silently coerced."},"pipeline_ids":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"},"description":"Optional. Restricts pipeline-related metrics to these pipelines."},"total_rollup":{"type":"boolean","description":"Add a combined total-rollup row across all breakdown groups."},"responsible_user_role":{"type":"string","nullable":true,"description":"Only populated when `breakdown` is `Responsible User`. Dashboard UI offers All, Admin, WorkroomAdmin, Marketing, Sales, Analyst, Specific Users."},"responsible_user_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw staff-record ids (not `usr_`-prefixed) — only populated when `responsible_user_role` is `Specific Users`."},"location_type":{"type":"string","nullable":true,"description":"Only populated when `breakdown` is `Location`. Dashboard UI offers All, Specific Locations."},"location_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw location values — only populated when `location_type` is `Specific Locations`."},"workroom_type":{"type":"string","nullable":true,"description":"Report-breakdown dimension only — unrelated to the `Gleantap-Workroom` request-scoping header/query. Only populated when `breakdown` is `Workroom`. Dashboard UI offers All, Specific Workrooms."},"workroom_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw workroom ids — only populated when `workroom_type` is `Specific Workrooms`."},"workroom_scoped":{"type":"boolean","const":false,"description":"Always `false`. The underlying `scorecards` collection has no app_id/workroom field at all, so this resource is account-wide regardless of any `Gleantap-Workroom` header/`?workroom=` hint on the request — see `scope_note`."},"scope_note":{"type":"string","description":"Plain-English restatement of `workroom_scoped`, always present so a caller does not have to infer scoping behavior from testing."},"calculation_status":{"type":"string","enum":["pending","calculating","completed","error"],"description":"Derived from the same fields the existing periodic `Cron::calculateScorecards()` sweep reads/writes on this same doc — this endpoint never computes metric values itself. A fresh scorecard reads `pending` until that sweep's next pass. Editing a scorecard (PATCH) clears its last calculation time, so it reads `pending` until the sweep recalculates it. A scorecard that completed calculation but produced no metric values reads `error` with an explanation in `calculation_error`. The sweep runs overnight (01:06–09:45 UTC); until then the dashboard shows the previous values, and its refresh button recalculates on demand.\n"},"calculation_error":{"type":"string","nullable":true,"description":"Explanation when calculation_status is error (e.g. calculation failed or produced no metric values)."},"metrics_calculated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metrics_values":{"type":"object","nullable":true,"additionalProperties":true,"description":"Computed metric values, keyed and shaped per `breakdown`/`type` with numeric counts. Omitted (`null`) in list responses by default unless `include_values=true` is requested. Empty object until the first calculation pass completes."},"inactive":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"ScorecardId":{"type":"string","pattern":"^scr_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"TooManyRequests":{"description":"Rate limited.","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"headers":{"RetryAfter":{"description":"On 429, seconds to wait before retrying.","schema":{"type":"integer"}}}},"paths":{"/scorecards":{"post":{"tags":["Scorecards"],"operationId":"createScorecard","summary":"Create a scorecard.","description":"Writes only the scorecard definition — metric values are computed asynchronously by the existing periodic dashboard cron (`Cron::calculateScorecards()`), the same job that has always computed them for dashboard-created scorecards; this endpoint does not trigger it synchronously. Returns 202, not 201: the response body is the full definition with `calculation_status: \"pending\"`, not yet-computed values. Poll `GET /scorecards/{id}` for `calculation_status` to flip to `completed`.\n\nRequires the name and what it measures. Optional fields fall back to a server-side default when omitted. That includes the workroom: an omitted workroom resolves to the account default, and a record created in the wrong workroom is invisible where it was expected. Half-specified records are created successfully and then have to be hunted down and fixed by hand.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScorecardCreate"}}}},"responses":{"202":{"description":"Scorecard definition created; metric calculation is pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scorecard"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}}}
```

## Retrieve one scorecard.

> A scorecard's definition and its current metric values.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"Scorecard":{"type":"object","description":"Account-wide metrics table. Shaped identically regardless of whether the underlying doc was created by this API or by the legacy dashboard (`Apps::ajaxSaveScorecard()`) — both write the same fields to the same `scorecards` collection.\n","properties":{"id":{"$ref":"#/components/schemas/ScorecardId"},"object":{"type":"string","enum":["scorecard"]},"name":{"type":"string"},"type":{"type":"string","description":"Chart/display type — one of `Table`, `Metric`, `Line`, `Bar`, `Trend` (the values the dashboard renders; `Trend` is legacy and charted like `Line`). Writes accept these case-insensitively (also `# Metric`, `bar_chart`, ...) and store the canonical spelling; anything else is a 422. Scorecards saved before this check may still carry another value."},"breakdown":{"type":"string","description":"How rows are sliced — one of `None` (aggregate only), `Source`, `Location`, `Workroom`, `Responsible User`. Writes accept these case-insensitively (also `responsible_user`, `staff`, `aggregate`) and store the canonical spelling; anything else is a 422. `None` is not available with type `Table` (as in the dashboard). Only `Responsible User`, `Location`, and `Workroom` have corresponding `*_type`/`*_ids` side fields (see below); `None` and `Source` leave all three side-field groups null."},"metrics":{"type":"array","items":{"type":"string"},"description":"Metric names to track (e.g. \"New Contacts\", \"Total Contacts\"). Every element must be a non-empty string — an object or other non-string element is rejected with a 400/422, not silently coerced."},"pipeline_ids":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"},"description":"Optional. Restricts pipeline-related metrics to these pipelines."},"total_rollup":{"type":"boolean","description":"Add a combined total-rollup row across all breakdown groups."},"responsible_user_role":{"type":"string","nullable":true,"description":"Only populated when `breakdown` is `Responsible User`. Dashboard UI offers All, Admin, WorkroomAdmin, Marketing, Sales, Analyst, Specific Users."},"responsible_user_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw staff-record ids (not `usr_`-prefixed) — only populated when `responsible_user_role` is `Specific Users`."},"location_type":{"type":"string","nullable":true,"description":"Only populated when `breakdown` is `Location`. Dashboard UI offers All, Specific Locations."},"location_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw location values — only populated when `location_type` is `Specific Locations`."},"workroom_type":{"type":"string","nullable":true,"description":"Report-breakdown dimension only — unrelated to the `Gleantap-Workroom` request-scoping header/query. Only populated when `breakdown` is `Workroom`. Dashboard UI offers All, Specific Workrooms."},"workroom_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw workroom ids — only populated when `workroom_type` is `Specific Workrooms`."},"workroom_scoped":{"type":"boolean","const":false,"description":"Always `false`. The underlying `scorecards` collection has no app_id/workroom field at all, so this resource is account-wide regardless of any `Gleantap-Workroom` header/`?workroom=` hint on the request — see `scope_note`."},"scope_note":{"type":"string","description":"Plain-English restatement of `workroom_scoped`, always present so a caller does not have to infer scoping behavior from testing."},"calculation_status":{"type":"string","enum":["pending","calculating","completed","error"],"description":"Derived from the same fields the existing periodic `Cron::calculateScorecards()` sweep reads/writes on this same doc — this endpoint never computes metric values itself. A fresh scorecard reads `pending` until that sweep's next pass. Editing a scorecard (PATCH) clears its last calculation time, so it reads `pending` until the sweep recalculates it. A scorecard that completed calculation but produced no metric values reads `error` with an explanation in `calculation_error`. The sweep runs overnight (01:06–09:45 UTC); until then the dashboard shows the previous values, and its refresh button recalculates on demand.\n"},"calculation_error":{"type":"string","nullable":true,"description":"Explanation when calculation_status is error (e.g. calculation failed or produced no metric values)."},"metrics_calculated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metrics_values":{"type":"object","nullable":true,"additionalProperties":true,"description":"Computed metric values, keyed and shaped per `breakdown`/`type` with numeric counts. Omitted (`null`) in list responses by default unless `include_values=true` is requested. Empty object until the first calculation pass completes."},"inactive":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"ScorecardId":{"type":"string","pattern":"^scr_[0-9a-f]{24}$"},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/scorecards/{id}":{"get":{"tags":["Scorecards"],"operationId":"retrieveScorecard","summary":"Retrieve one scorecard.","description":"A scorecard's definition and its current metric values.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scorecard"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Update a scorecard definition.

> Partial update — only send the fields you want to change. Per \`update\_for\_account()\`, any successful update unconditionally queues the scorecard for recalculation (\`calculation\_status\` reverts to \`pending\`) regardless of which fields changed — there is no field-level diffing that skips recalculation for a cosmetic-only change (e.g. renaming). This matches the legacy dashboard's own full-form save behavior. Changing \`breakdown\` recomputes all three breakdown side-field groups (\`responsible\_user\_\*\`, \`location\_\*\`, \`workroom\_\*\`) from this same request body — the other two groups are cleared.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"schemas":{"ScorecardUpdate":{"type":"object","description":"Fields to update on a scorecard. All fields are optional.","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["Table","Metric","Line","Bar","Trend"],"description":"Case-insensitive; stored canonical. Any other value is a 422. See the Scorecard schema."},"breakdown":{"type":"string","enum":["None","Source","Location","Workroom","Responsible User"],"description":"Case-insensitive; stored canonical. Any other value is a 422, as is `None` with type `Table`. See the Scorecard schema."},"metrics":{"type":"array","minItems":1,"items":{"type":"string"},"description":"Non-empty array of metric names. Every element must be a non-empty string."},"pipeline_ids":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"}},"total_rollup":{"type":"boolean","default":false},"responsible_user_role":{"type":"string","description":"Used when `breakdown` is `Responsible User`. Use `Specific Users` with `responsible_user_ids` to restrict."},"responsible_user_ids":{"type":"array","items":{"type":"string"},"description":"Only used when `responsible_user_role` is `Specific Users`. Accepts `usr_`-prefixed or raw ids; stored raw."},"location_type":{"type":"string","description":"Used when `breakdown` is `Location`. Use `Specific Locations` with `location_ids` to restrict."},"location_ids":{"type":"array","items":{"type":"string"},"description":"Only used when `location_type` is `Specific Locations`."},"workroom_type":{"type":"string","description":"Report-breakdown dimension only — see the Scorecard schema. Used when `breakdown` is `Workroom`. Use `Specific Workrooms` with `workroom_ids` to restrict."},"workroom_ids":{"type":"array","items":{"type":"string"},"description":"Only used when `workroom_type` is `Specific Workrooms`. Accepts `wrm_`-prefixed or raw ids; stored raw."}}},"PipelineId":{"type":"string","pattern":"^pip_[0-9a-f]{24}$"},"Scorecard":{"type":"object","description":"Account-wide metrics table. Shaped identically regardless of whether the underlying doc was created by this API or by the legacy dashboard (`Apps::ajaxSaveScorecard()`) — both write the same fields to the same `scorecards` collection.\n","properties":{"id":{"$ref":"#/components/schemas/ScorecardId"},"object":{"type":"string","enum":["scorecard"]},"name":{"type":"string"},"type":{"type":"string","description":"Chart/display type — one of `Table`, `Metric`, `Line`, `Bar`, `Trend` (the values the dashboard renders; `Trend` is legacy and charted like `Line`). Writes accept these case-insensitively (also `# Metric`, `bar_chart`, ...) and store the canonical spelling; anything else is a 422. Scorecards saved before this check may still carry another value."},"breakdown":{"type":"string","description":"How rows are sliced — one of `None` (aggregate only), `Source`, `Location`, `Workroom`, `Responsible User`. Writes accept these case-insensitively (also `responsible_user`, `staff`, `aggregate`) and store the canonical spelling; anything else is a 422. `None` is not available with type `Table` (as in the dashboard). Only `Responsible User`, `Location`, and `Workroom` have corresponding `*_type`/`*_ids` side fields (see below); `None` and `Source` leave all three side-field groups null."},"metrics":{"type":"array","items":{"type":"string"},"description":"Metric names to track (e.g. \"New Contacts\", \"Total Contacts\"). Every element must be a non-empty string — an object or other non-string element is rejected with a 400/422, not silently coerced."},"pipeline_ids":{"type":"array","items":{"$ref":"#/components/schemas/PipelineId"},"description":"Optional. Restricts pipeline-related metrics to these pipelines."},"total_rollup":{"type":"boolean","description":"Add a combined total-rollup row across all breakdown groups."},"responsible_user_role":{"type":"string","nullable":true,"description":"Only populated when `breakdown` is `Responsible User`. Dashboard UI offers All, Admin, WorkroomAdmin, Marketing, Sales, Analyst, Specific Users."},"responsible_user_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw staff-record ids (not `usr_`-prefixed) — only populated when `responsible_user_role` is `Specific Users`."},"location_type":{"type":"string","nullable":true,"description":"Only populated when `breakdown` is `Location`. Dashboard UI offers All, Specific Locations."},"location_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw location values — only populated when `location_type` is `Specific Locations`."},"workroom_type":{"type":"string","nullable":true,"description":"Report-breakdown dimension only — unrelated to the `Gleantap-Workroom` request-scoping header/query. Only populated when `breakdown` is `Workroom`. Dashboard UI offers All, Specific Workrooms."},"workroom_ids":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Raw workroom ids — only populated when `workroom_type` is `Specific Workrooms`."},"workroom_scoped":{"type":"boolean","const":false,"description":"Always `false`. The underlying `scorecards` collection has no app_id/workroom field at all, so this resource is account-wide regardless of any `Gleantap-Workroom` header/`?workroom=` hint on the request — see `scope_note`."},"scope_note":{"type":"string","description":"Plain-English restatement of `workroom_scoped`, always present so a caller does not have to infer scoping behavior from testing."},"calculation_status":{"type":"string","enum":["pending","calculating","completed","error"],"description":"Derived from the same fields the existing periodic `Cron::calculateScorecards()` sweep reads/writes on this same doc — this endpoint never computes metric values itself. A fresh scorecard reads `pending` until that sweep's next pass. Editing a scorecard (PATCH) clears its last calculation time, so it reads `pending` until the sweep recalculates it. A scorecard that completed calculation but produced no metric values reads `error` with an explanation in `calculation_error`. The sweep runs overnight (01:06–09:45 UTC); until then the dashboard shows the previous values, and its refresh button recalculates on demand.\n"},"calculation_error":{"type":"string","nullable":true,"description":"Explanation when calculation_status is error (e.g. calculation failed or produced no metric values)."},"metrics_calculated_at":{"$ref":"#/components/schemas/Timestamp","nullable":true},"metrics_values":{"type":"object","nullable":true,"additionalProperties":true,"description":"Computed metric values, keyed and shaped per `breakdown`/`type` with numeric counts. Omitted (`null`) in list responses by default unless `include_values=true` is requested. Empty object until the first calculation pass completes."},"inactive":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"ScorecardId":{"type":"string","pattern":"^scr_[0-9a-f]{24}$"},"Timestamp":{"type":"string","format":"date-time","description":"RFC 3339 timestamp, always UTC, millisecond precision."},"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or failed validation.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"Semantic validation failed — the request is well-formed but references an object in the wrong state (e.g., sending to an opted-out contact).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/scorecards/{id}":{"patch":{"tags":["Scorecards"],"operationId":"updateScorecard","summary":"Update a scorecard definition.","description":"Partial update — only send the fields you want to change. Per `update_for_account()`, any successful update unconditionally queues the scorecard for recalculation (`calculation_status` reverts to `pending`) regardless of which fields changed — there is no field-level diffing that skips recalculation for a cosmetic-only change (e.g. renaming). This matches the legacy dashboard's own full-form save behavior. Changing `breakdown` recomputes all three breakdown side-field groups (`responsible_user_*`, `location_*`, `workroom_*`) from this same request body — the other two groups are cleared.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScorecardUpdate"}}}},"responses":{"200":{"description":"OK — definition updated synchronously; recalculation is still async (see `calculation_status`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scorecard"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}}}
```

## DELETE /scorecards/{id}

> 'No reference-counting or \`force\` needed — a scorecard is a read-only report over other entities; nothing else in the data model references a scorecard by id.'\
> \
> \*\*Permanent.\*\* There is no undo and no trash to restore from. Anything that references the deleted record is affected too.<br>

```json
{"openapi":"3.1.0","info":{"title":"Gleantap API v3","version":"2026-05-27"},"tags":[{"name":"Scorecards","description":"Account-wide metrics tables, broken down by Responsible User, Location, or Workroom (a reporting/analytics view, not a contact-scoring mechanism). This resource only writes the scorecard definition; metric values are computed asynchronously by the same periodic job that has always computed them for dashboard-created scorecards, so a newly created or edited scorecard reads `calculation_status: \"pending\"` until that job's next sweep. Account-scoped only — see the `workroom_scoped` field on every response.\n"}],"servers":[{"url":"https://api.gleantap.com/v3","description":"Production. There is no separate sandbox."}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"gltp_sk_*","description":"The **API Secret** from the Gleantap dashboard under **Settings → API** (Generate New Key if none exists). Send it bare (40 hex characters) or prefixed as `gltp_sk_live_<40-hex>`. There is no sandbox: every key acts on the live account.\n\nKeys are account-scoped and carry all permissions on that account (no per-key scope selection). Cross-workroom reads are unrestricted by default — narrow with `?workroom=` / `Gleantap-Workroom` on each request. Revoke via the dashboard.\n\nFor per-user consent, per-workroom scoping, and short-lived tokens, use OAuth 2.1 instead.\n"}},"parameters":{"VersionHeader":{"name":"Gleantap-Version","in":"header","required":false,"description":"Minor version to run the request under (date-based). Older dates remain supported for at least 24 months. If omitted, the account's default pinned version is used.\n","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"AccountHeader":{"name":"Gleantap-Account","in":"header","required":false,"description":"Target customer account, as `acc_<24-hex>` or a bare 24-hex ID. **Only for Gleantap staff (CSM) tokens**, which authenticate against the internal staff directory and are bound to no account; for a normal customer token the account is fixed by the token and this header is ignored.\n\nA staff token MUST name an account on every request — there is no default, and omitting it returns 400 `admin_account_required` rather than falling back to some first account. Switching accounts is just a different value here; no re-authorization. Account *names* are rejected (400 `admin_account_invalid`) because they are neither unique nor stable — list IDs with `GET /v3/accounts`.\n\nEvery impersonated response carries an `impersonation` block naming the account actually acted on, so an account switch mid-session is always visible. Also settable via `?account=`.\n","schema":{"type":"string"}},"WorkroomHeader":{"name":"Gleantap-Workroom","in":"header","required":false,"description":"Which workroom to act in. Accepts a workroom name (case-insensitive), a prefixed ID (`wrm_<hex>`), a raw 24-hex ID, or the literal `all`.\n\n**On any write, ask the user which workroom — do not omit this.** Optional here means the server has a fallback, not that the fallback is what anyone wanted: an omitted workroom sends the write to the account's *default* workroom, and accounts routinely have dozens. Creating a contact, flow, campaign or segment in the wrong workroom puts it where nobody is looking, and moving it afterwards is manual.\n\nThe one case where you need not ask: the account has exactly one workroom. Call `listWorkrooms` to find out — if it returns a single row, use it; if it returns several, ask which one before writing.\n\n**Reads are scoped too.** Omitting a workroom on a read does not span the account — it narrows to the same default workroom a write would go to, and the response carries a `workroom_defaulted` warning saying so. So a count, a list or a segment preview describes *one* workroom unless you said otherwise. Pass `all` to deliberately span every workroom; that is the only way to get account-wide figures, and it is never the default. `listWorkrooms` itself is never narrowed, since it is how you discover what to ask for.\n\nAlso settable via `?workroom=` or a `workroom` body field (POST/PATCH only) — query wins over header wins over body.\n","schema":{"type":"string"}}},"responses":{"NotFound":{"description":"The resource doesn't exist or isn't visible to this caller.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","description":"RFC 9457 Problem Details with Gleantap extensions. Every error response follows this shape.\nHandle by inspecting the `code` field (not the human-readable `title` or `detail`), which is stable across versions.\n","required":["type","title","status","code","request_id"],"properties":{"type":{"type":"string","format":"uri","description":"URL to the human-readable error documentation."},"title":{"type":"string","description":"Short human-readable summary."},"status":{"type":"integer","description":"HTTP status code repeated in the body for convenience."},"detail":{"type":"string","description":"Longer human-readable explanation. May be null.","nullable":true},"code":{"type":"string","description":"Machine-readable error code. This is the field to switch on programmatically.\nStandard values include: `authentication_required`, `invalid_credentials`, `permission_denied`, `scope_required`, `resource_not_found`, `validation_error`, `invalid_field`, `missing_field`, `idempotency_conflict`, `rate_limited`, `quota_exceeded`, `internal_error`, `service_unavailable`, `feature_not_enabled`, `compliance_block`, `version_conflict`.\n"},"request_id":{"type":"string","description":"The X-Request-ID for this response. Include when reporting issues."},"errors":{"type":"array","nullable":true,"description":"Field-level details, present on validation errors.","items":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"paths":{"/scorecards/{id}":{"delete":{"tags":["Scorecards"],"operationId":"deleteScorecard","description":"'No reference-counting or `force` needed — a scorecard is a read-only report over other entities; nothing else in the data model references a scorecard by id.'\n\n**Permanent.** There is no undo and no trash to restore from. Anything that references the deleted record is affected too.\n","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/AccountHeader"},{"$ref":"#/components/parameters/WorkroomHeader"}],"responses":{"204":{"description":"Deleted."},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
