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