Signer queue: list packages and record signatures

Signer-scoped endpoints are available to any user who has an active signer assignment in the Safeclose signing system. Every endpoint in this group enforces that the authenticated user is actually assigned to the package being accessed — you cannot read or sign documents on a package where you are not listed as a signer. If your Clerk account has no linked signer row, all endpoints in this group return 404. You can check caps.canViewSignerAssignments in the session payload before calling these routes.

Signer access is scoped strictly to packages you are assigned to. You cannot enumerate packages you are not assigned to, even if you also hold a manager role.

List your signing packages

Returns all signing packages you are assigned to as a signer, together with the parent signing rows. Results are ordered by most recently updated first and capped at 100 entries each.

GET /v1/signing/signer/signings

No query parameters.

curl https://api.safeclose.com/v1/signing/signer/signings \
  -H "Authorization: Bearer <clerk_jwt>"

Response

array

required

Your signer stub rows. Each object contains the fields below.

Show signer fields

string

required

The signer row ID (bigint serialized as string).

string

required

The parent signing package ID.

string

required

Current status of this signer assignment, e.g. "pending", "completed", "cancelled".

number or null

Signer position number within the package (1-indexed ordering).

string or null

Display name for this signer.

string or null

Email address for this signer assignment.

string

required

ISO 8601 timestamp of the last update to this signer row.

array

required

The parent signing package records for all packages in the signers list, deduplicated. Ordered by most recently updated first.

Error responses

Status	Condition
`404`	No signer assignment is linked to your account. Contact your manager to be assigned.

Get one signing package

Returns the full signing package record for a single package you are assigned to.

GET /v1/signing/signer/signings/:signingId

string

required

Numeric ID of the signing package (as a string, e.g. "3001").

curl https://api.safeclose.com/v1/signing/signer/signings/3001 \
  -H "Authorization: Bearer <clerk_jwt>"

Response

object

required

The signing package record for this package.

Error responses

Status	Condition
`400`	`signingId` is not a valid numeric ID.
`404`	You are not assigned as a signer to this package, or the package does not exist.

List documents in a signing package

Returns all documents in the package, ordered by position ascending then by id ascending. Capped at 500 documents.

GET /v1/signing/signer/signings/:signingId/documents

string

required

Numeric ID of the signing package.

curl https://api.safeclose.com/v1/signing/signer/signings/3001/documents \
  -H "Authorization: Bearer <clerk_jwt>"

Response

array

required

Array of document records for this package.

Error responses

Status	Condition
`400`	`signingId` is not a valid numeric ID.
`404`	You are not assigned to this package.

Get one document

Returns a single document row from a package you are assigned to.

GET /v1/signing/signer/signings/:signingId/documents/:documentId

string

required

Numeric ID of the signing package.

string

required

Numeric ID of the document.

curl https://api.safeclose.com/v1/signing/signer/signings/3001/documents/7 \
  -H "Authorization: Bearer <clerk_jwt>"

Response

The document record for the requested document.

Error responses

Status	Condition
`400`	Invalid signing or document ID.
`404`	You are not assigned to this package, or the document does not exist within it.

Record an e-signature

Records that you have electronically signed a specific document in a package. This is the primary signing action in the signer flow.

POST /v1/signing/signer/signings/:signingId/documents/:documentId/sign

string

required

Numeric ID of the signing package.

string

required

Numeric ID of the document to sign.

This endpoint is idempotent. The e_sign_recorded_at timestamp on your signer row is written only on the first successful call. Subsequent calls for the same document return ok: true with firstESign: false and the same observedAt time from the first signing event—you will not receive an error.

Request body

The request body is optional. Omit it entirely or send an empty object {}.

object

Optional metadata about the client environment at the time of signing.

Show properties

string

The browser or app user agent string. Maximum 2048 characters. Used for audit trail purposes.

The server also reads the x-forwarded-for header to capture the client IP for the audit record. Your API gateway or load balancer should set this header.

curl -X POST https://api.safeclose.com/v1/signing/signer/signings/3001/documents/7/sign \
  -H "Authorization: Bearer <clerk_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"clientMeta": {"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"}}'

