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. 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.

# 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"
  }
}'
// 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);
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.
{
  "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), 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.