Skip to content

Overview

Introduction

Let users sign inside your web or mobile app. Your server creates the ceremony, your app shows it in an iframe or WebView and reacts to how it ended.

A signing ceremony embedded in a web app on a laptop and in a mobile app on a phone, each showing the document and a Start button

Let your users sign documents directly in your web or mobile app using SignatureAPI’s Embedded Signing.

You need both:

  • A server to create an envelope and get a ceremony URL.
  • A client to display the ceremony to the recipient.

How it works

  1. Your server creates the envelope. The recipient’s ceremony uses custom or email_code authentication, so SignatureAPI returns the ceremony URL instead of emailing it.
  2. Your server waits until the envelope is in_progress, then passes the URL to your app.
  3. Your app appends embedded=true and an event_delivery value to the URL, and shows it in an iframe or a WebView.
  4. When the ceremony ends, it sends your app an event: ceremony.completed, ceremony.canceled, ceremony.declined or ceremony.failed.
  5. Your server confirms the outcome with the API or a webhook before it acts on it.

Embedding in a Web Application shows every request of this flow, step by step.

Server side

Your server holds the API key and creates the envelope with Create Envelope. Three settings on the recipient’s ceremony matter for embedding:

  • authentication: the first method must be custom (your app has already signed the user in) or email_code (SignatureAPI emails the user a code). With email_link, the default, SignatureAPI emails the link and returns no URL.
  • embeddable_in: the origins of the pages that show the ceremony in an iframe, such as https://app.acme.example. SignatureAPI keeps it only when the first authentication method is custom or email_code. A native WebView that loads the ceremony as its own page doesn’t need it.
  • redirect_delay: how long the result page shows before the event, 3 seconds by default. Set 0 to show your own result screen right away.

The 201 Created response already contains the URL in recipients[].ceremony.url. The ceremony opens once the envelope is in_progress; before that, it asks the recipient to try again later. Wait for the envelope.started webhook, or read the envelope until its status is in_progress. To get a URL for an existing recipient, see Ceremony URL.

Not sure which authentication method fits? Answer two questions:

Which authentication method should my recipient use?

See every path

Who delivers the ceremony link to the recipient?

  • SignatureAPI, by email

    Should the recipient also enter a code from their email before they see the documents?

    • No, the link is enough

      Email link (the default): SignatureAPI emails the recipient a direct link; opening it authenticates them. No setup: it is what you get when you leave out ceremony. The ceremony's url is null because SignatureAPI delivers it. See: Email link authentication

    • Yes, add a second step

      Email link, then email code: SignatureAPI emails the invitation link and, inside the ceremony, a 9-digit verification code, so your application sends neither email. The ceremony's url stays null. This is one of the two setups the HIPAA page describes for documents with protected health information. See: Multiple authentication methods, HIPAA

  • My application: my own email, SMS, an in-app link or an embedded ceremony

    Has your application already authenticated the recipient?

    • Yes, they are signed in to my application

      Do you also want a second factor that SignatureAPI controls?

      • No, my authentication is enough

        Custom: Your application authenticates the recipient and SignatureAPI returns a ceremony URL to share or embed. Set provider and data: both appear in the audit log, and you must keep the records that prove how the recipient was authenticated. See: Custom authentication

      • Yes, add an email code

        Custom, then email code: Your application authenticates the recipient first, then SignatureAPI independently checks their email with a 9-digit code inside the ceremony. The URL is returned and your application delivers it. See: Multiple authentication methods

    • No, SignatureAPI should check their email

      Email code: The API returns the ceremony URL and you deliver it through your own channel. When the recipient opens it, SignatureAPI emails them a 9-digit code to enter before signing. See: Email code authentication, Ceremony URL

Client side

Don’t use our API directly from the client because API keys can be exposed. If someone gets your API key, they can access all your data in SignatureAPI.

After getting the ceremony URL, you can embed the signing interface directly into your application. You don’t need any extra dependencies. Use standard components like iframes (for web apps), WebView (for Android), or WKWebView (for iOS).

Each platform catches the ceremony’s result in its own way. A web page receives a JavaScript message; a native WebView intercepts a navigation to a signatureapi-message:// URL:

