Expire or delete a request

DELETE /v1/requests/{shortCode}

Requires the requests:write scope.

One method, two outcomes

This endpoint does something the share equivalent does not: what it does depends on the request's current state.

A call on an active request closes the link and leaves every submission alone. A call on a request that is already expired removes the request record and the content of its live submissions, and that can be your first call: a request that reached its expired_at on its own goes straight to the second row.

The response says which happened rather than leaving you to infer it:

{
  "short_code": "a1b2c3d4",
  "outcome": "expired"
}

Request

curl -X DELETE https://api.credenshare.io/v1/requests/a1b2c3d4 \
  -H "Authorization: Bearer crs_sk_live_<keyId>.<authSecret>"

{shortCode} is the short_code from the create response, not a database id, and not a submission's short code.

What expiry means for submissions already received

Expiring a request through this endpoint closes the collect link and nothing else. Submissions already made are still there, and still readable through the submissions endpoint until their own expiry — an expired request is not the same as a deleted one. The app's Expire request now control is different: it scrubs the content of every live submission before it expires the request.

Permanent deletion removes the request record and destroys the content of any submission still live; a metadata audit row of each submission remains. A submission stops counting as active once it has expired and been cleared away, which happens within about an hour of its expiry. By default, submissions to a request created through this API expire 30 days after they are submitted. A request created in the app can instead count from first view. Its submissions then expire their chosen time after they are first opened in the app, and no later than 30 days plus that time after they were submitted. Reading them through the submissions endpoint does not start that countdown. The permanent delete is the API's way to clear them sooner. In the app, Delete expired request on the Expired tab scrubs the content of the remaining submissions and then removes the request. A submission that has already expired keeps only a metadata audit row; its content was removed when it expired. Once the request record is gone, its submissions are no longer listed through this API or in the app.

Ownership

Ownership is enforced in the handler, not in the service layer. The service permits a link-holder to delete in some configurations, which is correct for the recipient path in the app and wrong for a key acting on an account.

A short code on another account returns 404, indistinguishable from one that does not exist.

Errors

Once a request has been permanently deleted, further calls return 404. If your goal is "make sure this collect link is closed", treat both 200 and 404 as success — but see the warning above before retrying blindly.