---
title: Read an approval request
url: /docs/developers/reference/approvals-read
---

# Read an approval request

`approvals.read@1`

Reads a request your own key asked a person to approve, such as a paid picture from [Start social post drafts](social-posts-generate.md). The answer says where it stands (`waiting`, `approved`, `declined`, `expired` or `withdrawn`), what exactly would change, how many people can answer it and, once a person approved it, what it became. Your team's names are never shown to a key: every person appears as `A person on your team`. A key sees only the requests it asked: another key, or another business, gets `APPROVAL.UNKNOWN`. A key can never approve or decline anything, its own included; a person does that in GrowLocal. Keys created before this read was added, or without an **act** area, cannot read it: send the same call again with the same `operationId` instead, which answers the request it is waiting on, or what it became.

## See where an approval stands

Use `core.approvals` as the `featureId` in place of `YOUR_FEATURE_ID`, and replace the reference with the `approvalRequestRef` your call's `requirements` answer gave. Reading changes nothing.

```curl tabs
# A new operationId for each new request; the same one to retry it.
curl https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations \
  -H "Authorization: Bearer gl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": {
    "featureId": "YOUR_FEATURE_ID",
    "export": "readApproval",
    "contractRef": "approvals.read@1"
  },
  "operationId": "read-approval-1",
  "input": {
    "approvalRequestRef": "11111111-2222-4333-8444-555555555555"
  }
}'
```

```javascript tabs
// A new operationId for each new request; the same one to retry it.
const response = await fetch(
  "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer gl_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      "target": {
        "featureId": "YOUR_FEATURE_ID",
        "export": "readApproval",
        "contractRef": "approvals.read@1"
      },
      "operationId": "read-approval-1",
      "input": {
        "approvalRequestRef": "11111111-2222-4333-8444-555555555555"
      }
    }),
  },
);
const receipt = await response.json();
console.log(response.status, receipt);
```

```python tabs
import requests

# A new operationId for each new request; the same one to retry it.
response = requests.post(
    "https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
    headers={"Authorization": "Bearer gl_YOUR_API_KEY"},
    json={
        "target": {
            "featureId": "YOUR_FEATURE_ID",
            "export": "readApproval",
            "contractRef": "approvals.read@1",
        },
        "operationId": "read-approval-1",
        "input": {
            "approvalRequestRef": "11111111-2222-4333-8444-555555555555",
        },
    },
    timeout=30,
)
print(response.status_code, response.json())
```

## Parameters

What goes in `input`:

| Name | Type | Required | Description |
|---|---|---|---|
| `approvalRequestRef` | string | Yes | The request to read: the `approvalRequestRef` in the `requirements` answer you got when a person's approval was needed. |

## Response

A call that worked answers `200` with an `applied` receipt; its `output` holds these fields, among others. `GET /catalog/approvals.read@1` answers the complete shape as JSON Schema.

| Name | Type | Description |
|---|---|---|
| `approvalRequestRef` | string | The request. |
| `revision` | integer | Changes each time the request does. |
| `state` | one of `waiting`, `approved`, `declined`, `expired`, `withdrawn` | `waiting` for a person's answer, `approved`, `declined`, `expired` after a day without an answer, or `withdrawn`. Nothing was made unless it is `approved` and its `outcome` is `applied`. |
| `requester` | object | Who asked: your key, named by `kind` `api-key` and the name you gave it. |
| `actingFor` | object | The member whose authority the key acts under, shown only as `A person on your team`. |
| `operation` | object | What would run, in plain words. |
| `operation.title` | string | The operation's plain title. |
| `operation.ask` | string | What is asked, after "asks to". |
| `approver` | object or null | The person who answered, once someone has, shown only as `A person on your team`. |
| `answeredAt` | string (date-time) or null | When it was answered, or `null`. |
| `expiresAt` | string (date-time) | When it expires if nobody answers. |
| `outcome` | object or null | What the approved call became once it ran: the same answer the call itself gives. `null` before that. |
| `youMayAnswer` | boolean | Always `false` for a key. |
| `askedByYou` | boolean | `true`: your key asked it. |
| `preview` | object or null | The exact change a person is shown to approve, in its owner's words (for a paid picture: the recipe, the accounts and the estimated price), or `null`. |
| `askedOf` | array of object | One entry for each person who may answer while it waits, so you can count them; none is named. |

```json title="Response"
{
  "status": "applied",
  "operationId": "read-approval-1",
  "output": {
    "approvalRequestRef": "11111111-2222-4333-8444-555555555555",
    "revision": 1,
    "state": "waiting",
    "requester": {
      "ref": "api-key:YOUR_KEY_ID",
      "kind": "api-key",
      "name": "Nightly job"
    },
    "actingFor": {
      "ref": "redacted",
      "kind": "member",
      "name": "A person on your team"
    },
    "operation": {
      "contractRef": "social.posts.generate@1",
      "title": "Start social post drafts",
      "targetRef": "juniper-cakes.social",
      "ask": "make illustrated draft posts",
      "activity": "making one paid AI illustration and draft posts"
    },
    "askedBecause": "role",
    "askRuleRefs": [],
    "approver": null,
    "answeredAt": null,
    "expiresAt": "2026-01-02T09:00:00Z",
    "createdAt": "2026-01-01T09:00:00Z",
    "outcome": null,
    "youMayAnswer": false,
    "askedByYou": true,
    "preview": {
      "name": "An illustrated brand post",
      "changes": [
        "One AI illustration, shared by these accounts",
        "Makes drafts only. Nothing is posted."
      ],
      "steps": [
        "Make one picture, then editable branded drafts."
      ]
    },
    "subject": null,
    "askedOf": [
      {
        "ref": "redacted",
        "kind": "member",
        "name": "A person on your team"
      }
    ]
  }
}
```

## Errors

It reads and changes nothing. Besides the answers every request can get ([Errors](../errors.md)), its receipt can say:

| Status | HTTP | What it means |
|---|---|---|
| `rejected` | 400, or 403 when it's a matter of access | Not done. `diagnostics` says why: each has a `code`, a `path` into what you sent and a `message`. |

The codes in `diagnostics` you're most likely to see:

| Code | Status | What it means |
|---|---|---|
| `APPROVAL.UNKNOWN` | `rejected` | No such request here for this key: it does not exist, belongs to another business, or was asked by another key. |
| `APPROVAL.SCOPE_DENIED` | `rejected` | This key can't read approvals. Create a new key with an **act** area. |
