Signclad
Start free
Documentation

Reference

API reference

Getting started

Sending

Embedding

Events and errors

More

Admin API

Staff-only. Every route answers `404` to everyone else, so the existence of the surface is never confirmed to a stranger.

Updated

On this page

22 operations, generated from openapi/signclad.v1.yaml. Try them in the interactive reference, browse every endpoint group, or read the guides for the prose version.

GET /admin/lookup

Find an account Extension

Staff only. One search box over workspace ids, account ids, document ids, API key prefixes, emails, and names; matched_by says which one hit. At most 20 results, and the search itself is written to the staff audit log.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Query parameters

Name Type Required Description
q string Optional Anything identifying. An empty query returns an empty list.

Responses

Status Description
200 The matches.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X GET https://api.signclad.com/api/v1/admin/lookup \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /admin/accounts/{account}

Get an account overview Extension

Staff only. The workspace, its billing account, the current period's usage, the counts a support engineer asks for first, and the abuse reputation score.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
account string (uuid) A workspace id, despite the parameter's name — the staff surface is organized by workspace and reports the account behind it.

Responses

Status Description
200 The overview.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X GET https://api.signclad.com/api/v1/admin/accounts/{account} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /admin/accounts/{account}/members

List an account's members Extension

Staff only. Archived memberships included, with whether each has MFA enrolled.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
account string (uuid) A workspace id, despite the parameter's name — the staff surface is organized by workspace and reports the account behind it.

Responses

Status Description
200 The members.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X GET https://api.signclad.com/api/v1/admin/accounts/{account}/members \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /admin/accounts/{account}/keys

List an account's API keys Extension

Staff only. Prefixes and usage, never a secret or a hash — this view answers "is their key working", not "what is their key".

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
account string (uuid) A workspace id, despite the parameter's name — the staff surface is organized by workspace and reports the account behind it.

Responses

Status Description
200 The keys.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X GET https://api.signclad.com/api/v1/admin/accounts/{account}/keys \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /admin/accounts/{account}/webhooks

List an account's webhook endpoints Extension

Staff only. Health and the last failure, for "why are their webhooks not arriving".

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
account string (uuid) A workspace id, despite the parameter's name — the staff surface is organized by workspace and reports the account behind it.

Responses

Status Description
200 The endpoints.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X GET https://api.signclad.com/api/v1/admin/accounts/{account}/webhooks \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /admin/accounts/{account}/documents

List an account's documents Extension

Staff only. A metadata-only listing — names, states, counts, error messages. No fields, no recipients' values, no file contents.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
account string (uuid) A workspace id, despite the parameter's name — the staff surface is organized by workspace and reports the account behind it.

Query parameters

Name Type Required Description
state string Optional Internal state, not the wire status.
cursor string Optional Opaque cursor from a previous response's next_cursor.
limit integer Optional Items per page.

Responses

Status Description
200 A page of documents.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X GET https://api.signclad.com/api/v1/admin/accounts/{account}/documents \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /admin/accounts/{account}/audit

Read an account's audit log Extension

Staff only. The same entries the customer can read, flattened.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
account string (uuid) A workspace id, despite the parameter's name — the staff surface is organized by workspace and reports the account behind it.

Query parameters

Name Type Required Description
cursor string Optional Opaque cursor from a previous response's next_cursor.
limit integer Optional

Responses

Status Description
200 A page of entries.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X GET https://api.signclad.com/api/v1/admin/accounts/{account}/audit \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

PATCH /admin/accounts/{account}/plan

Override an account's plan Extension

Staff only. A reason of at least eight characters is required and is written to the staff audit log — an override nobody can explain later is not an override worth having.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
account string (uuid) A workspace id, despite the parameter's name — the staff surface is organized by workspace and reports the account behind it.

Request body

application/json

Property Type Required Description
plan string Required
reason string Required Why a staff member did this. At least eight characters, and written to the staff audit log — an override nobody can explain later is not one worth having.
interval string or null Optional

