Capture requests

A capture request is a question you send to people, and the recordings that come back. Send it to a roster of named contacts, or share one open link.

Requests created through the API belong to your organization rather than to a studio, so you do not need a studio to collect anything.

Create one

curl -X POST https://capturly.app/api/v1/capture-requests \
  -H "Authorization: Bearer cap_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer stories",
    "prompt": "How did the rollout go?",
    "status": "active",
    "maxDurationSec": 300,
    "metadata": { "crm_id": "C-42" }
  }'

Requests start as draft unless you pass status: "active". A draft collects nothing: its links resolve to a “not accepting takes” page. That gap exists so you can build a roster before anything goes live, and passing active skips it.

metadata is yours. It is stored verbatim and returned on every read, so you can carry your own correlation ids without Capturly modelling your domain.

Add people

curl -X POST https://capturly.app/api/v1/capture-requests/{id}/contacts \
  -H "Authorization: Bearer cap_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "contacts": [{ "email": "jane@example.com", "name": "Jane Doe" }] }'

The response carries each contact’s personal link. Adding a contact does not email them. Sending is yours, which keeps the message in your voice and your sending reputation in your control.

Addresses on your organization’s suppression list — unsubscribes, bounces and spam complaints — are skipped and reported back by address. That list is not advisory, and this path honours it exactly as the dashboard does.

Read what came back

curl https://capturly.app/api/v1/capture-requests/{id}/submissions \
  -H "Authorization: Bearer cap_live_..."

Each submission carries the consent record frozen at the moment it was accepted:

{
  "id": "sub_...",
  "displayName": "Jane Doe",
  "recordingId": "rec_...",
  "durationSec": 92,
  "viaOpenLink": false,
  "consent": {
    "text": "I grant permission for this recording…",
    "version": "default:v1",
    "acceptedAt": "2026-09-08T12:00:00.000Z",
    "ipAddress": "203.0.113.5",
    "subjectName": "Jane Doe"
  }
}

consent.text is stored verbatim as it was displayed. Editing the request’s release wording later never changes what a past respondent appears to have agreed to.

Two fields decide whether the footage is still there. recordingId is null once the take has passed its retention window and been deleted — the submission survives as the record that the person answered, and footageExpiredAt says when the video went. previousTakeAt is set when this take replaced an earlier answer from the same person: re-recording deletes the previous take outright, so anything you mirrored from that timestamp no longer exists. Treat a null recordingId as “collected, no longer fetchable” rather than as an error.

A version of legacy means the record was backfilled when consent records were introduced, and the text is the request’s wording at migration time rather than what that person actually saw. Check for it before relying on a record as evidence.

The recording itself is a normal library recording. Read it through /v1/recordings/{id} for its tracks and their capture manifests.

Closing

curl -X POST https://capturly.app/api/v1/capture-requests/{id}/close \
  -H "Authorization: Bearer cap_live_..."

Closing is terminal and kills every outstanding link at once. Links already sitting in inboxes begin rendering the “not accepting takes” page immediately. There is no reopen: resurrecting links people were told were finished would surprise them.

A deadline closes a request the same way, and fires the same capture_request.closed event with reason: "deadline_passed".

Endpoints

Deleting a request removes its roster and the rows linking takes to it. The footage survives as ordinary library recordings. One consequence worth knowing: a consent record’s durable attribution is its capture request, so deleting the request leaves the releases attributable to your organization and nothing narrower. Close a request instead when the consent trail matters.