Manage access requests through the APIBeta
List the people who asked to download or view a brand and approve or reject each request.
When a brand asks visitors for access, each request appears in the Requests tab of the brand, in Brand Pages. The Brand API lists those requests and makes the same decisions, so you can work from your own code. This page covers the calls that list requests and decide them.
Your token needs the brands:requests scope. This one scope covers both listing requests and deciding them, and it is separate from brands:read and brands:write. A token without it gets a 403 error. A missing or revoked token gets a 401 error. Create the token under Developers on the API Tokens tab, and follow the steps in the Brand API quick start.
The brand in each request is its id or its slug. A token only reaches the brands of its own workspace, and a brand of another workspace returns a 404 error. Each token can make 120 requests per minute. A request over that limit returns a 429 error with Retry-After: 60. Responses carry the header X-Tarkle-Api-Version: v1, and new fields can be added to v1 while a breaking change goes to a new version. The errors, paging and rate limits article describes the error format.
List requests
To list the requests of a brand, send a GET request for them, as Brand API endpoints describes. The response has data and next_cursor. Each request has id, kind (view or download), name, company, email, message, status, created_at and decided_at. The newest requests come first.
Set status to pending, approved or rejected to list one group. Any other status returns a 400 error.
A page holds 25 requests by default. Set limit from 1 to 100 to change the page size; any other value returns a 400 error. Send the next_cursor value of a response as cursor to get the next page, and stop when next_cursor is null. A page that is exactly full still returns a cursor, so the next call can come back empty, and then next_cursor is null.
Approve or reject
To decide one request, send a POST request for that request with the body { "action": "approve" } or { "action": "reject" }. The response contains the request id and its new status, which is approved or rejected. Any other action returns a 400 error, and so does a request id that is not valid. An unknown brand or request returns a 404 error.
You can change a decision: approving a rejected request, or rejecting an approved one, is allowed. Repeating the decision a request already has returns a 409 error, with the message "This request is already approved." or "This request is already rejected."
What each decision does
Approving a download request issues a new download link and emails it to the visitor. The response includes emailed, which is true when the email was sent and false when it was not. A failed email does not undo the approval, so the request stays approved. To send the link again, reject the request and then approve it, because approving an approved request is refused.
Approving a view request only marks it approved. It sends no email and creates no link, so the response has no emailed field. The brand page does not read this status, so approving a view request does not open the page for the visitor. Who can open a brand page explains how a visitor gets in.
Rejecting a request marks it rejected and takes back the link that was issued for it. No email is sent to the visitor.
The Requests tab makes the same decisions from the row menu. A request that is not approved shows Give access for a download request or Accept for a view request. A request that is not rejected shows Reject, and an approved one shows that item as Revoke access. An approved download request also shows Resend access, but that item sends the same approve action, which is refused while the request stays approved. To send the link again, use Revoke access and then Give access. Delete removes the request from the list, and the API has no delete call.
The Slack buttons make the same decision. If the request is no longer pending, the button replies that it is already approved or rejected. To turn on download approval for a brand, read How do download approval and access requests work?.