---
title: "Update Custom Signature Request Status (BYOSP)"
method: PATCH
path: "/signature-requests/{id}"
tags: ["Workflows"]
---

# Update Custom Signature Request Status (BYOSP)

`PATCH /signature-requests/{id}`

## Request

- Base URL: `https://ironcladapp.com/public/api/v1`
- URL: `https://ironcladapp.com/public/api/v1/signature-requests/{id}`
- Auth: API key in header `Authorization` and OAuth 2
  - Authorization code: `https://ironcladapp.com/oauth/authorize`
  - Client credentials
  - Token URL: `https://ironcladapp.com/oauth/token` scopes: `public.signatureRequests.updateRequest`

Inbound webhook endpoint for Bring Your Own Signature Provider (BYOSP) middleware. The customer-built middleware posts signature lifecycle events here so Ironclad can update the corresponding signature request and fire workflow events.

**OAuth Scope required:** `public.signatureRequests.updateRequest`

Returns `204 No Content` on success. Idempotent — once an envelope has reached `completed` or `voided`, subsequent pushes are no-ops.

## Path parameters

- `id` string, uuid, required

## Request body

- CustomStatusUpdateBody: Inbound payload posted by BYOSP middleware to update a custom signature request. Idempotent at the envelope level — once `completed` or `voided`, subsequent pushes are no-ops.
  - `status` 'pending' | 'completed' | 'voided', required: Envelope-level state. Ironclad trusts this field over signer-level inference (e.g., all signers signed but envelope still `pending` keeps the envelope open).
  - `signatures` object[], required
    - `roleName` string, required: Role name for this signer. Must be one of the roleNames sent in the initiation request; unknown values cause a 400. roleName is the only identifier round-tripped through the BYOSP middleware — Ironclad does not assign a separate signerId on the wire.
    - `signer` object, required
      - `name` string, required: The signer's full name.
      - `email` string, email, required: The signer's email address.
    - `status` 'awaiting_signature' | 'signed' | 'declined', required: This signer's current state: `awaiting_signature` before they act, `signed` once they complete signing, or `declined` if they refuse. Distinct from the envelope-level `status`.
    - `declineReason` string: Free-form reason captured at decline time. Surfaced in the workflow activity log. Only persisted when `status` is `declined`; ignored otherwise.
    - `firstViewedAt` string, date-time: First-viewed-at timestamp; once set on a signer it is not overwritten by subsequent updates.

## Response `204`

204

## Other responses

- `400`: Malformed request body, or an inbound signer role not present in the original signature request.
- `401`: 401
- `403`: 403
- `404`: Unknown signatureRequestId.

## Changes

- **2026-11-03** `435da5a4396e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/changes/signature-requests/:id/patch.md)

---

[API](https://skmtc.dev/ironcladapp/apis/ironclad-public-api.md) - [All operations](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ironcladapp/apis/ironclad-public-api/revisions/435da5a4396e?raw)