Responses

Status Description
200 The account overview, after the change.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
422 Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays.

Example request

curl -X PATCH https://api.signclad.com/api/v1/admin/accounts/{account}/plan \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/accounts/{account}/unban

Lift a suspension Extension

Staff only. Requires a reason, which is audited.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
account string (uuid) A workspace id, despite the parameter's name — the staff surface is organized by workspace and reports the account behind it.

Request body

application/json

Property Type Required Description
reason string Required Why a staff member did this. At least eight characters, and written to the staff audit log — an override nobody can explain later is not one worth having.

Responses

Status Description
200 The account overview.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
422 Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/accounts/{account}/unban \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /admin/accounts/{account}/refunds

List refunds Extension

Staff only. The 25 most recent refunds on this account.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
account string (uuid) A workspace id, despite the parameter's name — the staff surface is organized by workspace and reports the account behind it.

Responses

Status Description
200 The refunds.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X GET https://api.signclad.com/api/v1/admin/accounts/{account}/refunds \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/accounts/{account}/refunds

Issue a refund Extension

Staff only. target is a Stripe invoice or charge id — one starting in_ is read as an invoice. Over the configured ceiling the refund is refused and must be issued in Stripe with a second approver. A gateway failure still answers 200: the refund row exists with status: failed and a failure_message, because the attempt is part of the record.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
account string (uuid) A workspace id, despite the parameter's name — the staff surface is organized by workspace and reports the account behind it.

Request body

application/json

Property Type Required Description
amount_cents integer Required
reason string Required Why a staff member did this. At least eight characters, and written to the staff audit log — an override nobody can explain later is not one worth having.
target string Required
currency string Optional

Responses

Status Description
200 The refund — successful or failed — and the account's refund history.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
422 Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/accounts/{account}/refunds \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/documents/{document}/cancel

Cancel a document Extension

Staff only, with an audited reason. Crosses workspaces, which is the point.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
document string (uuid) The document's id. Staff routes are not scoped to a workspace.

Request body

application/json

Property Type Required Description
reason string Required Why a staff member did this. At least eight characters, and written to the staff audit log — an override nobody can explain later is not one worth having.

Responses

Status Description
200 The document.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
409 The request is well formed; the resource is not in a state that allows it.…
422 Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/documents/{document}/cancel \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/documents/{document}/complete

Manually complete a document Extension

Staff only, with an audited reason.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
document string (uuid) The document's id. Staff routes are not scoped to a workspace.

Request body

application/json

Property Type Required Description
reason string Required Why a staff member did this. At least eight characters, and written to the staff audit log — an override nobody can explain later is not one worth having.

Responses

Status Description
200 The document.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
409 The request is well formed; the resource is not in a state that allows it.…
422 Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/documents/{document}/complete \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/documents/{document}/release

Release a blocked document Extension

Staff only. Lets a document held for abuse review carry on, optionally naming which state to restore it to.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
document string (uuid) The document's id. Staff routes are not scoped to a workspace.

Request body

application/json

Property Type Required Description
reason string Required Why a staff member did this. At least eight characters, and written to the staff audit log — an override nobody can explain later is not one worth having.
restore_to string or null Optional

Responses

Status Description
200 The document.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
409 The request is well formed; the resource is not in a state that allows it.…
422 Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/documents/{document}/release \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/documents/{document}/resend

Resend a document's invitations Extension

Staff only. Optionally to named addresses; omitted, it goes to everyone still unsigned. The one admin write that takes no reason, because resending changes nothing.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
document string (uuid) The document's id. Staff routes are not scoped to a workspace.

Request body

application/json

Property Type Required Description
emails array of string (email) Optional

Responses

Status Description
200 The document, and who it went to.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
409 The request is well formed; the resource is not in a state that allows it.…
422 Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/documents/{document}/resend \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/impersonate/{user}

Start impersonating a user Extension