curl -X POST https://api.safeclose.com/v1/signing/signer/signings/3001/documents/7/sign \
  -H "Authorization: Bearer <clerk_jwt>"

Response

boolean

required

Always true on a successful call.

boolean

required

true if this call recorded the e-signature for the first time. false if the document had already been signed by you previously (idempotent repeat call).

string

required

ISO 8601 timestamp of when this signing event was observed by the server.

object or null

The updated document record after the signing action, or null if the document could not be re-fetched.

object or null

Your updated signer record for this package, reflecting the new status and timestamps, or null if the signer record could not be re-fetched.

boolean

required

true if a vault integration event was triggered for downstream processing. false if the signing package’s organization could not be resolved — the e-signature is still recorded regardless.

{
  "ok": true,
  "firstESign": true,
  "observedAt": "2025-06-15T14:30:00.000Z",
  "document": {
    "id": "7",
    "signingId": "3001",
    "position": 1,
    "status": "signed",
    "updatedAt": "2025-06-15T14:30:00.000Z"
  },
  "signer": {
    "id": "801",
    "signingId": "3001",
    "status": "completed",
    "number": 1,
    "fullName": "Jordan Lee",
    "email": "jordan@dealership.com",
    "updatedAt": "2025-06-15T14:30:00.000Z"
  },
  "vaultJobEnqueued": true
}

{
  "ok": true,
  "firstESign": false,
  "observedAt": "2025-06-15T14:30:00.000Z",
  "document": {
    "id": "7",
    "signingId": "3001",
    "position": 1,
    "status": "signed",
    "updatedAt": "2025-06-15T14:30:00.000Z"
  },
  "signer": {
    "id": "801",
    "signingId": "3001",
    "status": "completed",
    "number": 1,
    "fullName": "Jordan Lee",
    "email": "jordan@dealership.com",
    "updatedAt": "2025-06-15T14:30:00.000Z"
  },
  "vaultJobEnqueued": true
}

Error responses

Status	Condition
`400`	Invalid signing or document ID, or malformed JSON body.
`404`	You are not assigned to this package, or the document does not exist within it.

List co-signers on a package

Returns all signer records on the same package. Useful for displaying the signing status of other parties in the transaction. Ordered by signer number ascending, capped at 200 entries.

GET /v1/signing/signer/signings/:signingId/signers

string

required

Numeric ID of the signing package.

curl https://api.safeclose.com/v1/signing/signer/signings/3001/signers \
  -H "Authorization: Bearer <clerk_jwt>"

Response

array

required

All signer records for this package, including your own record and all co-signers.

Error responses

Status	Condition
`400`	`signingId` is not a valid numeric ID.
`404`	You are not assigned to this package.

Get one co-signer

Returns a single signer record from the package.

GET /v1/signing/signer/signings/:signingId/signers/:signerId

string

required

Numeric ID of the signing package.

string

required

Numeric ID of the signer row to fetch.

curl https://api.safeclose.com/v1/signing/signer/signings/3001/signers/802 \
  -H "Authorization: Bearer <clerk_jwt>"

Response

The signer record for the requested signer.

Error responses

Status	Condition
`400`	Invalid signing or signer ID.
`404`	You are not assigned to this package, or the signer does not belong to this package.

Overview

Documents

Signing

Workspace

Signer queue: list packages and record signatures

List your signing packages

Response

Error responses

Get one signing package

Response

Error responses

List documents in a signing package

Response

Error responses

Get one document

Response

Error responses

Record an e-signature

Request body

Response

Error responses

List co-signers on a package

Response

Error responses

Get one co-signer

Response

Error responses

​List your signing packages

​Response

​Error responses

​Get one signing package

​Response

​Error responses

​List documents in a signing package

​Response

​Error responses

​Get one document

​Response

​Error responses

​Record an e-signature

​Request body

​Response

​Error responses

​List co-signers on a package

​Response

​Error responses

​Get one co-signer

​Response

​Error responses

List your signing packages

Response

Error responses

Get one signing package

Response

Error responses

List documents in a signing package

Response

Error responses

Get one document

Response

Error responses

Record an e-signature

Request body

Response

Error responses

List co-signers on a package

Response

Error responses

Get one co-signer

Response

Error responses