curl --request GET \
--url https://app.vumasign.com/api/v1/envelopes \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.vumasign.com/api/v1/envelopes"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.vumasign.com/api/v1/envelopes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.vumasign.com/api/v1/envelopes"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"data": [
{
"id": "01960000-0000-4000-8000-0000000000e5",
"title": "Employment contract",
"status": "sent",
"template_id": "01960000-0000-4000-8000-0000000007e1",
"reference": "hire-2026-0917",
"created_at": "2026-09-02T09:00:00.000Z",
"sent_at": "2026-09-02T09:05:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}List envelopes, newest first, optionally filtered by status or by your reference.
GET /api/v1/envelopes/{envelopeId} reads one envelope by an id you already hold; this is how you find out which ids exist. The webhook delivery ladder gives up after 7 attempts, so an integrator who dropped a delivery has no way to learn what was missed except by asking here.
Walked by keyset cursor rather than by offset, for the same reason GET /api/v1/templates is: this list is ordered newest first, so an envelope created between page 1 and page 2 would shift every row down under an offset, and a caller would receive one row twice and never see another.
⚠️ cursor IS OPAQUE. It is the last envelope’s id in clear, but that is an implementation detail rather than a promise — pass back exactly the next_cursor a previous page gave you and never construct one by hand. A well-formed uuid naming no envelope of yours (yours or another organisation’s — this endpoint cannot tell the two apart, and does not try) is refused rather than answered with an empty page, for the same reason an unknown status is below: an empty page reads as “you have none”, which is the single hardest defect class to notice because it looks exactly like data.
EACH ROW IS A SUMMARY, not the full Envelope GET /api/v1/envelopes/{envelopeId} returns — no recipients, no delivery state. Read one envelope in full once you know which one you want.
RECONCILING A LOST REQUEST IS ONE CALL WITH ?reference=. Set a reference of your own when you create an envelope, and if you never learn what that request did, list by it: a row means it was created, no row means it was not. Make your references unique if you want exactly one — we do not.
curl --request GET \
--url https://app.vumasign.com/api/v1/envelopes \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.vumasign.com/api/v1/envelopes"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.vumasign.com/api/v1/envelopes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://app.vumasign.com/api/v1/envelopes"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"data": [
{
"id": "01960000-0000-4000-8000-0000000000e5",
"title": "Employment contract",
"status": "sent",
"template_id": "01960000-0000-4000-8000-0000000007e1",
"reference": "hire-2026-0917",
"created_at": "2026-09-02T09:00:00.000Z",
"sent_at": "2026-09-02T09:05:00.000Z"
}
],
"has_more": false,
"next_cursor": null
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>"
}
}Authorizations
Authorization: Bearer vsk_live_…. Chosen over a bespoke X-API-KEY header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see x-scopes at the root of this document and x-required-scope on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for oauth2 and openIdConnect and requires it to be empty for an http scheme.
Query Parameters
⚠️ A VALUE OUTSIDE THE RANGE IS REFUSED, NOT CLAMPED, for the same reason GET /api/v1/templates refuses one: a caller who asks for 1000 and receives 100 has a working integration reading their whole account in ten times the requests they budgeted, and nothing anywhere says so.
How many envelopes to return.
1 <= x <= 100⚠️ AN UNKNOWN VALUE IS REFUSED, NOT ANSWERED WITH AN EMPTY PAGE. A typo — "complete" for "completed" — would otherwise read as "you have none", which is data-shaped and is exactly the failure this refusal exists to avoid. Omit it to list every status.
Restrict the list to one status.
draft, sent, partially_signed, completed, declined, voided, expired Only envelopes whose reference is exactly this — the one call that tells you whether a create whose answer you lost made anything. Compared in Unicode NFC, whichever form you send it in; case and whitespace are significant. Combines with status and cursor, and the matches are newest first like the rest of the list.
⚠️ MORE THAN ONE ROW CAN MATCH. A reference is not unique unless you made it so. ⚠️ AN EMPTY OR OVER-LONG VALUE IS REFUSED, NOT ANSWERED — an empty ?reference= is not "no filter", and a value no reference can be would otherwise answer "nothing was created".
The reference you set on create: at most 255 UTF-16 code units once composed to NFC, as JavaScript counts string length: most characters count as one, some (outside the Basic Multilingual Plane, such as most emoji) count as two. No maxLength is declared, because JSON Schema counts code points and would admit a value the server refuses.
1"hire-2026-0917"
Response
A page of envelope summaries, newest first, with the cursor for the next.
The page.
Pass this as cursor for the next page. Null exactly when has_more is false -- the two are computed from one expression, so a true with a null cursor cannot happen. ⚠️ OPAQUE: it is the last envelope’s id, but that is an implementation detail rather than a promise -- pass it back exactly as received and never construct one by hand.