Staff only, with a reason and optionally a support ticket recorded. Staff accounts cannot be impersonated, and neither can yourself. The session runs until POST /admin/impersonate/stop, or until the grant is ended from another session. There is no expiry. While a grant is live the admin surface itself answers 404 — an impersonating session is the customer, not staff.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
user string The user to act as.

Request body

application/json

Property Type Required Description
reason string Required Why a staff member did this. At least eight characters, and written to the staff audit log — an override nobody can explain later is not one worth having.
ticket string or null Optional

Responses

Status Description
201 The grant.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
422 errors.user reads Staff accounts cannot be impersonated. or You are already signed in as yourself.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/impersonate/{user} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/impersonate/stop

Stop impersonating Extension

Hands the session back to the staff user. stopped: false means there was nothing to stop, which is not an error. This is the one admin route reachable while a grant is live.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Responses

Status Description
200 Stopped, or there was nothing to stop.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/impersonate/stop \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /admin/abuse/queue

Read the abuse review queue Extension

Staff only. Reports from signers, from the scorer, and from staff, with the workspace and document each concerns. An unrecognized status filter is quietly treated as open rather than refused.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Query parameters

Name Type Required Description
status string Optional
cursor string Optional Opaque cursor from a previous response's next_cursor.
limit integer Optional Items per page.

Responses

Status Description
200 A page of reports, and a tally by status. The tally omits statuses with no rows rather than reporting them as zero.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X GET https://api.signclad.com/api/v1/admin/abuse/queue \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

GET /admin/abuse/{report}

Get an abuse report Extension

Staff only. The report, plus up to ten other reports against the same workspace.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
report string (uuid) The abuse report's id.

Responses

Status Description
200 The report.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.

Example request

curl -X GET https://api.signclad.com/api/v1/admin/abuse/{report} \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/abuse/{report}/release

Release a reported document Extension

Staff only. Decides the report was unfounded and lets the document carry on. Only an open report can be decided; one already reviewed answers 409 naming who reviewed it, and that check runs before the body is validated.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
report string (uuid) The abuse report's id.

Request body

application/json

Property Type Required Description
reason string Required Why a staff member did this. At least eight characters, and written to the staff audit log — an override nobody can explain later is not one worth having.

Responses

Status Description
200 The decided report.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
409 The request is well formed; the resource is not in a state that allows it.…
422 Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/abuse/{report}/release \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/abuse/{report}/cancel

Cancel the reported document Extension

Staff only. Cancels the document but leaves the workspace alone.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
report string (uuid) The abuse report's id.

Request body

application/json

Property Type Required Description
reason string Required Why a staff member did this. At least eight characters, and written to the staff audit log — an override nobody can explain later is not one worth having.

Responses

Status Description
200 The decided report.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
409 The request is well formed; the resource is not in a state that allows it.…
422 Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/abuse/{report}/cancel \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"

POST /admin/abuse/{report}/ban

Suspend the workspace Extension

Staff only. Suspends the whole workspace, not just the document. `POST /admin/accounts/{account}/unban` is the way back.

Base URL
https://api.signclad.com/api/v1
Authentication
API key or OAuth 2.1 access token

Path parameters

Name Type Description
report string (uuid) The abuse report's id.

Request body

application/json

Property Type Required Description
reason string Required Why a staff member did this. At least eight characters, and written to the staff audit log — an override nobody can explain later is not one worth having.

Responses

Status Description
200 The decided report.
403 Staff, but without a second factor enrolled. This is the only non-404 refusal on the staff surface: everybody else — a stranger, a customer, an API key, an impersonating session — gets 404, so…
404 No such record for this workspace. Signclad never answers 404 for a record that exists: a 404 is authoritative.
409 The request is well formed; the resource is not in a state that allows it.…
422 Validation failed. errors maps a field name to a message string, or to an object keyed by an error code or by a per-item key. Values are never arrays.

Example request

curl -X POST https://api.signclad.com/api/v1/admin/abuse/{report}/ban \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"