Web
// URL: ...&embedded=true&event_delivery=message
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://sign.signatureapi.com') return;
  if (event.source !== iframe.contentWindow) return;
  handleCeremonyEvent(event.data.type, event.data.error_type);
});
iOS
// URL: ...&embedded=true&event_delivery=redirect
func webView(_ webView: WKWebView, decidePolicyFor action: WKNavigationAction,
             decisionHandler: @escaping @MainActor (WKNavigationActionPolicy) -> Void) {
    guard let url = action.request.url, url.scheme == "signatureapi-message" else {
        return decisionHandler(.allow)
    }
    decisionHandler(.cancel)
    handleCeremonyEvent(url.host() ?? "")
}
Android
// URL: ...&embedded=true&event_delivery=redirect
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
    val uri = request.url
    if (uri.scheme != "signatureapi-message") return false
    handleCeremonyEvent(uri.host.orEmpty())
    return true
}
React Native
// URL: ...&embedded=true&event_delivery=redirect
<WebView
  source={{ uri: ceremonyUrl }}
  originWhitelist={['*']}
  onShouldStartLoadWithRequest={(request) => {
    const match = /^signatureapi-message:\/\/([^/?#]+)/i.exec(request.url);
    if (!match) return true;
    handleCeremonyEvent(match[1]); // not new URL(): its host is empty here
    return false;
  }}
/>
Flutter
// URL: ...&embedded=true&event_delivery=redirect
NavigationDelegate(
  onNavigationRequest: (request) {
    final uri = Uri.parse(request.url);
    if (uri.scheme != 'signatureapi-message') return NavigationDecision.navigate;
    handleCeremonyEvent(uri.host, uri.queryParameters['error_type']);
    return NavigationDecision.prevent;
  },
)

The event type, such as ceremony.completed, is the message’s type or the URL’s host. See Ceremony Events for every event and its data, then follow the guide for your platform.

Web apps

Web Apps

Embed the ceremony in a web application using HTML and JavaScript.

React

A reusable signing component with event handling and a redirect when the signer finishes.

Next.js

A server action creates the ceremony; a client component shows it.

Vue and Nuxt

A Vue component and a Nuxt server route.

Angular

A standalone component with signal inputs and outputs.

Svelte and SvelteKit

A Svelte 5 component and a SvelteKit form action.

Mobile apps

iOS

Embed the ceremony in an iOS app using Swift and WKWebView.

Android

Embed the ceremony in an Android app using Kotlin and WebView.

React Native

Embed the ceremony in a React Native app.

Flutter

Embed the ceremony in a Flutter app using webview_flutter.

Browser requirements

The ceremony runs in any modern browser or WebView. Default settings work, except that Android needs JavaScript turned on.

  • JavaScript must be on.
  • The ceremony uses no cookies, localStorage, sessionStorage, or IndexedDB. Third-party cookie blocking in WebKit is fine. On Android, DOM storage and third-party cookies can stay off.
  • Allow the browser to contact these hosts:
HostPurpose
sign.signatureapi.comThe ceremony
api.signatureapi.comThe ceremony’s API calls
vault.signatureapi.comDocument page images
fonts.googleapis.comFonts
fonts.gstatic.comFonts

Automated testing

To stop email link scanners from completing ceremonies, the ceremony arms completion only after input that a person produces. That input is a touch, a scroll-wheel turn, a key press, or a pointer moving across several positions. Until then, Finish opens a “Confirm to continue” dialog. This is expected.

Automated tests must produce real input:

  • XCUITest taps on iOS.
  • UiAutomator gestures on Android.
  • Mouse movement in Playwright.

Clicks dispatched from JavaScript, such as Espresso-Web webClick(), don’t count. Add a real gesture first, for example a swipe over the document. Don’t confirm the dialog in tests: if it appears, the test isn’t acting like a signer.

Assert on the ceremony event itself. In a desktop browser, the Navigation API fires a navigate event for the signatureapi-message:// URL at the same moment a native WebView sees it. Listen for that event. Don’t assert on the ceremony’s console output.