Custom signing domains

By default, the signing links in Verdocs invitations open on app.verdocs.com. A custom signing domain lets them open on a subdomain you own instead, so the address your recipients click matches the rest of your brand. Throughout this guide we'll set up sign.acme.com for a brand named Acme.

Signing domains belong to Brands, the same way custom email domains do. You can add one in the Verdocs Web app under Settings → Brands → {brand} → Hosting, or through the REST API and SDKs as shown below.

Prerequisites

• Admin or Owner access in your organization, or an API key for one.
• At least one Brand. Navigate to Settings → Brands, or call Create Brand.
• The ability to add a CNAME record for the subdomain.
• A subdomain such as sign.acme.com. Apex domains like acme.com aren't supported, and subdomains of verdocs.com and verdocs.io are reserved.

Step 1 - Add the domain

Call Add app domain with the subdomain you want to use:

import {addBrandAppDomain} from '@verdocs/js-sdk';

const brand = await addBrandAppDomain(endpoint, organizationId, brandId, {subdomain: 'sign.acme.com'});
console.log(brand.app_domain, brand.app_domain_status); // "sign.acme.com" "pending"

The equivalent REST call is POST /v2/organizations/{organizationId}/brands/{brandId}/app-domain with a body of {"subdomain": "sign.acme.com"}. The response is your brand record, with app_domain set and app_domain_status set to pending.

Each brand can have one signing domain, so remove the current one before adding a different one. Each subdomain can also belong to only one brand across all of Verdocs.

Step 2 - Point the subdomain at Verdocs

Add one record in your DNS provider:

Some DNS providers add your domain to the name automatically. If yours does, enter only sign as the host.

That's the only record you need. Once it resolves, Verdocs requests a TLS certificate for sign.acme.com and keeps it renewed, so there is nothing to upload.

Step 3 - Verify

Verdocs checks new domains within about 15 minutes, and then every hour. You don't have to wait for the schedule, though: call Verify app domain or click Verify DNS record in the Web app to check right away.

import {verifyBrandAppDomain} from '@verdocs/js-sdk';

const brand = await verifyBrandAppDomain(endpoint, organizationId, brandId);
console.log(brand.app_domain_status, brand.app_domain_status_reason);

The certificate usually issues within minutes of the record resolving, though DNS changes can take up to 48 hours to reach every resolver. When the check passes, app_domain_status becomes active and app_domain_verified_at is set.

What your recipients see

Once the domain is active, the signing links Verdocs creates for envelopes on that brand use it. Invitation and reminder emails link to https://sign.acme.com/sign/..., and so do in-person signing links. Verdocs picks the brand for each envelope the same way it does for notifications, which is described in How notifications choose a brand.

When someone pastes a signing link into a chat app, the link preview shows the brand's page title (or its name) and its logo instead of Verdocs'.

Your subdomain serves signing pages only. A request for anything else, such as the dashboard or the login page, redirects to app.verdocs.com, and plain http requests redirect to https.

Statuses and what to check

When a domain isn't active, app_domain_status_reason explains why, and the Web app shows the same message under the domain. In most cases the CNAME record is the problem, so check it first. From a terminal, dig CNAME sign.acme.com +short should print custom.verdocs.com. If it prints nothing or a different value, fix the record and verify again.

Verdocs stops checking a failed domain on its own, so verify it again once the record is fixed. A suspended domain should be fixed quickly: Verdocs removes a domain that stays suspended for 7 days, and while it's suspended, links in invitations you already sent won't open, because they point at your subdomain. New emails use app.verdocs.com until the domain is active again.

Removing a domain

Call Remove app domain, or click Remove domain in the Web app. This takes effect right away, and signing links for the brand go back to app.verdocs.com.

Invitations you already sent still link to your subdomain, so those links stop working once the domain is removed. It's best to remove a domain when no envelopes are waiting on signers. If some are, a reminder gives each signer a fresh link on app.verdocs.com.

Once the domain is removed, you can delete the CNAME record whenever it's convenient.