# Custom signing domains (/docs/guides/tutorials/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](https://app.verdocs.com) under **Settings → Brands → \{brand} → Hosting**, or through the REST API and SDKs as shown below.

## Prerequisites [#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](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/brands/createBrand).
* 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 [#step-1---add-the-domain]

Call [Add app domain](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/brands/addBrandAppDomain) with the subdomain you want to use:

```typescript
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 [#step-2---point-the-subdomain-at-verdocs]

Add one record in your DNS provider:

|           |                      |
| --------- | -------------------- |
| **Type**  | CNAME                |
| **Host**  | `sign.acme.com`      |
| **Value** | `custom.verdocs.com` |

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 [#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](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/brands/verifyBrandAppDomain) or click **Verify DNS record** in the Web app to check right away.

```typescript
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 [#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](https://developers.verdocs.com/docs/guides/tutorials/add-a-custom-email-domain-to-your-brand#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 [#statuses-and-what-to-check]

| Status      | What it means                                                        | Where signing links open |
| ----------- | -------------------------------------------------------------------- | ------------------------ |
| `pending`   | Waiting for the CNAME record to resolve and the certificate to issue | `app.verdocs.com`        |
| `active`    | The domain is serving signing pages                                  | Your domain              |
| `suspended` | The domain was active, but a later check failed                      | `app.verdocs.com`        |
| `failed`    | The domain was still pending after 14 days                           | `app.verdocs.com`        |

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 [#removing-a-domain]

Call [Remove app domain](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/brands/removeBrandAppDomain), 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.