Pending steps

Answer pending when the signer must do something at your provider before you can return a result, such as identify or approve. Only credential and authorize can answer pending. sign can’t.

Pause only where your provider needs the signer. Which calls that is depends on your provider’s model: see Choose your provider’s model.

{
    "status": "pending",
    "action_url": "https://signer.example.com/consent?ticket=...",
    "poll_after": 3,
    "expires_at": "2026-08-24T16:45:00Z"
}

A pending answer offers at least one way to finish the step: action_url, poll_after, or both. One with neither fails the session with worker response invalid: pending needs action_url or poll_after.

You send	The ceremony shows	The step ends when
action_url	Confirm your identity to continue on credential, Authorize your signature on authorize, then sends the browser to action_url	The browser reaches callback_url
poll_after	Waiting for your confirmation. The signer stays in the ceremony.	A poll gets completed or failed
Both	The redirect screen, as for action_url	Whichever happens first. The other channel then has no effect.

On credential, the ceremony waits a moment before the redirect, so the signer can read why they’re leaving. On authorize, it redirects right away. Both screens also show a button to the action_url, in case the redirect doesn’t happen.

Redirect: action_url

An absolute https URL. SignatureAPI sends the signer’s browser there. It can be your provider’s page or a page your worker hosts.

The step ends when the browser arrives at callback_url. Add one of these as query parameters. callback_url already has a query string, so append with &:

• code. An opaque, single-use value you mint. SignatureAPI calls the same operation again with "callback": { "code": "..." }, and you turn the code into a result.
• error, and optionally error_description. The session fails with error_description, or with error when you leave the description out. The ceremony shows that reason, and the signer can retry.

https://api.signatureapi.com/v1/signing-sessions/callback?state=NQ...&code=c_8f2e...
https://api.signatureapi.com/v1/signing-sessions/callback?state=NQ...&error=access_denied&error_description=You%20cancelled%20the%20signature.

A callback with neither fails the session with The authorization callback carried neither a code nor an error.

A request that carries callback.code must get completed or failed. Never answer it with pending.

Providers usually require an exact, pre-registered OAuth redirect URI. Register your worker’s own URI with the provider, finish the exchange in your worker, then redirect the browser to callback_url.

callback_url works once. A replayed callback takes the signer back to the ceremony and has no other effect.

Poll: poll_after

The number of seconds after which SignatureAPI calls the same operation again with the same body. SignatureAPI keeps the value between 1 and 60. Answer pending again, or resolve. Use this for app confirmations, QR codes and wallets, where the browser never comes back by itself.

A poll repeats the call, not the act. If your authorize sends a push notification, don’t send another one on every poll. Answer from your provider’s current state.

Deadline

The signer has until the connection’s Authorization timeout, 5 minutes by default, to finish each pending step. The account sets it when it connects your worker, up to one hour. An expires_at on a pending answer can shorten that deadline, never extend it.

After the deadline, the session fails with authorization window expired, even if the browser comes back later. The signer can retry from the ceremony.