Skip to main content

Signing room links

A signing room link is the personal URL a participant uses to open the signing room. From API version 3.7.0, links expire and can be replaced, so read the current link when you need it instead of storing it.


Every signer, approver, and observer on an agreement gets their own signing room link. The link's url is a bearer credential: anyone who has it can open the signing room as that person. Treat it like a password and only share it with the person it belongs to.


Links are generated when the agreement moves to pending. They are kept as the agreement moves through other lifecycle states, so pausing an agreement by moving it to open and sending it again does not change the links.


Where to find it​

Participants, observers, and the issuer carry a signing_room_link object:

signing_room_link on a participant
{
    "signing_room_link": {
        "version": "1.0",
        "result_type": "single",
        "resource_type": "signing_room_link",
        "data": {
            "id": "cyujgihk0jluorojcjgexample",
            "resource_type": "signing_room_link",
            "agreement_id": "cebixe9xitfowpoaduaexample",
            "url": "<signing room URL>",
            "status": "active",
            "expires_at": "2026-11-01T00:00:00.000Z",
            "created_at": "2026-10-25T00:00:00.000Z",
            "updated_at": "2026-10-25T00:00:00.000Z"
        }
    }
}

signing_room_link is null before the agreement has moved to pending, and when the person has no current link.

signing_room_url is the same URL as signing_room_link.data.url. It is kept for backwards compatibility; use signing_room_link when you also need the status or expiry.


Expiry​

A new link expires at the end of the agreement's lifetime if the agreement has an expiration date. Otherwise it expires after 7 days.

An expired link doesn't lock the person out. When they open it, they can request a new link from the signing room. The new link replaces the original, which then stops working.

Links created while your API client was older than 3.7.0 don't expire.


  • active: The link opens the signing room until expires_at.
  • expired: The link has passed expires_at. The person can request a new one from the signing room, or you can rotate it.
  • revoked: The link has been withdrawn and can't be rotated.

  • The person requests a new link after theirs expired. The original stops working.
  • You rotate the link. See below.
  • The participant is forwarded. The old link is revoked and the new recipient gets a new link.
  • The participant is removed. Their link is revoked.

Because a link can be replaced at any of these points, the URL you got earlier may no longer work. Fetch the participant or observer when you need the link, and use the URL from that response. Don't store URLs to reuse later.


Rotate a link when it has expired, or when you think it reached someone it shouldn't have:

POST /agreements/{agreement_id}/signing_room_links/{signing_room_link_id}/rotate

The request has no body, and the response is the new link.

  • The old link stops working straight away, and every signing room session opened with it ends.
  • No email is sent. Deliver the new URL to the person yourself.
  • Older links start to expire. Rotating a link that was created while your API client was older than 3.7.0 replaces it with a link that expires like any other.
  • Requires version 3.7.0. API clients older than 3.7.0 can't call this endpoint.

Webhook events​

Link events come in three categories. The category decides which resource is sent as data:

  • agreement.signing_room_link.* sends the agreement.
  • participant.signing_room_link.* sends the participant.
  • observer.signing_room_link.* sends the observer.

Each category has a generated, a rotated, and a revoked event. See Webhook Events for the full list.


Requirements​

Link expiry and rotation require API client version 3.7.0. Older clients keep links that don't expire. Upgrade your client from the API client settings on zigned.se by clicking "Upgrade".