> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safeclose.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Signer queue: list packages and record signatures

> List your assigned signing packages, retrieve documents and co-signer info, and record e-signatures using signer-scoped endpoints in Safeclose.

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](/api/signing/session) before calling these routes.

<Warning>
  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.
</Warning>

***

## 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.safeclose.com/v1/signing/signer/signings \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

### Response

<ResponseField name="signers" type="array" required>
  Your signer stub rows. Each object contains the fields below.

  <Expandable title="signer fields">
    <ResponseField name="id" type="string" required>
      The signer row ID (bigint serialized as string).
    </ResponseField>

    <ResponseField name="signingId" type="string" required>
      The parent signing package ID.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Current status of this signer assignment, e.g. `"pending"`, `"completed"`, `"cancelled"`.
    </ResponseField>

    <ResponseField name="number" type="number or null">
      Signer position number within the package (1-indexed ordering).
    </ResponseField>

    <ResponseField name="fullName" type="string or null">
      Display name for this signer.
    </ResponseField>

    <ResponseField name="email" type="string or null">
      Email address for this signer assignment.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp of the last update to this signer row.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="signings" type="array" required>
  The parent signing package records for all packages in the `signers` list, deduplicated. Ordered by most recently updated first.
</ResponseField>

### 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
```

<ParamField path="signingId" type="string" required>
  Numeric ID of the signing package (as a string, e.g. `"3001"`).
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.safeclose.com/v1/signing/signer/signings/3001 \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

### Response

<ResponseField name="signing" type="object" required>
  The signing package record for this package.
</ResponseField>

### 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
```

<ParamField path="signingId" type="string" required>
  Numeric ID of the signing package.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.safeclose.com/v1/signing/signer/signings/3001/documents \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

### Response

<ResponseField name="documents" type="array" required>
  Array of document records for this package.
</ResponseField>

### 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
```

<ParamField path="signingId" type="string" required>
  Numeric ID of the signing package.
</ParamField>

<ParamField path="documentId" type="string" required>
  Numeric ID of the document.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.safeclose.com/v1/signing/signer/signings/3001/documents/7 \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

### 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
```

<ParamField path="signingId" type="string" required>
  Numeric ID of the signing package.
</ParamField>

<ParamField path="documentId" type="string" required>
  Numeric ID of the document to sign.
</ParamField>

<Note>
  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.
</Note>

### Request body

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

<ParamField body="clientMeta" type="object">
  Optional metadata about the client environment at the time of signing.

  <Expandable title="properties">
    <ParamField body="clientMeta.userAgent" type="string">
      The browser or app user agent string. Maximum 2048 characters. Used for audit trail purposes.
    </ParamField>
  </Expandable>
</ParamField>

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.

<CodeGroup>
  ```bash cURL (with userAgent) theme={null}
  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)"}}'
  ```

  ```bash cURL (no body) theme={null}
  curl -X POST https://api.safeclose.com/v1/signing/signer/signings/3001/documents/7/sign \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

### Response

<ResponseField name="ok" type="boolean" required>
  Always `true` on a successful call.
</ResponseField>

<ResponseField name="firstESign" type="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).
</ResponseField>

<ResponseField name="observedAt" type="string" required>
  ISO 8601 timestamp of when this signing event was observed by the server.
</ResponseField>

<ResponseField name="document" type="object or null">
  The updated document record after the signing action, or `null` if the document could not be re-fetched.
</ResponseField>

<ResponseField name="signer" type="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.
</ResponseField>

<ResponseField name="vaultJobEnqueued" type="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.
</ResponseField>

<CodeGroup>
  ```json First signing theme={null}
  {
    "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
  }
  ```

  ```json Idempotent repeat call theme={null}
  {
    "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
  }
  ```
</CodeGroup>

### 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
```

<ParamField path="signingId" type="string" required>
  Numeric ID of the signing package.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.safeclose.com/v1/signing/signer/signings/3001/signers \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

### Response

<ResponseField name="signers" type="array" required>
  All signer records for this package, including your own record and all co-signers.
</ResponseField>

### 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
```

<ParamField path="signingId" type="string" required>
  Numeric ID of the signing package.
</ParamField>

<ParamField path="signerId" type="string" required>
  Numeric ID of the signer row to fetch.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.safeclose.com/v1/signing/signer/signings/3001/signers/802 \
    -H "Authorization: Bearer <clerk_jwt>"
  ```
</CodeGroup>

### 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. |