# Home (/docs)
## What is Next? [#what-is-next]
# Getting Started (/docs/guides/getting-started)
Welcome to Verdocs! This guide will help you quickly get up and running with the Verdocs platform, whether you want to integrate via our APIs, use our public SDKs, or embed rich signing experiences inside your web application. We'll cover:
* [Verdocs JS SDK (@verdocs/js-sdk)](#verdocs-js-sdk-getting-started)
* [Verdocs Web Components SDK (@verdocs/web-sdk)](#verdocs-web-components-sdk-getting-started)
***
## Verdocs JS SDK: Getting Started [#verdocs-js-sdk-getting-started]
The [Verdocs JS SDK](/docs/reference/SDK/languages/getting-started) provides type-safe, convenient access to the Verdocs API for both browser and NodeJS applications. Use this SDK to manage templates, documents, organizations, authentication, and more.
### 1. Installation [#1-installation]
Install using your package manager of choice:
```sh
npm install @verdocs/js-sdk
# or
yarn add @verdocs/js-sdk
# or
pnpm add @verdocs/js-sdk
```
### 2. Authentication [#2-authentication]
#### Standard User Authentication [#standard-user-authentication]
To authenticate as a standard user, present the user with a login form to enter their username and password, then use code such as shown below. NOTE: You may also embed the VerdocsAuth component in your Web application, and this is strongly recomended.
```ts
import {VerdocsEndpoint, authenticate} from '@verdocs/js-sdk';
const endpoint = VerdocsEndpoint.getDefault();
const authResult = await authenticate(endpoint, {
grant_type: 'password',
username: USER,
password: PASS,
});
endpoint.setToken(authResult.access_token);
```
#### Server Application Authentication [#server-application-authentication]
Server applications should never "know" usernames and passwords. Instead, create an API key in your account, and securely store the Client ID and Secret in an appropriate location such as Vault, Secrets Manager, SSM, etc. Then use code such as the following to authenticate:
```ts
import {VerdocsEndpoint, authenticate} from '@verdocs/js-sdk';
const endpoint = VerdocsEndpoint.getDefault();
const authResult = await authenticate(endpoint, {
grant_type: 'client_credentials',
client_id: ID,
client_secret: SECRET,
});
endpoint.setToken(authResult.access_token);
```
### 3. Using the SDK [#3-using-the-sdk]
You’re now ready to work with the main Verdocs primitives!
**Templates:**
```typescript
import {VerdocsEndpoint, authenticate, getTemplates} from '@verdocs/js-sdk';
const endpoint = VerdocsEndpoint.getDefault();
const authResult = await authenticate(endpoint, {
grant_type: 'client_credentials',
client_id: ID,
client_secret: SECRET,
});
endpoint.setToken(authResult.access_token);
const templates = await endpoint.getTemplates(endpoint);
templates.forEach((template) => {
console.log('Template: ' + template.id + ' - ' + template.name);
});
```
See the [JS SDK repository](https://github.com/Verdocs/js-sdk) for reference.
***
## Verdocs Web Components SDK: Getting Started [#verdocs-web-components-sdk-getting-started]
The [Verdocs Web Components SDK](/docs/reference/SDK/web) is a library of reusable, embeddable UI components (built using StencilJS) for signature flows, document previews, and more.
### 1. Installation [#1-installation-1]
Install the SDK and the framework-specific package you need (React, Angular, or plain JS):
**For React:**
```sh
npm install @verdocs/web-sdk-react
```
**For Angular:**
```sh
npm install @verdocs/web-sdk-angular
```
**For VueJS/Plain JS:**
```sh
npm install @verdocs/web-sdk-vue
```
### 2. Add Fonts [#2-add-fonts]
To match Verdocs visual style, add the Barlow font to your site's `
`:
```html
```
### 3. Usage Examples [#3-usage-examples]
#### **React Example** [#react-example]
```tsx
import React from 'react';
import {VerdocsButton} from '@verdocs/web-sdk-react';
const MyComponent = () => {
return setInviting(true)} />
}
```
#### **Angular Example** [#angular-example]
Include the component in your module:
```typescript
import { ComponentLibraryModule } from '@verdocs/web-sdk-angular';
@NgModule({
imports: [ComponentLibraryModule],
})
export class AppModule {}
```
Use in a template:
```ts
import { AfterViewInit, Component, ElementRef, ViewChild } from '@angular/core';
import { VerdocsButton } from '@verdocs/web-sdk-angular';
@Component({
selector: 'app-verdocs-button-demo',
template: `
Verdocs Button Demo
{{ statusMessage }}
`,
})
export class VerdocsButtonDemoComponent implements AfterViewInit {
@ViewChild('primaryBtn', { read: ElementRef })
private primaryBtnRef?: ElementRef;
buttonLabel = 'Continue';
isDisabled = false;
statusMessage = 'Waiting for click...';
// Optional icon sample (string-based SVG)
startIconSvg = '';
ngAfterViewInit(): void {
// Accessing the underlying web component instance (typed as VerdocsButton)
const buttonEl = this.primaryBtnRef?.nativeElement;
if (buttonEl) {
// Example of setting prop programmatically
buttonEl.label = 'Continue';
}
}
handleClick = (): void => {
this.statusMessage = 'Button clicked!';
};
}
```
#### **Vue.js Example** [#vuejs-example]
```ts
```
For more information, you can visit the [Web SDK repository](https://github.com/Verdocs/web-sdk).
***
## Verdocs REST API [#verdocs-rest-api]
Our [REST API documentation](/docs/reference/Rest-API) will allow you to test any route in your browser.
***
**Questions or issues?** [Contact our support team](https://verdocs.com/contact) for a resolution.
Happy building!
# Guides (/docs/guides)
# FAQ (/docs/learn/FAQ)
# AI and MCP (/docs/learn/mcp)
Verdocs is an eSignature platform you build into your own product: a REST API, SDKs for the browser and the server, and embeddable web components that put signing inside your application instead of redirecting people to somebody else's portal.
If you are writing that integration with an AI assistant, point it here first. This site runs an MCP server that lets your agent search and read the documentation directly, so it works from what Verdocs actually does today rather than from whatever it remembers about eSignature APIs in general.
## The two MCP surfaces [#the-two-mcp-surfaces]
| Surface | Endpoint | What it does | Status |
| ----------------- | ------------------------------------ | -------------------------------------------------------------------------------- | -------------- |
| Documentation MCP | `https://developers.verdocs.com/mcp` | Search and read these docs. No account or key needed. | Available now |
| Platform MCP | To be announced | Act on the Verdocs API: templates, envelopes, recipients, organization settings. | In development |
The documentation MCP is read-only and anonymous. It reads a public site, so there is nothing to authenticate and nothing it can change.
## Connect your client [#connect-your-client]
### Claude Code [#claude-code]
```bash
claude mcp add --transport http verdocs-docs https://developers.verdocs.com/mcp
```
### Claude Desktop, Cursor, Windsurf, and other clients [#claude-desktop-cursor-windsurf-and-other-clients]
Anything that supports remote MCP over HTTP takes the URL directly. In a JSON config file that usually looks like this:
```json
{
"mcpServers": {
"verdocs-docs": {
"type": "http",
"url": "https://developers.verdocs.com/mcp"
}
}
}
```
The exact key names move around between releases, so check your client's current docs if it rejects the block above. Clients that still speak only `stdio` can bridge to it:
```json
{
"mcpServers": {
"verdocs-docs": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://developers.verdocs.com/mcp"]
}
}
}
```
Once it is connected, ask your assistant something like "using the Verdocs docs, show me how to send an envelope from a template" and it will search and read the relevant pages before answering.
## Tools [#tools]
| Tool | Arguments | Returns |
| ----------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `search_docs` | `query` (string, up to 500 characters) | Ranked section matches, each with its breadcrumb trail, page URL, and raw markdown URL. This is the one to reach for first. |
| `get_doc_page` | `path` (string, up to 256 characters) | One page as markdown. Accepts `learn/mcp`, `/docs/learn/mcp`, or `/docs/learn/mcp.mdx`; all three normalize to the same page. |
| `list_docs_paths` | none | Every documentation path with its URL. Useful for seeing the shape of the docs when no search term is obvious. |
Search runs against the same index the site's own search box uses, so an agent and a person asking the same question get the same results.
## Plain HTTP, without MCP [#plain-http-without-mcp]
Everything the MCP server reads is a public URL, so a RAG pipeline or a one-off script does not need MCP at all.
**Any page as markdown.** Append `.mdx` to any docs URL:
```
https://developers.verdocs.com/docs/guides/getting-started.mdx
```
This is worth knowing even if you are reading pages by hand. A rendered docs page is around 300 KB of HTML, most of it navigation and syntax-highlighting markup; the same page as markdown is a few kilobytes of content. Every page also advertises this with a `` tag, so a crawler can find it without being told.
**An index of every page**, with titles and descriptions, plus the API base URL and auth model:
```
https://developers.verdocs.com/llms.txt
```
**The full text of the entire site** in one response, for ingesting the whole knowledge base at once:
```
https://developers.verdocs.com/llms-full.txt
```
**The OpenAPI specification**, if you would rather generate a client than read prose:
```
https://developers.verdocs.com/openapi.json
```
## Checking the connection [#checking-the-connection]
If a client will not connect, test the transport directly. A successful `initialize` returns a JSON-RPC result carrying the server's name, version, and capabilities:
```bash
curl -sS -X POST "https://developers.verdocs.com/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Mcp-Protocol-Version: 2024-11-05" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
```
[MCP Inspector](https://github.com/modelcontextprotocol/inspector) pointed at the same URL gives you a UI for listing and calling the tools.
The endpoint speaks [streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) and is stateless, so there is no session to establish and no order you have to call things in. Request bodies over 2 MiB are rejected.
## Platform MCP [#platform-mcp]
The documentation MCP tells an agent how Verdocs works. The platform MCP, which is in development now, will let it use Verdocs: creating and sending envelopes, checking signing status, managing templates and recipients, and reading organization configuration, all under your own API credentials and scoped to the same permissions those credentials already carry.
It will be a separate endpoint with its own authentication, so connecting to the docs today does not give an agent any access to your account, and it never will.
Watch [What's new](/docs/learn/whats-new) for the announcement, or subscribe to [the changelog feed](/rss.xml).
# Verdocs Learning Center (/docs/learn/verdocs-learning-center)
# Reference (/docs/reference)
# Custom email domains for notifications (/docs/guides/tutorials/add-a-custom-email-domain-to-your-brand)
Your envelope creators and recipients should recognize who sent the email the moment it lands in their inbox. By default, Verdocs sends notifications from `notifications@verdocs.com`. With **custom email domains**, you can send from an address on your own domain, e.g. 'Acme Documents \<[notifications@notify.acme.com](mailto:notifications@notify.acme.com)>' so every notification reflects your brand.
Custom email domains are configured via Brands. When an envelope is sent, Verdocs resolves the brand from the envelope assignment, your organization's default brand, or (in parent/child org hierarchies) a parent organization's default brand. You may configure custom domains either via the Verdocs Web App (**Settings → Brands → \{brand} → Sender Email**) or via our REST API / SDKs.
> Note: The custom **From** address is used only when that brand's domain is fully verified; until then, notifications continue to send from the platform default.
## Prerequisites [#prerequisites]
Before you begin, make sure you have:
* **Admin or Owner** access in your organization, or an API token for same.
* At least one Brand defined. Navigate to **Settings → Brands**, or call [Create Brand](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/brands/createBrand).
* The ability to add custom DNS records for the domain or subdomain you want to send from.
* A sending domain that is **not** a subdomain of `verdocs.com` or `verdocs.io` (these are reserved).
We strongly recommend using a **dedicated subdomain** such as `notify.acme.com` rather than your primary corporate domain (`acme.com`). A dedicated subdomain isolates your notification sending reputation from everyday business email - if deliverability issues arise on the notification channel, they won't affect mail sent from your main domain.
***
## How it works [#how-it-works]
At a high level, you tell us which subdomain and sender address to use, then add DNS records that we provide in response (to prove that you control the domain). We will periodically check for these records to be created, then complete the verification process. Once all checks pass, notifications for communications related to the selected Brand will automatically use your custom address.
### Step 1 - Configure the sender identity [#step-1---configure-the-sender-identity]
You must provide four pieces of information when adding an email domain:
| Input | API field | Required | Example |
| ------------------- | -------------- | -------- | ------------------ |
| Sending domain | `subdomain` | Yes | `notify.acme.com` |
| From local part | `local_part` | Yes | `notifications` |
| Sender display name | `display_name` | No | `Acme Documents` |
| Reply-to address | `reply_to` | No | `support@acme.com` |
This can be done via the [Verdocs web application](https://app.verdocs.com) or the [Verdocs API](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/brands/addBrandEmailDomain).
After you submit, Verdocs registers the domain with our email infrastructure and returns your brand record with `email_domain_status` set to `pending`. The response also includes `email_dkim_tokens` - three unique tokens you will use to create DKIM CNAME records.
The resulting `From address` recipients, once verified, will see:
'\{display\_name or brand/org name} \<\{local\_part}@\{subdomain}>'
For example: 'Acme Documents \<[notifications@notify.acme.com](mailto:notifications@notify.acme.com)>'.
### Step 2 - Add DNS records [#step-2---add-dns-records]
Add the following records in your DNS provider. All three record types are **required** before the domain becomes active.
#### SPF (TXT) [#spf-txt]
Authorizes Verdocs' mail servers to send on behalf of your domain.
| | |
| --------- | --------------------------------------- |
| **Type** | TXT |
| **Host** | `notify.acme.com` (your `email_domain`) |
| **Value** | `v=spf1 include:amazonses.com ~all` |
If your domain already has an SPF TXT record on that host, **do not create a second one**. Instead, add `include:amazonses.com` to your existing SPF record.
#### DKIM (3× CNAME) [#dkim-3-cname]
Adds a cryptographic signature to outgoing mail. Verdocs provides three tokens in `email_dkim_tokens` after you add the domain. Create one CNAME per token:
| | |
| --------- | ------------------------------------ |
| **Type** | CNAME |
| **Host** | `{token}._domainkey.notify.acme.com` |
| **Value** | `{token}.dkim.amazonses.com` |
Repeat for all three tokens.
#### DMARC (TXT) [#dmarc-txt]
Tells receiving mail servers how to handle messages that fail SPF or DKIM checks.
| | |
| --------- | ------------------------ |
| **Type** | TXT |
| **Host** | `_dmarc.notify.acme.com` |
| **Value** | `v=DMARC1; p=reject;` |
Verification requires both `v=DMARC1` and `p=reject` in the record value. You can optionally append an aggregate reporting address, for example:
`v=DMARC1; p=reject; rua=mailto:dmarc-reports@acme.com`
Because the sending subdomain is dedicated to Verdocs notifications, `p=reject` is appropriate: if DMARC fails, something is misconfigured and the message should not be delivered.
### Step 3 - Verify DNS [#step-3---verify-dns]
Once your DNS records are in place, trigger a verification check. Verdocs evaluates three independent checks:
| Check | Field updated | What passes |
| ----- | ---------------------- | ------------------------------------------------------------------------------- |
| SPF | `email_spf_verified` | TXT record on your sending domain contains `v=spf1` and `include:amazonses.com` |
| DKIM | `email_dkim_verified` | DKIM identity reports a successful status |
| DMARC | `email_dmarc_verified` | TXT record at `_dmarc.{email_domain}` contains `v=DMARC1` and `p=reject` |
When **all three** are `true`, `email_domain_status` becomes `verified` and `email_domain_verified_at` is set to the current timestamp.
You can verify on demand at any time. Verdocs also re-checks automatically:
* **Pending domains** - checked approximately every 15 minutes until verified.
* **Verified domains** - re-checked daily. If a previously passing record is removed, status moves to `suspended` and sending reverts to the platform default until DNS is fixed and verification passes again.
DNS changes typically propagate within 15 - 60 minutes, though some providers can take up to 48 hours.
### Step 4 - Send notifications from your domain [#step-4---send-notifications-from-your-domain]
Once verified, envelope notifications tied to that brand use your custom **From** address. The display name comes from `email_display_name` if set; otherwise Verdocs uses the envelope sender name, organization name, or profile name depending on context.
If verification is incomplete (`pending`) or a re-check fails (`suspended`), Verdocs continues sending from `notifications@verdocs.com` - your recipients are not left without mail, but they will see the platform sender until DNS is healthy again.
***
## Status lifecycle [#status-lifecycle]
| Status | Meaning | Sending behavior |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------- |
| `pending` | Domain configured; DNS verification incomplete | Platform default sender |
| `verified` | SPF, DKIM, and DMARC all pass | Custom From address active |
| `suspended` | Was verified, but a re-check found missing or invalid DNS | Reverts to platform default until fixed and re-verified |
**Removing a domain** clears all email fields (`email_domain`, `email_local_part`, `email_display_name`, `email_reply_to`, verification flags, DKIM tokens, and timestamps) and deletes the registered domain identity. This is immediate - there is no grace period.
**Constraints to be aware of:**
* One email domain per brand. Remove the existing domain before adding a different one.
* Each `email_domain` value can only be registered to one brand across the entire Verdocs platform.
* Subdomains of `verdocs.com` and `verdocs.io` cannot be used.
* The sending domain must be a valid multi-label domain (e.g. `notify.acme.com`, not a single label like `acme`).
***
## How notifications choose a brand [#how-notifications-choose-a-brand]
Not every notification is tied to the same brand. Verdocs resolves the brand in this order:
1. The **brand assigned to the envelope** (if set when the envelope was created).
2. Your **organization's default brand** (if configured).
3. In parent/child organization hierarchies, the **parent organization's default brand**.
The custom email domain on the resolved brand is used for that notification's **From** address - but only when that brand's domain is fully verified as described above. Brand visual settings (logo, colors) follow the same resolution path independently of email domain status.
For more on how notifications behave generally - including when Verdocs sends email versus when you handle delivery yourself - see [Controlling workflow behaviors](https://developers.verdocs.com/docs/guides/tutorials/controlling-workflow-behaviors-notifications-names-and-more).
# Bring-Your-Own Notification (/docs/guides/tutorials/bring-your-own-notification)
**Goal:** Choose the right model for how signers hear about an envelope - either Verdocs sends the standard invitation and lifecycle notifications, or your application owns every outbound message while Verdocs still powers signing workflows.
**Who this is for:** Backend engineers and technical product teams building white-label, embedded, or in-app signing experiences where communication should come entirely from their own platform.
***
## Two notification models [#two-notification-models]
| | Verdocs-managed notifications (default) | Bring-your-own (BYO) custom notifications |
| ----------------------------------- | -------------------------------------------- | ----------------------------------------------- |
| Envelope configuration | Omit `no_contact` or set `no_contact: false` | Set `no_contact: true` |
| Who sends invitations and reminders | Verdocs | Your application |
| Who sends completion emails | Verdocs | Your application |
| Who owns delivery infrastructure | Verdocs | You |
| What you must build | Minimal integration | Notification delivery + lifecycle orchestration |
The property` no_contact` is configured at the envelope-level during creation.
***
## When to use each model [#when-to-use-each-model]
### Use Verdocs-managed notifications when [#use-verdocs-managed-notifications-when]
* Verdocs-branded or co-branded email is acceptable
* You want built-in reminders and lifecycle messaging
* You prefer minimal notification infrastructure
* Your application only needs signing workflows, not messaging control
***
### Use `no_contact: true` when [#use-no_contact-true-when]
* Every signer-facing touchpoint must come from your brand
* Signers stay entirely inside your product experience
* Your organization already operates email, SMS, push, or in-app messaging infrastructure
* You need tighter control over notification timing, compliance, or localization
***
## What Verdocs still handles in BYO mode [#what-verdocs-still-handles-in-byo-mode]
Setting `no_contact: true` does not disable the Verdocs signing engine.
Verdocs still manages:
| envelopes | signing workflows |
| ------------------ | -------------------- |
| recipients | fields and documents |
| signing sessions | audit trails |
| webhooks | completion state |
| document retention | |
The primary change is that Verdocs suppresses its own recipient-facing notifications for that envelope.
***
### What gets suppressed [#what-gets-suppressed]
When `no_contact` is enabled:
* invitation emails are not sent
* reminder emails are not sent
* Verdocs-managed SMS notifications are not sent
* completion-style participant notifications are suppressed where applicable
***
### What still works normally [#what-still-works-normally]
Even with `no_contact: true`:
* webhooks continue firing
* signing sessions can still be created
* recipients still progress through workflows
* envelope lifecycle events still occur normally
Your application becomes responsible for turning those events into user-facing communication.
***
## Important workflow difference [#important-workflow-difference]
In the default flow, recipients typically receive a Verdocs-delivered invitation that starts the signing experience. In BYO mode, your application is responsible for:
1. deciding when the signer should act
2. generating or retrieving signing links
3. delivering those links through your own channels
That usually means your backend calls [Start Signing Session](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/recipients/startSigningSession) (or equivalent APIs) and sends the resulting link through your own email, SMS, push, or in-app notification system.
***
## BYO notification flow (`no_contact: true`) [#byo-notification-flow-no_contact-true]
### Step 1 - Create the envelope [#step-1---create-the-envelope]
*Include:*
```
{
"no_contact": true,
"name": "Order #4412 - signature required",
"template_id": "…",
"recipients": [ … ]
}
```
The same approach works for both template-based and template-less envelope creation flows. The important part is: `no_contact: true`.
***
### Step 2 - Subscribe to webhook events [#step-2---subscribe-to-webhook-events]
Configure webhook subscriptions for the lifecycle events your application needs.
*Typical integrations listen for:*
* envelope lifecycle events
* recipient lifecycle events
* completion events
* failure events
\*\*
*Your webhook handler should:*
1. authenticate the webhook request
2. validate tenant ownership (`organization_id`)
3. enqueue downstream notification work
***
### Step 3 - Deliver signing links yourself [#step-3---deliver-signing-links-yourself]
*When recipients should sign:*
* create or retrieve a signing session
* generate the signing URL
* send it through your own communication channels
\*\*
*Common delivery channels include:*
* transactional email
* SMS
* push notifications
* CRM notifications
* in-app inboxes
***
### Step 4 - Handle completion messaging [#step-4---handle-completion-messaging]
Verdocs still completes the envelope internally when signing finishes. However, completion emails are also suppressed in BYO mode.
*If customers expect messages such as:*
* “Your document has been signed”
* “Download your completed agreement”
* “All parties completed signing”
Your application must send those notifications itself. Most teams trigger those messages from webhook events.
***
## Default Verdocs-managed flow (`no_contact: false`) [#default-verdocs-managed-flow-no_contact-false]
When `no_contact` is omitted or set to `false`:
* Verdocs sends invitation emails
* Verdocs sends reminders
* Verdocs sends completion notifications according to organization settings
* your integration can still consume webhooks for automation
This is the simplest integration path and usually the best starting point for new implementations.
***
## Typical architecture comparison [#typical-architecture-comparison]
### Verdocs-managed notifications [#verdocs-managed-notifications]
```
Your App
→ Create Envelope
→ Verdocs sends notifications
→ Recipient signs
```
***
### Bring-your-own notifications [#bring-your-own-notifications]
```
Your App
→ Create Envelope (no_contact: true)
→ Verdocs emits webhooks
→ Your notification service sends links
→ Recipient signs through your experience
```
***
## Commonly asked questions [#commonly-asked-questions]
### Can we switch modes after envelope creation? [#can-we-switch-modes-after-envelope-creation]
That depends on your API version and environment policy. Some versions may allow updating `no_contact`, while others treat it as immutable after creation. For new integrations, treat it as a create-time decision unless your API reference explicitly documents update behavior.
***
### Does `no_contact` disable webhooks? [#does-no_contact-disable-webhooks]
No. Webhooks operate independently from notification delivery. You continue receiving lifecycle events normally.
***
### Does `no_contact` affect legal validity or audit trails? [#does-no_contact-affect-legal-validity-or-audit-trails]
No. It changes who delivers notifications - not the underlying signing process, audit records, disclosures, or retention behavior.
***
### What about SMS notifications? [#what-about-sms-notifications]
If your organization normally uses Verdocs-managed SMS delivery, BYO mode means your application becomes responsible for SMS delivery as well. The same ownership split applies across all signer-facing notification channels.
***
## In summary [#in-summary]
### Verdocs-managed notifications (`no_contact: false`) [#verdocs-managed-notifications-no_contact-false]
Verdocs sends:
* invitations
* reminders
* completion notifications
* other lifecycle communications according to organization settings
This is the simplest operational model.
***
### Bring-your-own notifications (`no_contact: true`) [#bring-your-own-notifications-no_contact-true]
Your application owns all signer-facing communication.
Verdocs still powers:
* signing workflows
* sessions
* documents
* webhooks
* audit trails
Use webhooks and signing-session APIs to drive your own branded notification experience.
***
\*\*Learn More: \*\*[Verify signer](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/recipients/verifySigner), [Start Signing Session](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/recipients/startSigningSession), [New Recipient Authentication Options](https://developers.verdocs.com/docs/learn/whats-new/new-recipient-authentication-options), [Understanding Profiles, or “Why do my API calls return the wrong data?”](https://developers.verdocs.com/docs/guides/tutorials/understanding-profiles-or-why-do-my-api-calls-return-the-wrong-data) (for org vs recipient mental models)
# Controlling Workflow Behaviors (Notifications, Names, and More) (/docs/guides/tutorials/controlling-workflow-behaviors-notifications-names-and-more)
Our default workflows were designed to meet the needs of the majority of our customers, but some use-cases need finer-grained control. To control these behaviors, you can adjust a number of flags when creating envelopes to match your use-case.
## No contact [#no-contact]
When sending an envelope, Verdocs will contact each recipient for you via Email or SMS to invite them to sign at the appropriate step in your workflow. Recipients at the same "sequence" act in parallel, and will receive invitations (and, if enabled, reminders) at the same time. Recipients at later steps will be notified once all prior recipients have completed their steps.
These messages are delivered via user-friendly templates that you can customize in your [Organization Profile](https://app.verdocs.com/settings/organization) by changing the Logo, Thumbnail, Primary Color, and Secondary Color. You can also set an invitation message per recipient to provide more information about what they are being asked to sign:
```bash
curl -X POST 'https://stage-api.verdocs.com/v2/envelopes' \
-H "Content-Type: application/json" \
-H 'authorization: Bearer ey........Nc' \
--data-raw '{...otherparams,
"recipients":[{
"name":"Recipient 1",
"type":"signer",
"first_name":"First",
"last_name":"Last",
"email":"first+last@gmail.com",
"sequence":1,
"order":1,
"message":"This version includes the adjustments we agreed to on 3/1. Thanks!"
}]}'
```
Including a message helps recipients understand what they are being asked to do, and increases click-through rates to get your documents signed more quickly.
## Sender name [#sender-name]
You can also customize the "from" name on outbound messages when creating envelopes. Note that Verdocs cannot "spoof" email addresses - notifications will still be sent from [notifications@verdocs.com](mailto:notifications@verdocs.com). But the full name shown in most email clients is normally obtained from your profile, generating an email address such as the following:
`Will Power <notifications@verdocs.com>`
if your profile name was "Will Power". Most modern email clients will show that name instead of the raw email address, which helps recipients identify your notifications in their inboxes.
This works for the majority of use-cases, but some dynamic workflows have "sender names" driven by backend processes, databases, etc. If they are very dynamic, it can be a burden to create new profiles for every new envelope being sent. To avoid this, you can also specify the sender name directly when creating an envelope:
```bash
curl -X POST 'https://stage-api.verdocs.com/v2/envelopes' \
-H "Content-Type: application/json" \
-H 'authorization: Bearer ey........Nc' \
--data-raw '{...otherparams,
"sender_name": "Paige Turner",
"recipients":[...]}'
```
## No contact [#no-contact-1]
For many users, the above options are the easiest options for customizing messages. Email delivery is challenging, and we have worked hard at Verdocs to achieve the highest "reputation" for our notifications to ensure they get delivered, and most of our customers prefer to take advantage of that.
However, if you do have your own email/SMS infrastructures, you can have full control over your outbound messages by setting the "no\_contact" flag when creating an envelope. If this is set, recipients will not receive alerts of any kind from Verdocs. You can use the metadata returned when creating the envelope to generate invitation messages of your own.
This is particularly helpful when building "in-person" signing workflows, such as kiosk apps where notifications are not required/desired at all. Our "Sign" Web embed only requires three parameters: the envelope ID, the recipient's role, and an in-person invite code which can be found in the Create Envelope response body.
```bash
curl -X POST 'https://stage-api.verdocs.com/v2/envelopes' \
-H "Content-Type: application/json" \
-H 'authorization: Bearer ey........Nc' \
--data-raw '{...otherparams,
"no_contact": true,
"recipients":[...]}'
```
# 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.
# Document Processing (/docs/guides/tutorials/document-processing)
## Organization pipeline settings [#organization-pipeline-settings]
When you upload a PDF or DOCX to a template - or attach documents directly to an envelope - Verdocs can automatically scan the file for signing fields. That automation is powerful for [Dynamic Tagging](https://developers.verdocs.com/docs/guides/tutorials/tagging-dynamic-documents) and fillable PDF workflows, but it is not always desirable: some documents contain \{\{field\_type:role\_name}}-style text that is not a Verdocs tag, and auto-detecting fillable PDF widgets can create duplicate fields when you already place fields in the template builder.
**Pipeline settings** let each **organization** opt in to the behaviors it needs. All flags default to `false`, so new organizations start with conservative, manual-first document handling until you explicitly enable automation.
This guide explains the four pipeline flags, where they apply, how to read and update them through the REST API, and common configuration patterns.
***
## When to configure pipeline settings [#when-to-configure-pipeline-settings]
Consider adjusting pipeline settings when any of the following apply:
* Your integration **embeds handlebars-style tags** in server-generated PDFs or DOCX files and expects roles and fields to be created automatically on upload.
* You upload **fillable PDFs** (for example standard government forms) and want Verdocs to map native AcroForm widgets to signing fields without hand-placing them.
* Your tag source documents are **generated programmatically**, and you prefer to skip occasional malformed tags rather than fail the entire upload.
* You **never** want automatic field detection - you place all roles and fields through the template builder or API and only need the raw document stored.
Pipeline settings are stored per **organization** and are evaluated using the organization tied to the profile or API key that performs the upload.
***
## The four pipeline flags [#the-four-pipeline-flags]
Each organization has a `pipeline_settings` object with four boolean flags. When a flag is unset, the API treats it as `false` and always returns an explicit boolean for each one.
| Flag | When `true` | When `false` (default) |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `process_tags` | Scan uploaded PDFs (and PDFs converted from DOCX) for Verdocs text tags and run the tag pipeline (redaction, role/field creation). | Treat the document as untagged - no tag scan, no tag-driven automation. |
| `process_acroforms` | If a PDF has **no text tags**, attempt to detect native fillable PDF (AcroForm) widgets and map them to signing fields. | Do not auto-detect AcroForm fields. |
| `ignore_invalid_roles` | Skip tags whose role name is missing or invalid; continue processing other tags. | Reject the upload when an invalid role tag is encountered. |
| `ignore_invalid_fields` | Skip tags that cannot be resolved to a valid field; continue processing other tags. | Reject the upload when an invalid field tag is encountered. |
`process_tags`\*\* and **`process_acroforms`** are independent.\*\* You can enable AcroForm detection without text-tag scanning, or the reverse. AcroForm detection only runs when **no text tags** were found on the document.
The `ignore_invalid_*` flags apply when documents are attached to **templates** (see [When settings take effect](#when-settings-take-effect) below).
***
## When settings take effect [#when-settings-take-effect]
Pipeline settings are read from the **sender's organization** at document-ingest time.
### Template documents [#template-documents]
When you attach a document to a template - via file upload, URI, or base64 - the organization's flags control whether text tags and AcroForms are detected, and whether invalid tags cause a hard failure or are skipped.
Relevant API: [Attach a document to a template](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/template-documents/createTemplateDocument)
### Envelopes without a template [#envelopes-without-a-template]
When you [create an envelope](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/envelopes/createEnvelope) and supply documents inline (rather than referencing an existing template), the same `process_tags` and `process_acroforms` gates apply.
See also: [Send an envelope without a template](https://developers.verdocs.com/docs/guides/tutorials/send-an-envelope-without-a-template)
### Envelopes created from an existing template [#envelopes-created-from-an-existing-template]
Envelopes created **from an existing template** use the template's already-defined roles and fields. Pipeline settings do not re-scan template source files at send time.
***
## Reading current settings [#reading-current-settings]
Organization pipeline settings are available to **organization admins** only. An admin can read settings for their own organization; cross-organization access is denied.
`GET /v2/organizations/{organization_id}/pipeline-settings`
**Example response:**
```
{
"process_acroforms": false,
"process_tags": false,
"ignore_invalid_roles": false,
"ignore_invalid_fields": false
}
```
***
## Updating settings [#updating-settings]
`PATCH /v2/organizations/{organization_id}/pipeline-settings`
Send only the flags you want to change. Updates are **merged** - setting one flag does not reset the others. Unknown keys and non-boolean values are rejected with `400`.
**Enable dynamic tagging for an org that generates tagged PDFs server-side:**
```
{
"process_tags": true
}
```
**Enable AcroForm auto-detection for standard fillable PDFs:**
```
{
"process_acroforms": true
}
```
> **Multi-tenant note:** In a parent/child organization hierarchy, pipeline settings are stored on each **organization** individually. If child orgs upload their own documents, configure each tenant org separately. See [Organization Hierarchies](https://developers.verdocs.com/docs/guides/tutorials/organization-hierarchies).
***
## Common configurations [#common-configurations]
#### Dynamic Tagging workflows [#dynamic-tagging-workflows]
If your integration embeds handlebars-style tags in PDF or DOCX source files ([Tagging Dynamic Documents](https://developers.verdocs.com/docs/guides/tutorials/tagging-dynamic-documents)), enable:
\{ "process\_tags": true }
Confirm your organization's current values with `GET /v2/organizations/{id}/pipeline-settings` before relying on automatic tag processing in production.
#### Fillable PDF auto-detection [#fillable-pdf-auto-detection]
Enable AcroForm detection when you are **not** also embedding text tags in the same file:
`{ "process_acroforms": true }`
Test in staging first: some PDFs mix visible widgets with manually placed builder fields, and auto-detection can create overlapping fields.
#### Programmatically generated tags with occasional errors [#programmatically-generated-tags-with-occasional-errors]
If tags are generated programmatically and occasional malformed entries are acceptable:
```
{
"process_tags": true,
"ignore_invalid_roles": true,
"ignore_invalid_fields": true
}
```
With both ignore flags off (the default), Verdocs surfaces authoring errors immediately - usually preferable while you are still building templates.
#### Manual field placement only [#manual-field-placement-only]
Leave all flags at their defaults (`false`). Uploaded PDFs and DOCX files are stored as-is; define roles and fields through the API or UI separately.
***
## See also [#see-also]
* [Dynamic Tagging](https://developers.verdocs.com/docs/learn/whats-new/dynamic-tagging) - overview of handlebars-style tags
* [Tagging Dynamic Documents](https://developers.verdocs.com/docs/guides/tutorials/tagging-dynamic-documents) - tag syntax, roles, and placement
* [Attach a document to a template](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/template-documents/createTemplateDocument)
* [Create Envelope](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/envelopes/createEnvelope)
* [Organization Hierarchies](https://developers.verdocs.com/docs/guides/tutorials/organization-hierarchies)
# Embedded signing in React (/docs/guides/tutorials/embedded-signing-in-react)
This walks the whole path for a React application: create an envelope from your backend, get the signer to a route you own, render the signing experience inline, and find out when it completes. The signer never leaves your product and never sees a Verdocs URL.
There are two packages involved and they do different jobs. [`@verdocs/js-sdk`](/docs/reference/SDK/languages/getting-started) talks to the API and belongs on your server. [`@verdocs/web-sdk-react`](/docs/reference/SDK/web/get-started) renders the UI and belongs in your React app.
## 1. Install [#1-install]
```bash
npm install @verdocs/web-sdk-react # your React app
npm install @verdocs/js-sdk # your server
```
## 2. Create the envelope on your server [#2-create-the-envelope-on-your-server]
Envelope creation needs your API credentials, so it happens server side. Never put a client secret in browser code.
```ts
import {VerdocsEndpoint, authenticate, createEnvelope} from '@verdocs/js-sdk';
const endpoint = new VerdocsEndpoint();
// authenticate() returns the tokens but does not attach them, so set it yourself.
const {access_token} = await authenticate(endpoint, {
grant_type: 'client_credentials',
client_id: process.env.VERDOCS_CLIENT_ID!,
client_secret: process.env.VERDOCS_CLIENT_SECRET!,
});
endpoint.setToken(access_token);
const envelope = await createEnvelope(endpoint, {
template_id: '8e0b...c41a',
name: 'Mutual NDA',
recipients: [{role_name: 'Signer', email: 'ada@acme.com', first_name: 'Ada', last_name: 'Lovelace'}],
});
```
See [Server workflow with static templates](/docs/guides/tutorials/server-workflow-with-static-templates) for the full set of options, and [Send an envelope without a template](/docs/guides/tutorials/send-an-envelope-without-a-template) if you are uploading a PDF directly instead.
## 3. Get the signer to your page [#3-get-the-signer-to-your-page]
The response carries one recipient entry per signer, each with the three values the signing component needs: the envelope ID, the role, and an invite code. Build your own URL from them:
```
https://yourapp.com/sign/:envelopeId/:roleName/:inviteCode
```
By default Verdocs emails the signer a link to its own hosted signing page. To send them to your route instead, suppress the Verdocs notification and send your own message. [Bring-your-own notification](/docs/guides/tutorials/bring-your-own-notification) covers exactly that, and it is the step most people miss on the first try.
The invite code is a bearer credential for that one envelope and that one role. Treat it like a password: it belongs in the link you send the signer and nowhere else.
## 4. Render the signer [#4-render-the-signer]
```tsx
import {useRef} from 'react';
import {useParams} from 'react-router-dom';
import {VerdocsEndpoint} from '@verdocs/js-sdk';
import {VerdocsSign} from '@verdocs/web-sdk-react';
export const SignPage = () => {
const {envelopeId = '', roleName = '', inviteCode = ''} = useParams();
// sessionType: 'signing' means the signer is never asked to log in or create
// an account. Held in a ref so a re-render does not rebuild the session.
const endpoint = useRef(new VerdocsEndpoint({sessionType: 'signing'}));
return (
{
if (e.detail?.event === 'submitted') {
// The signer has finished. Route them wherever makes sense in your app.
}
}}
onSdkError={(e: any) => console.error('Verdocs signing error', e.detail)}
/>
);
};
```
`VerdocsSign` fills its container, so give it a parent with a real height. It renders the document, the fields, the signature and initial dialogs, and any authentication the recipient requires, including passcode, SMS, ID scan, and KBA. You do not wire those up separately; see [the recipient auth ladder](/docs/guides/tutorials/the-recipient-auth-ladder) for what each one asks of the signer.
### The props [#the-props]
| Prop | What it is |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `endpoint` | A `VerdocsEndpoint` with `sessionType: 'signing'`. Omit it and the component builds one with the same default. |
| `envelopeId` | The envelope being signed. |
| `roleId` | The recipient's role name, for example `Signer`. |
| `inviteCode` | The invite code for that recipient. |
| `headerTargetId` | The ID of a `
` you own. The component moves its header there on first render, which is how you control placement and scroll behavior. Applied once, so do not render that container conditionally. |
| `toolbarStyle` | `controls` or `menu`. |
### The events [#the-events]
| Event | When it fires |
| ------------------- | ------------------------------------------------------------------------------- |
| `onEnvelopeLoaded` | The envelope is loaded and about to render. Useful for analytics. |
| `onEnvelopeUpdated` | Something changed. Check `e.detail.event` for `submitted` to detect completion. |
| `onSdkError` | Something went wrong. Log it; do not leave the signer staring at an empty box. |
## 5. Confirm completion on your server [#5-confirm-completion-on-your-server]
`onEnvelopeUpdated` fires in the signer's browser, which makes it right for updating your UI and wrong for anything that matters. A browser can close mid-submit and a client event can be forged.
Use [webhooks](/docs/reference/Rest-API/webhooks) for the authoritative signal, and read [Securing your webhooks](/docs/guides/tutorials/securing-your-webhooks-hmac-vs-oauth) before you trust the payload. Treat the client event as a hint and the webhook as the fact.
One thing worth knowing: an envelope can report `complete` before the signed PDF and audit certificate have finished generating. If your flow downloads the document immediately on completion, wait for the event that says the artifacts are ready rather than the one that says signing finished. The [FAQ](/docs/learn/FAQ) covers the distinction.
## Branding [#branding]
Signing inherits the brand on the envelope's organization, so colors, logo, and disclaimers follow without any work in your app. To match your own styles more closely, override the CSS variables:
```css
:root {
--verdocs-primary-color: #654dcb;
--verdocs-button-radius: 999px;
--verdocs-field-background: #8dc63f1a;
}
```
[Styling](/docs/reference/SDK/web/styling) has the full variable reference.
## If you cannot use Web Components [#if-you-cannot-use-web-components]
Some environments, older Angular versions and WordPress among them, cannot host custom elements. [IFRAME embeds](/docs/guides/tutorials/iframe-embeds) gives you the same flow with less styling control.
## Vue, Angular, and vanilla [#vue-angular-and-vanilla]
The same component ships for every framework; only the wrapper import changes. [Get started with the Web SDK](/docs/reference/SDK/web/get-started) covers the others, and [Components](/docs/reference/SDK/web/components) is a live Storybook of everything available.
# Entitlements (/docs/guides/tutorials/entitlements)
## What are entitlements? [#what-are-entitlements]
An **entitlement** is a record that says your organization is allowed to use a specific Verdocs capability for a given period. Entitlements are attached to an **organization**, not to individual users, API keys, or brands.
In practice, entitlements answer three questions:
1. **Can we use this feature?** - For example, SMS invitations or SMS-based signer verification.
2. **How much can we use?** - Some entitlements include quantity limits (such as how many white-label brands you can create).
3. **When is access valid?** - Each entitlement has a start and end date.
If you run a multi-tenant SaaS on Verdocs, entitlements also work cleanly with [organization hierarchies](https://developers.verdocs.com/docs/guides/tutorials/organization-hierarchies): **child organizations inherit entitlements from their parent**. You can grant capabilities once at the parent and have every sub-account benefit, which is much simpler than provisioning each tenant separately.
You can inspect entitlements for your current organization with the **Get organization entitlements** API (`GET /v2/organizations/entitlements`). For billing dashboards and pass-through charges, pair that with [Get organization usage](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/organizations/getOrganizationUsage) and the `entitlement_used` webhook event, which fires when metered activity is recorded.
Entitlements are provisioned by Verdocs (typically as part of your contract or after you contact support). They are not something you toggle on yourself in the dashboard today.
***
## Which features require an entitlement? [#which-features-require-an-entitlement]
Not every Verdocs feature is entitlement-gated. Core workflows - templates, envelopes, email notifications, passcode and email signer verification, webhooks, and the signing experience - work without a special entitlement. The table below covers capabilities that **do** depend on entitlements today.
| Capability | What it controls | If you're not entitled |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Envelope Limit** | The max quantity of envelopes that can be sent within your pay period (monthly or yearly). | You cannot send any more envelopes. Please contact us if we need to discuss options. |
| **SMS notifications** | Text-message invitations and reminders to recipients | SMS is skipped; email notifications still send normally. |
| **SMS signer verification** | SMS one-time passcode as an `auth_method` on a recipient (see [The Recipient Auth Ladder](https://developers.verdocs.com/docs/guides/tutorials/the-recipient-auth-ladder)) | Signers see an error that SMS verification is not available for the document. |
| **Custom branding (Brands)** | How many distinct [Brands](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/brands/createBrand) you can create for white-label signing experiences | Brand creation is blocked once you reach your limit. Contact support to raise it. |
| **SMS Auth** | Sends an authentication notification via SMS. | Cannot authenticate over SMS, email authentication is still available. |
| **KBA Auth** | Use KBA authentication for your recipients. **Costs $1 per usage**. | KBA authentication is not available. |
| **ID Auth** | Authenticate recipients via their government-issued IDs. Uses their camera to analyze identity. | ID authentication is not available. |
A few related notes:
* **Metered authentication methods** (KBA, ID verification, and similar pass-through capabilities) are managed through the entitlements and usage system even when they don't block an API call outright. Usage is recorded so you can monitor consumption and align billing - especially useful with parent/child org setups. See [Organization Hierarchies](https://developers.verdocs.com/docs/guides/tutorials/organization-hierarchies) for the monitoring story.
* **Custom signing disclaimers** are a separate approval path: you can customize the disclosure shown before signing, but Verdocs must approve the change for legal reasons. If you don't see the setting in your dashboard, request access via support ([Custom Disclaimers](https://developers.verdocs.com/docs/learn/whats-new/custom-disclaimers)).
***
## If something is not working [#if-something-is-not-working]
If something isn't working and you suspect entitlements, check `GET /v2/organizations/entitlements` first, then your usage metrics. When in doubt, your account team or [support@verdocs.com](mailto:support@verdocs.com) can confirm what's on your contract.
# Fill templates from your data (/docs/guides/tutorials/fill-templates-from-your-data)
Use your own data structures to make pre-filling data, such as a customer's name, a policy number, or a start date, fast and painless. Throughout this document, we will use the following data structure as an example record, but any flat or nested data structure may be used.
```json
{
"policy_id": "1234567890",
"applicant": {
"full_name": "Jordan Rivera",
"date_of_birth": "1988-04-12",
"email": "jordan.rivera@example.com",
"phone": "(555) 010-0199",
"mailing_address": {
"line1": "100 Example Ave",
"city": "Springfield",
"state": "OH",
"postal_code": "45402"
}
},
"co_applicant": {
"full_name": "Casey Rivera"
},
"property": {
"address": {
"line1": "48 Harbor Rd",
"city": "Springfield",
"state": "OH",
"postal_code": "45404"
},
"year_built": 1994
},
"policy": {
"number": "HO-2026-001234",
"effective_date": "2026-11-01",
"annual_premium": 1840.00,
"coverage": {
"level": "standard",
"dwelling_limit": 350000,
"flood": true
}
},
"additional_insureds": [{
"full_name": "Riley Rivera",
"relationship": "Child"
}]
}
```
## Assign data keys [#assign-data-keys]
A "data key" is your system's identifier for a value. Data keys may also refer to nested values, using a `.` period as a separator. In the example above, `policy_id` is the simplest type of key, while `applicant.full_name` and `property.address.state` refer to nested values.
To assign keys, set `data_key` on a field, either via our Template Builder's field inspector panel ("Fill with"), or when calling [create](/docs/reference/Rest-API/api-docs/fields/createField) or [update](/docs/reference/Rest-API/api-docs/fields/updateField) at the API level, or [createEnvelope](/docs/reference/Rest-API/api-docs/envelopes/createEnvelope) directly without a template. When using tags, set the `k` option, e.g. `{{textbox:Applicant;k:applicant.full_name}}` (see [Tagging dynamic documents](/docs/guides/tutorials/tagging-dynamic-documents)).
## Send your data [#send-your-data]
When calling [createEnvelope](/docs/reference/Rest-API/api-docs/envelopes/createEnvelope), pass your data via the `prefill_data` parameter as shown below:
```typescript
import {createEnvelope} from '@verdocs/js-sdk';
const envelope = await createEnvelope(endpoint, {
template_id: templateId,
recipients: [{role_name: 'Applicant', first_name: 'Jordan', last_name: 'Rivera', email: 'jordan@example.com'}],
prefill_data: {
applicant: {full_name: 'Jordan Rivera', state: 'TX'},
policy: {effective_date: '2026-11-01', premium: 1234.5, coverage: {flood: true}},
// ... More data
},
});
```
Note that nested objects and dotted keys work the same way, so you can also pass the data in a flat structure such as:
```typescript
const prefill_data = {'applicant.full_name': 'Jordan Rivera', 'applicant.state': 'TX', 'policy.effective_date': '2026-11-01'};
```
Data will be mapped to each field type as follows:
| Field | Send |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Text | Text, a number, or true/false. A number in a plain text field will be shown in a locale-friendly format, e.g. `1,234.50`. A [number field](/docs/guides/tutorials/formatting-text-fields) stores the number itself, and also accepts locale-formatted text as an input, e.g. `12.450,50` for `de-DE`. |
| Date | An ISO 8601 date, like `2026-11-01` |
| Checkbox | Accepts `true` or `false`, `"yes"` or `"no"`, or `1` or `0`. |
| Dropdown | The option's id or its label |
| Radio | The label or name of the option to select |
When you also send a `fields` entry for a field, that entry supersedes other settings such as from a template. This allows you to override a field placement or configuration on a one-off basis.
## Developer feedback [#developer-feedback]
Data mapping is a complex operation and it's easy to make mistakes when hand-typing data keys, or if data structures change over time. To help troubleshoot issues, when prefilling data Verdocs will include a `prefill_result` block in the response. For privacy and security reasons, data values will never be included in the response (so it should also be safe to log for most organizations). An example response is below:
```json
{
"placements_filled": 6,
"unused_keys": ["applicant.ful_name"],
"hints": [{"key": "applicant.ful_name", "did_you_mean": "applicant.full_name"}],
"missing_keys": ["policy.coverage.flood"],
"errors": [{"key": "applicant.state", "field": "state", "message": "No dropdown option matches this value"}],
"format_problems": [{"key": "applicant.email", "field": "email", "message": "Not a valid email"}]
}
```
`unused_keys` are keys you sent that were not mapped to anything. In the example above, there was obviously a typo in `applicant.ful_name` so it would not have been mapped to any fields looking for `applicant.full_name`. Unused keys are not always errors - you may simply not be using one of them. But if a form is not mapping data the way you expect, this is the best first thing to check. Where possible, we will provide a `hints` block in the result with our best guess of what was meant.
If a field is mapped to a key your data object doesn't provide, we will list those in `missing_keys`. These are nearly always errors and are the second thing we recommend examining when troubleshooting.
Other errors will be listed in `errors` if both the field and key were found and matched, but the requested value could not be prefilled for another reason, such as calling for a dropdown entry that the dropdown does not provide, while `format_problems` will list cases where everything was mapped, but the value supplied doesn't match the field's validation or formatting (see [Formatting text fields](/docs/guides/tutorials/formatting-text-fields)). If the field is not read-only, the recipient will be able to correct the issue themselves but this creates a poor user experience. If the field is read-only, they may be blocked from proceeding at all. Either way, these issues are worth fixing at the source.
## Strict mode [#strict-mode]
The `prefill_result` block provides feedback, but doesn't necessarily block an envelope from being sent - Verdocs will make a best-efforts attempt to proceed with the data provided. In some cases you may prefer that we stop and report an error. To achieve this, set `prefill_options: {strict: true}` and we will refuse these requests rather than allowing them to proceed. To enable strict mode but ignore unused keys (a common need if you don't control the source data structure), set `prefill_options: {strict: true, ignore_unused: true}`.
We also provide a dry-run setting. If you set `dry_run: true` on the request (usually alongside `prefill_options: {strict: true}`), we will run the complete validation pass on the provided data but without creating an envelope (js-sdk users, see `previewEnvelope`). This can be a convenient way to verify that data mapping is complete and valid if your own system provides the UI for users to perform this task.
## Bulk sends [#bulk-sends]
`POST /v2/envelopes/bulk` takes `prefill_data` on each entry, so every envelope in the batch gets its own data, while `prefill_options` applies to the entire batch. The call response will include `prefill_results` as an array, with one record per entry in the bulk-send request, in the same order. For entries with no `prefill_data`, the `prefill_results` array element will be `null`. In strict mode, all rows must be valid or the entire batch will be rejected, avoiding any risk of a partially sent batch.
```json
{
"template_id": "d2338742-f3a1-465b-8592-806587413cc1",
"prefill_options": {"strict": true},
"entries": [
{"recipients": [{"role_name": "Applicant", "first_name": "Jordan", "last_name": "Rivera", "email": "jordan@example.com"}], "prefill_data": {"applicant": {"full_name": "Jordan Rivera"}}},
{"recipients": [{"role_name": "Applicant", "first_name": "Sam", "last_name": "Lee", "email": "sam@example.com"}], "prefill_data": {"applicant": {"full_name": "Sam Lee"}}}
]
}
```
## Template requirements [#template-requirements]
The [`getTemplateDataContract`](/docs/reference/Rest-API/api-docs/templates/getTemplateDataContract) method lists every data key a template uses, including its type and options, how many fields use it, and whether it's needed (a read-only field the signer can't fill in). It also returns a JSON Schema for the template's `prefill_data`, which may be used to validate your payloads before sending. It also provides a `contract_hash` value. This is a hash of the data key mapping requirements, and may be used in a CI check to determine whether a change has been made that might invalidate future sends.
```typescript
import {getTemplateDataContract} from '@verdocs/js-sdk';
const {keys, json_schema, contract_hash} = await getTemplateDataContract(endpoint, templateId);
```
# Formatting text fields (/docs/guides/tutorials/formatting-text-fields)
Text fields accept any text by default, and the signed PDF prints it at 11 points. When a field needs something more specific, such as a phone number, a dollar amount, or an account number in a fixed shape, you describe that in the field's `config`. Signers see a hint in the empty field and a short message when what they entered doesn't match, and they can't finish until it does.
## Setting a field's config [#setting-a-fields-config]
`config` is part of a template field, so you set it when you [create](/docs/reference/Rest-API/api-docs/fields/createField) or [update](/docs/reference/Rest-API/api-docs/fields/updateField) the field. Envelopes sent from the template copy it along with the rest of the field, and fields you add to an envelope directly (as in [Send an envelope without a template](/docs/guides/tutorials/send-an-envelope-without-a-template)) take the same `config`.
```typescript
import {updateField} from '@verdocs/js-sdk';
await updateField(endpoint, templateId, 'amount', {
config: {
type: 'textbox',
number: {style: 'currency', currency: 'USD', decimals: 2, min: 0},
fit: {max_font_size: 11, min_font_size: 8, overflow: 'ellipsize'},
},
});
```
`config.type` always matches the field's type, so you can leave it out and we fill it in. An update replaces the whole `config`, so include every option you want to keep, or send `null` to clear it. The template builder sets the same options from its Inspector panel.
## Built-in formats [#built-in-formats]
The field's `validator` checks for a common format:
| `validator` | Accepts |
| ------------- | ------------------------------------------------------------------- |
| `email` | An email address |
| `phone` | A phone number, with or without a country code |
| `url` | A Web address starting with `http://` or `https://` |
| `postal_code` | A ZIP or postal code of 3 to 10 letters, digits, spaces, or hyphens |
| `number` | A number, optionally with thousands separators |
| `date` | A date like `10/27/2026` or `2026-10-27` |
| `ssn` | A Social Security number like `123-45-6789` |
A `validator` we don't recognize is treated as plain text.
## Numbers, currency, and percentages [#numbers-currency-and-percentages]
`config.number` makes a field a number field. Signers enter the number the way their locale writes it, and when they leave the field it's rewritten in the field's style. We store the plain number, like `12450.5`, so your integration never has to parse `$12,450.50`, and the signed PDF prints it formatted.
| Option | Values |
| ------------ | -------------------------------------------------- |
| `style` | `number`, `currency`, or `percent` (required) |
| `locale` | A locale like `de-DE` (defaults to `en-US`) |
| `currency` | An ISO 4217 code like `EUR` (defaults to `USD`) |
| `decimals` | Decimal places to show, 0 to 6 |
| `min`, `max` | The smallest and largest number a signer may enter |
| `number` | Signer enters | Stored | Printed |
| ------------------------------------------------------- | ------------- | --------- | ---------- |
| `{style: 'currency', currency: 'USD', decimals: 2}` | `12450.5` | `12450.5` | $12,450.50 |
| `{style: 'number', locale: 'de-DE', decimals: 2}` | `12.450,5` | `12450.5` | 12.450,50 |
| `{style: 'currency', currency: 'EUR', locale: 'fr-FR'}` | `1 234,5` | `1234.5` | 1 234,50 € |
| `{style: 'percent'}` | `12.5` | `12.5` | 12.5% |
A number field uses its `number` settings in place of `validator`. To prefill one, send the plain number as a string, like `"12450.5"`.
## Input masks [#input-masks]
`config.input_mask` gives the value a fixed shape. Each `_` is a slot for one character the signer types, and every other character is filled in for them. The mask also shows in the empty field, and the stored value includes the filled-in characters.
```json
{"type": "textbox", "input_mask": "(___) ___-____"}
```
A signer who types `5550123456` gets `(555) 012-3456`, and the field isn't complete until every slot is filled. A slot accepts any character, so pair the mask with a pattern when slots must be digits:
```json
{
"type": "textbox",
"input_mask": "(___) ___-____",
"validation": {"pattern": "\\(\\d{3}\\) \\d{3}-\\d{4}"}
}
```
## Patterns [#patterns]
`config.validation.pattern` is a regular expression the whole value has to match, and `validation.message` is what signers see when it doesn't:
```json
{
"type": "textbox",
"validation": {"pattern": "AC-\\d{6}", "message": "Enter your account number, like AC-123456."}
}
```
We match the pattern against the entire value, so you don't need `^` and `$`. Patterns can be up to 500 characters, and we refuse ones that could take too long to match on some values, such as nested repeats like `(a+)+`.
## Text case and length [#text-case-and-length]
`config.text_case` is `upper` or `lower`. Signing converts what the signer types, and we apply it again when a value is saved and when it's stamped, so values your application fills in follow it too. `config.max_length` caps the value at 1 to 10,000 characters.
## Fitting text on the signed PDF [#fitting-text-on-the-signed-pdf]
`config.fit` decides how the value fits the field's width on the signed PDF. Stamping starts at `max_font_size` and steps down toward `min_font_size` until the text fits. Text that's still too wide at the smallest size follows `overflow`.
| Option | Values |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `max_font_size` | The size stamping starts at, 4 to 72 points (defaults to 11) |
| `min_font_size` | The smallest size it shrinks to. Without it, text stays at `max_font_size`. |
| `overflow` | `overflow` lets the text run past the field (the default), `truncate` cuts it off, and `ellipsize` cuts it off and ends it with "…" |
In a multi-line field, every line shares the size that fits the widest one. Fit only changes the signed PDF; signers see their full value while they type.
## Lining the value up [#lining-the-value-up]
`config.align` is `left` (the default), `center`, or `right`. It lines the value up with that side of the field, both while the signer types and on the signed PDF. Right alignment is handy for numbers printed just before a `%` or a unit, since `0%` and `100.00%` then end in the same spot. When `overflow` lets text run over, a right-aligned value that's too wide runs past the field's left edge, and a centered one past both edges.
```json
{"type": "textbox", "number": {"style": "number", "decimals": 2}, "align": "right"}
```
## When several checks apply [#when-several-checks-apply]
Signers see one message at a time, for the first check the value fails: the format or number range, then the mask, then the pattern, then the length. Empty values pass every check, since `required` decides whether a field can be left empty. Read-only fields skip the checks entirely.
## Filling fields from your application [#filling-fields-from-your-application]
When your application fills fields itself, for example in a [proxied signing flow](/docs/guides/tutorials/proxied-signing-flows), we apply `text_case` but store the value without the other checks. js-sdk exports the helpers signing uses, so you can check a value before you send it:
```typescript
import {getFieldFormatProblem, parseFieldNumber} from '@verdocs/js-sdk';
if (field.config?.type === 'textbox' && field.config.number) {
const amount = parseFieldNumber(field.config.number, '$12,450.50'); // 12450.5
const problem = getFieldFormatProblem(field, String(amount)); // null when it passes
}
```
A failed check returns `format`, `range`, `mask`, `pattern`, or `length`. `formatFieldNumber` goes the other way, turning a stored number into the text the field shows.
# IFRAME embeds (/docs/guides/tutorials/iframe-embeds)
Verdocs' Web components provide highly customizable controls for building e-Signing applications. However, some legacy applications and environments such as Wordpress do not yet support Web components. To provide support for these environments, our six most popular components may be embedded via IFRAME links.
To do this, use code such as the following:
```html
```
Adjust the style attribute to match your requirements. Note that with IFRAMEs you will have no styling/customization options, and all parameters must be specified in the URL.
We offer six embeds via the following URLs:
* VerdocsAuth: `https://app.verdocs.com/embeds/auth`
* VerdocsBuild: `https://app.verdocs.com/embeds/build/TEMPLATE_ID`
* VerdocsView: `https://app.verdocs.com/embeds/view/ENVELOPE_ID`
* VerdocsPreview: `https://app.verdocs.com/embeds/preview/TEMPLATE_ID`
* VerdocsSend: `https://app.verdocs.com/embeds/send/TEMPLATE_ID`
* VerdocsSign: `https://app.verdocs.com/embeds/sign/ENVELOPE_ID/ROLE_NAME/INVITE_CODE`
## Events [#events]
Your page can't see what happens inside an IFRAME, so each embed posts a message to its parent window as things happen, such as a signer finishing. Every message has `source` (always `"verdocs"`), `version` (currently `1`), `embed` (which embed sent it, such as `"sign"`), and `event`, plus the ids listed below. Messages only include ids and event names, so use the ids with the API or webhooks when you need more detail.
Check that a message came from the host in your IFRAME's `src` before acting on it:
```js
window.addEventListener('message', (e) => {
if (e.origin !== 'https://app.verdocs.com' || e.data?.source !== 'verdocs') {
return;
}
if (e.data.event === 'submitted') {
// The signer finished, so close the dialog or move on to the next step
}
});
```
| Embed | Events | Includes |
| ----- | --------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Sign | `loaded`, `agreed`, `later`, `printed`, `submitted`, `declined` | `envelope_id`, `role_name` |
| View | `canceled`, `printed`, `downloaded` | `envelope_id` |
| Build | `stepChanged`, `templateUpdated`, `sent` | `template_id`, plus `step` for `stepChanged` and `envelope_id` for `sent` |
| Send | `sent`, `exit` | `template_id`, plus `envelope_id` for `sent` |
| Auth | `authenticated` | `authenticated` (true or false) |
| All | `error` | `message`, `status` (the HTTP status, when there is one), and the embed's ids |
| All | `resize` | `height` |
`later` means the signer chose to finish later.
To fit the IFRAME to its content, set its height from `resize`. It reports the height the embed needs to show everything without scrolling, and never less than the IFRAME's current height, so start small and let it grow. Sign and View scroll on their own at any height, so with those you only need this if you'd rather your page do the scrolling.
```js
const frame = document.getElementById('verdocs-frame');
window.addEventListener('message', (e) => {
if (e.origin === 'https://app.verdocs.com' && e.data?.source === 'verdocs' && e.data.event === 'resize') {
frame.style.height = `${e.data.height}px`;
}
});
```
# Tutorials (/docs/guides/tutorials)
### [Testing KBA with the sandbox](/docs/guides/tutorials/testing-kba-with-the-sandbox) [#testing-kba-with-the-sandbox]
Save money and standardize your KBA testing in your lower environments.
***
### [Formatting text fields](/docs/guides/tutorials/formatting-text-fields) [#formatting-text-fields]
Control what signers can enter in a text field, how numbers appear, and how the value fits its box on the signed PDF.
***
### [Proxied signing flows](/docs/guides/tutorials/proxied-signing-flows) [#proxied-signing-flows]
Complete one recipient's part of an envelope through the API from your own interface, such as a chat assistant or a lobby kiosk, without showing them a signing interface.
***
### [Template Changes and Sent Envelopes](/docs/guides/tutorials/template-changes-and-sent-envelopes) [#template-changes-and-sent-envelopes]
Learn why editing a Verdocs template does not change the documents and fields in envelopes already sent.
***
### [Add a custom email domain to your brand](/docs/guides/tutorials/add-a-custom-email-domain-to-your-brand) [#add-a-custom-email-domain-to-your-brand]
Send Verdocs notifications from your own domain - configure DNS, verify SPF/DKIM/DMARC, and gain insight into when custom sending goes live.
***
### [Why am I not receiving Verdocs email notifications?](/docs/guides/tutorials/why-am-i-not-receiving-verdocs-email-notifications) [#why-am-i-not-receiving-verdocs-email-notifications]
Troubleshooting steps to take if transactional notification emails are not showing up in the primary inbox.
***
### [Verifying a Completed Verdocs PDF Signature](/docs/guides/tutorials/verifying-a-completed-verdocs-pdf-signature) [#verifying-a-completed-verdocs-pdf-signature]
Learn how to validate your PDF's certificate.
***
### [Entitlements](/docs/guides/tutorials/entitlements) [#entitlements]
Learn more about the additional features that Verdocs offers.
***
### [The Recipient Auth Ladder](/docs/guides/tutorials/the-recipient-auth-ladder) [#the-recipient-auth-ladder]
You configure a recipient with several auth\_methods, including: passcode, email, SMS, ID scan, and KBA
***
### [Document Processing](/docs/guides/tutorials/document-processing) [#document-processing]
The Verdocs document processing pipeline allows key features to be flexible, regardless of the use case.
***
### [Securing Your Webhooks: HMAC vs OAuth](/docs/guides/tutorials/securing-your-webhooks-hmac-vs-oauth) [#securing-your-webhooks-hmac-vs-oauth]
Anyone on the internet can send an HTTP request to a public URL. Verdocs provides two ways to verify the caller is actually Verdocs: HMAC (shared-secret signatures) and OAuth client credentials (short-lived bearer tokens). Choose the model that best matches your platform’s existing security architecture.
***
### [Send an envelope without a template](/docs/guides/tutorials/send-an-envelope-without-a-template) [#send-an-envelope-without-a-template]
Walk through the process of creating and sending an envelope when you already have a PDF (or DOCX) and do not want to create a Verdocs `Template` first.
***
### [Bring-Your-Own Notification](/docs/guides/tutorials/bring-your-own-notification) [#bring-your-own-notification]
Choose the right model for how signers hear about an envelope - either Verdocs sends the standard invitation and lifecycle notifications, or your application owns every outbound message while Verdocs still powers signing workflows.
***
### [Managing Your API Keys](/docs/guides/tutorials/managing-your-api-keys) [#managing-your-api-keys]
This guide explains how Verdocs API authentication and organization relationships work, including how API keys map to profiles and organizations, how multi-tenant SaaS integrations should structure credentials, and how recipient signing workflows operate without requiring signer accounts.
***
### [Understanding Profiles, or "Why do my API calls return the wrong data?"](/docs/guides/tutorials/understanding-profiles-or-why-do-my-api-calls-return-the-wrong-data) [#understanding-profiles-or-why-do-my-api-calls-return-the-wrong-data]
Periodically, we receive support requests from developers who believe they are receiving the wrong template/envelope data when querying lists of those records. A common source of this issue is a misunderstanding in the concept of a "Profile" within the Verdocs ecosystem. This guide covers how Profiles work within Verdocs and provides a few options for controlling this behavior.
***
### [Tagging Dynamic Documents](/docs/guides/tutorials/tagging-dynamic-documents) [#tagging-dynamic-documents]
Some types of documents may not be suitable for working with in a graphical "template builder". In these cases, developers may embed tags to identify where signing fields should be placed and managed by Verdocs.
***
### [Organization Hierarchies](/docs/guides/tutorials/organization-hierarchies) [#organization-hierarchies]
Learn how organization hierarchies can help you track and manage usage-based billing for your own platform's e-signing activities.
***
### [IFRAME embeds](/docs/guides/tutorials/iframe-embeds) [#iframe-embeds]
Verdocs' Web components provide highly customizable controls for building e-Signing applications, but some legacy applications and environments such as Wordpress do not yet support them. Learn how to use our IFRAME alternatives anywhere Web components cannot be used.
***
### [Understanding and Managing Profiles](/docs/guides/tutorials/understanding-and-managing-profiles) [#understanding-and-managing-profiles]
A Profile in Verdocs is a crucial component in managing signing workflows and security for your documents. This guide will help you understand how they work and how you can override them in highly dynamic workflows.
***
### [Controlling Workflow Behaviors (Notifications, Names, and More)](/docs/guides/tutorials/controlling-workflow-behaviors-notifications-names-and-more) [#controlling-workflow-behaviors-notifications-names-and-more]
Our default workflows were designed to meet the needs of the majority of our customers, but some use-cases need finer-grained control. Learn about several of the flags we offer to control how signing workflows are executed.
***
### [Server Workflow with Static Templates](/docs/guides/tutorials/server-workflow-with-static-templates) [#server-workflow-with-static-templates]
This workflow is the simplest use-case, and is the recommended place to start when building an e-Signing experience using Verdocs.
***
# Managing Your API Keys (/docs/guides/tutorials/managing-your-api-keys)
### Overview [#overview]
When building with Verdocs, it helps to understand the difference between four related concepts:
* **User**: A person with a Verdocs identity.
* **Organization**: A company, workspace, tenant, or customer account in Verdocs.
* **Profile**: A user’s relationship to a specific organization.
* **Recipient**: A person who receives or signs an envelope.
In most server-side integrations, your application authenticates with an API key that acts as a specific profile inside a specific organization. This lets your backend create templates, send envelopes, retrieve completed documents, and manage signing workflows without asking an end user to log in to Verdocs.
### Are API keys tied to users, organizations, or applications? [#are-api-keys-tied-to-users-organizations-or-applications]
API keys are created under a Verdocs profile, and that profile belongs to an organization. In practice, this means an API key acts as a specific user/profile within a specific organization.
For production integrations, we recommend creating a dedicated **API user** or service profile instead of using a personal developer account. This keeps your integration separate from an employee’s personal login and avoids unexpected behavior if that person belongs to multiple organizations or switches their current profile.
**Recommended pattern:**
Your SaaS application
→ Verdocs API key
→ API user / service profile
→ Verdocs organization
### Should I use one API key or one API key per organization? [#should-i-use-one-api-key-or-one-api-key-per-organization]
For a single organization, one API key is often enough.
For a multi-tenant SaaS platform, the recommended pattern is usually:
Parent Verdocs organization
→ Child organization / sub-account for Customer A
→ API key for Customer A workflows
→ Child organization / sub-account for Customer B
→ API key for Customer B workflows
This keeps templates, envelopes, branding, permissions, and usage cleanly separated by customer.
If you create child organizations using the API, the parent organization can establish the parent-child relationship. After that, operations inside the child organization should use credentials/API keys associated with that child organization. The parent token is used to create the relationship, not to perform all future operations inside every sub-account. Your existing organization hierarchy guide already states this, but it should be repeated in this new guide because it directly answers Steve’s question.
### Is there a master API key that can act as any organization? [#is-there-a-master-api-key-that-can-act-as-any-organization]
Generally, no. Verdocs should not be presented as a single global “master key” model where one credential freely impersonates every organization.
*The safer mental model is:* One API key acts as one profile in one organization.
For embedded SaaS platforms, use organization hierarchies to manage parent/child relationships, entitlements, and usage reporting, while using organization-specific credentials for the actual work inside each customer account. The docs already explain that sub-accounts can inherit entitlements and that usage metrics can be retrieved for monitoring and billing.
### Do my signers need Verdocs member accounts? [#do-my-signers-need-verdocs-member-accounts]
No. A person who signs an envelope does **not** need to be a member of your Verdocs organization.
In Verdocs, organization members are people who administer, create, send, or manage workflows inside an organization. Recipients/signers are participants in an envelope. When your application creates an envelope, it supplies the recipient information such as name, email, role, and signing order.
Example:
```typescript
const request = {
template_id,
name: 'Customer Agreement',
roles: [
{ type: 'signer', name: 'Customer', email: 'customer@example.com', sequence: 1 },
{ type: 'signer', name: 'Manager', email: 'manager@example.com', sequence: 2 },
],
};
```
Your current server workflow guide already shows this model: recipients/roles are provided when creating the envelope, and the returned envelope can be used later to retrieve status or final signed documents.
### Can my app send or sign “on behalf of” users? [#can-my-app-send-or-sign-on-behalf-of-users]
Your server can create and send envelopes using its API key. The recipient does **not** need to authenticate into Verdocs as a member of your organization.
You have two common options:
1. \*\*Verdocs-managed notification flow → \*\*Verdocs sends the email or SMS invitation to the recipient.
2. \*\*Application-managed notification flow → \*\*Your application handles the email, SMS, or in-app notification. In this case, create the envelope with `no_contact: true`, then retrieve signing links for the recipients and deliver them through your own app experience.
Your server workflow guide already explains this `no_contact` pattern and shows retrieving signing links for recipients.
# Organization Hierarchies (/docs/guides/tutorials/organization-hierarchies)
Verdocs manages access to features with pass-through fees from other vendors (such as knowledge-based authentication or KBA) via a system of "entitlements." Entitlements make it easy to track access to and usage of these kinds of features across an organization. But for customers managing clients of their own, this can be clumsy because as new organizations are created, these entitlements and usage metrics do not carry over.
Organization Hierarchies can help address this requirement. This feature is currently only available at the API level, but is easy to use. When creating an organization, you may specify that it should be considered a sub-account of your primary organization by setting a "parent\_id" field in the API call:
```bash
curl -X POST https://api.verdocs.com/organizations \
-H "Authorization: Bearer eY........." \
-H "Content-Type: application/json" \
-d '{"name": "New Child Org", "parent_id": "123....." }'
```
As shown in this example, the creation request must set the parent\_id field to the ID of the parent organization, and be accompanied by an access token associated with that same parent organization. This step will establish the relationship between the two.
## Listing Sub-Accounts [#listing-sub-accounts]
Two API endpoint responses are enabled by this step. First, when retrieving a detailed organization record, sub-accounts will be included in a new "children" array as a field in the response. Second, a new API endpoint may retrieve these sub-accounts directly:
```bash
curl -X GET https://api.verdocs.com/organizations/ORGID/children \
-H "Authorization: Bearer eY........." \
-H "Content-Type: application/json"
```
This will retrieve only the sub-accounts, for direct access.
## Updating and deleting sub-accounts [#updating-and-deleting-sub-accounts]
All organization-level operations work on sub-accounts as they would on any other, with two exceptions:
1. After creating the new sub-account, access credentials with ownership rights will be included in the response. Developers must use these new credentials to perform operations at the sub-account level. We recommend immediately creating an API key for the new sub-account to be used to perform subsequent requests. *The access token for the parent organization is valid only for the creation request, not subsequent operations*.
2. Deleting an organization is still a significant operation in the e-Signature industry because of the legal implications of discarding data that may have been related to e-signing activities. Just like with standard organizations, there is currently no automated way to delete a sub-account, but we would be happy to assist you with this. Please contact [support@verdocs.com](mailto:support@verdocs.com) if you need to discuss an automation requirement, or just want to clean up records from development or testing efforts.
## Entitlements [#entitlements]
One of the main advantages of creating sub-accounts is entitlement management. Sub-accounts inherit entitlements from the parent organization. You can thus grant (by establishing a sub-account) or keep separate (by establishing a new top-level organization) your own organization's entitlements to a new one by selectively using this feature.
To assist with monitoring and billing purposes, we have added a new API endpoint to retrieve usage metrics for entitlements:
```bash
curl -X GET https://api.verdocs.com/organizations/ORGID/metrics \
-H "Authorization: Bearer eY........." \
-H "Content-Type: application/json"
```
*NOTE: We will shortly be introducing a number of additional parameters such as date-range and org-level filtering*. *Please refer to our *[*API Browser*](https://developers.verdocs.com/rest-api/api-browser)* for the most up-to-date list of options that may be included in this call.*
This endpoint will return aggregate usage data on a daily and monthly level to support any monitoring or pass-through billing requirements you may have.
# Proxied signing flows (/docs/guides/tutorials/proxied-signing-flows)
In a proxied signing flow, your application completes one recipient's part of an envelope by calling the Verdocs API on their behalf. The recipient still accepts the disclosures, answers each field, adopts a signature, and submits, but they do it through your interface (e.g. a chat conversation, a kiosk screen, or a step in your own app) and never interact with the document in a signing view.
## Where this fits [#where-this-fits]
A proxied flow gives up some of the legal weight of a standard signing session in exchange for a much lighter experience. It is not intended to be used for documents that require strong legal binding by all parties, but may be appropriate in cases where one recipient has a lower level of commitment relative to the others, such as:
* **Accepting a benefit.** The recipient of an insurance payout is simply accepting that payout - the insurer is the party taking on the real obligation. A claims manager or other authorized company representative would still participate normally, but the beneficiary is accepting a check, and the insurer is never going to sue them to make them take it. An AI-assisted chat session, text or email message engagement, mobile app form, or other streamlined interface might be all that's needed to record acceptance, and it benefits the recipient to have a painless experience during a stressful time.
* **Kiosks and shared devices.** A tablet in the lobby of a gym or coworking space asks guests to sign a waiver or a guest agreement. No document needs to be presented - just the terms and an opportunity for the guest to sign their acceptance and Submit.
* **Disclosure / Terms and Conditions Dialogs.** Web and mobile apps often present disclosures and terms in modals or other formats in onboarding flows. The user's acceptance is often little more than a database column or sometimes not stored at all. Courts may not hold users to these agreements because the developer failed to provide an audit trail of the user's interaction with these dialogs, making them useless barriers in some cases, but a full e-signing flow is still overkill for this need. A proxied signing flow can provide that audit trail with just a few API calls.
* **Sign-off on a staff device.** A technician or courier hands their tablet to a customer to confirm the work was done or the delivery arrived.
* **Acknowledgements inside your product.** A signed-in user acknowledges a policy, a handbook, or updated terms from a screen in your app, where your own login already identifies them.
When a recipient is taking on obligations someone may need to enforce later, such as a loan, a lease, or an employment agreement, we recommend a standard signing flow with [recipient authentication](/docs/guides/tutorials/the-recipient-auth-ladder) for that person. Proxied signing is set up per recipient, not per envelope, so one envelope can have a proxied beneficiary followed by a claims manager who signs in the usual Verdocs interface.
## Authentication [#authentication]
In a standard flow, Verdocs establishes who the recipient is. The invitation goes to their email or phone, and the envelope can require a passcode, a one-time code, KBA, or an ID scan before they sign. Developers can set `no_contact` when creating an envelope to disable notifications, but this only changes who is responsible for handling those notifications (to the developer) - the workflow still proceeds in the same way.
A proxied flow replaces the signing user interface with a sequence of API calls. Your application starts the session with an in-person link (NOTE: this makes you responsible for authenticating the recipient). Verdocs records the session as in-person, and our audit trail and signing certificate will show this as an in-person session. The signature details on the certificate (IP address, platform, and device) describe whichever machine made the API calls, which means your server in a chat flow and the tablet in a kiosk flow. Keep your own record of how you identified the recipient, tied to the envelope ID, so you can produce it alongside the certificate.
Leave `auth_methods` empty for a proxied recipient. Since the user will not be directly interacting with Verdocs, we cannot conduct additional authentication steps. If needed, these must be performed by your application.
## Workflow [#workflow]
Your server creates the envelope as usual and requests an in-person link for the proxied recipient. That link's invite code starts a signing session scoped to that one recipient. With the session, you accept the disclosures, fill in the recipient's fields, create and apply their signature and initials, and submit. Webhooks tell your server what happens after that.
The code below uses [`@verdocs/js-sdk`](/docs/reference/SDK/languages/getting-started). If you're working in another language, each step links the REST call behind it.
### 1. Create the envelope [#1-create-the-envelope]
Create the envelope on your server with your API key.
```ts
import {VerdocsEndpoint, authenticate, createEnvelope} from '@verdocs/js-sdk';
const server = new VerdocsEndpoint();
const {access_token} = await authenticate(server, {
grant_type: 'client_credentials',
client_id: process.env.VERDOCS_CLIENT_ID!,
client_secret: process.env.VERDOCS_CLIENT_SECRET!,
});
server.setToken(access_token);
const envelope = await createEnvelope(server, {
template_id: '8e0b...c41a',
name: 'Claim 20931 settlement acceptance',
no_contact: true,
recipients: [
{role_name: 'Beneficiary', first_name: 'Ada', last_name: 'Lovelace', email: 'ada@example.com'},
{role_name: 'Claims Manager', first_name: 'Grace', last_name: 'Hopper', email: 'grace@insurer.example'},
],
});
```
`no_contact` applies to the whole envelope, so choose it with every recipient in mind. With `no_contact: true`, Verdocs sends no email or text to anyone on the envelope, and your application tells each later recipient when it's their turn ([Bring-your-own notification](/docs/guides/tutorials/bring-your-own-notification) covers how). With it off, later recipients get the standard Verdocs invitation and sign in the usual interface, but the proxied recipient also gets an invitation email when their turn arrives, which is immediately if they act first. For a single-recipient kiosk flow, `no_contact: true` is the natural choice.
### 2. Request an in-person link [#2-request-an-in-person-link]
Request the link from your server with the same credentials that created the envelope, because Verdocs issues in-person links only to the envelope's sender. ([Get In-Person Signing Link](/docs/reference/Rest-API/api-docs/recipients/getInPersonLink))
```ts
import {getInPersonLink} from '@verdocs/js-sdk';
const inPerson = await getInPersonLink(server, envelope.id, 'Beneficiary');
inPerson.link; // A Verdocs signing URL ending in /sign///
inPerson.access_key.key; // The invite code from the end of that URL
inPerson.access_token; // A signing session for this recipient
```
The response breaks the link into its parts, so there's no URL to parse. `access_key.key` is the invite code, and `access_token` is a signing session you can use right away when the same process carries on with the signing. When signing happens somewhere else, such as on the kiosk tablet or in a chat worker, send that process only the invite code and start the session there in step 3. Treat the invite code like a password for this recipient on this envelope, and never send your API credentials to a kiosk or a browser.
If the proxied recipient doesn't act first, wait for their turn before you start. The `recipient_invited` webhook fires when it arrives, or `recipient_invite_failed` on a `no_contact` envelope.
### 3. Start the signing session [#3-start-the-signing-session]
Start the session wherever the signing happens, with the envelope ID, role name, and invite code from step 2. It gets its own `VerdocsEndpoint`, separate from the one holding your API session. ([Start Signing Session](/docs/reference/Rest-API/api-docs/recipients/startSigningSession))
```ts
import {VerdocsEndpoint, startSigningSession} from '@verdocs/js-sdk';
// Kiosks are shared, so keep the session out of localStorage
const signer = new VerdocsEndpoint({sessionType: 'signing', persist: false});
const session = await startSigningSession(signer, envelopeId, roleName, inviteCode);
const {envelope, recipient} = session;
```
`startSigningSession` attaches the token to the endpoint for you. To use the `access_token` from step 2 instead, attach it with `signer.setToken(inPerson.access_token, 'signing')`. Make every remaining call with this endpoint: those calls act as the recipient, and submitting through the signing session is what records In-Person Link on the certificate.
A signing session lasts two hours. If a conversation pauses for longer, call `startSigningSession` again with the same invite code to pick up where the recipient left off.
### 4. Accept the disclosures [#4-accept-the-disclosures]
Before anything else, the recipient agrees to do business electronically. Show them the same disclosure text the Verdocs signing interface would, get a clear yes, and send that text with the call. Verdocs stores it with the time of acceptance, and both appear on the certificate. ([Agree to e-Signing Disclosures](/docs/reference/Rest-API/api-docs/recipients/envelopeRecipientAgree))
```ts
import {DEFAULT_DISCLOSURES, envelopeRecipientAgree} from '@verdocs/js-sdk';
const disclosures = session.brand?.disclaimer || envelope.organization?.disclaimer || DEFAULT_DISCLOSURES;
// After the recipient has read and agreed to `disclosures`
const {timeZone, locale} = Intl.DateTimeFormat().resolvedOptions();
await envelopeRecipientAgree(signer, envelopeId, roleName, disclosures, {timezone: timeZone, locale});
```
`DEFAULT_DISCLOSURES` is HTML with links to the full disclosure and our license agreement, so render those links in your interface rather than stripping them. The timezone and locale control how dates appear on the certificate for this recipient. In a chat flow running on your server, send the recipient's own values instead of your server's.
The recipient doesn't see the document in a signing view, but they should still be able to read it. Your server can generate a short-lived link for them to open right away with `getEnvelopeDocumentPreviewLink(server, document.id)` for each entry in `envelope.documents`.
### 5. Fill in the fields [#5-fill-in-the-fields]
The recipient's fields arrive in the session's envelope, sorted in the order they appear on each page. Each one has a `type`, a `label` to prompt with, `required`, and any `value` the sender prefilled.
```ts
import {updateEnvelopeField} from '@verdocs/js-sdk';
const fields = (envelope.fields || []).filter((field) => field.role_name === roleName && !field.readonly);
for (const field of fields) {
if (field.type === 'textbox') {
const answer = await askRecipient(field.label || field.name); // Your chat or kiosk prompt
await updateEnvelopeField(signer, envelopeId, roleName, field.name, answer, false);
} else if (field.type === 'checkbox') {
const checked = await confirmWithRecipient(field.label || field.name);
await updateEnvelopeField(signer, envelopeId, roleName, field.name, String(checked), false);
}
}
```
Leave the last argument, `prepared`, as `false`. The value depends on the field type:
| Field type | Value |
| ------------------- | --------------------------------------------------- |
| `textbox` | The text |
| `checkbox`, `radio` | `"true"` or `"false"` |
| `signature` | A signature block ID (step 6) |
| `initial` | An initials block ID (step 6) |
| `timestamp` | Nothing to send. Verdocs fills it in at submission. |
### 6. Adopt and apply a signature and initials [#6-adopt-and-apply-a-signature-and-initials]
The recipient adopts a signature by approving the image that will appear on the document. Create the signature block once, then apply it to each of their signature fields, and do the same with initials. ([Create Signature Block](/docs/reference/Rest-API/api-docs/signatures-and-initials/createSignature), [Create Initial Block](/docs/reference/Rest-API/api-docs/signatures-and-initials/createInitials))
```ts
import {createInitials, createSignature, fullNameToInitials, updateEnvelopeField} from '@verdocs/js-sdk';
const name = `${recipient.first_name} ${recipient.last_name}`;
const signature = await createSignature(signer, 'signature', await renderTypedName(name));
const initials = await createInitials(signer, 'initial', await renderTypedName(fullNameToInitials(name)));
for (const field of fields) {
if (field.type === 'signature') {
await updateEnvelopeField(signer, envelopeId, roleName, field.name, signature.id, false);
} else if (field.type === 'initial') {
await updateEnvelopeField(signer, envelopeId, roleName, field.name, initials.id!, false);
}
}
```
Both images are PNGs. On a kiosk, let the guest draw on a canvas, or render their typed name in a script font the way the Verdocs signing interface does:
```ts
// Draws a typed name as a transparent PNG. Load the font before calling this.
const renderTypedName = (text: string, width = 300, height = 80) => {
const canvas = document.createElement('canvas');
canvas.width = width;
canvas.height = height;
const context = canvas.getContext('2d')!;
context.font = '40px "Dancing Script"';
context.textAlign = 'center';
context.textBaseline = 'middle';
context.fillText(text, width / 2, height / 2);
return new Promise((resolve) => canvas.toBlob((blob) => resolve(blob!), 'image/png'));
};
```
In a chat flow, show the recipient the rendered image and have them confirm it before you create the block. On a server, any canvas library that outputs a PNG works, wrapped as `new Blob([png], {type: 'image/png'})`.
### 7. Submit [#7-submit]
Submitting finishes the recipient's part. ([Submit envelope](/docs/reference/Rest-API/api-docs/recipients/envelopeRecipientSubmit))
```ts
import {envelopeRecipientSubmit} from '@verdocs/js-sdk';
await envelopeRecipientSubmit(signer, envelopeId, roleName, {timezone: timeZone, locale});
```
Verdocs checks every required field first, and the call fails if any is empty or invalid. Once it succeeds, Verdocs stamps the recipient's fields onto the documents, fills in any timestamps, and moves the envelope to the next recipient. The signing session has nothing left to do, so discard the endpoint (on a kiosk, before the next guest walks up).
If the recipient refuses instead, call `envelopeRecipientDecline(signer, envelopeId, roleName)`. A decline ends the envelope for every recipient, and `recipient_declined` fires.
## Closure and Next Steps [#closure-and-next-steps]
`recipient_submitted` fires as soon as the submission succeeds, and `envelope_completed` fires once every recipient has acted and the signed documents and certificate are ready. In between, the remaining recipients take their turns:
* With `no_contact` off, Verdocs invites the next recipient as usual, `recipient_invited` fires, and they sign in the standard interface.
* With `no_contact: true`, Verdocs sends nothing and fires `recipient_invite_failed` as each recipient's turn arrives. That's your cue to notify them yourself, or to start another proxied session if they're proxied too.
Act on these events from your server rather than relying on the kiosk or chat client to report back. [Webhooks](/docs/reference/Rest-API/webhooks) lists every event, and [Securing your webhooks](/docs/guides/tutorials/securing-your-webhooks-hmac-vs-oauth) covers verifying them.
# Securing Your Webhooks: HMAC vs OAuth (/docs/guides/tutorials/securing-your-webhooks-hmac-vs-oauth)
## The scenario [#the-scenario]
You expose: `POST https://api.yourproduct.com/integrations/verdocs/events. `A third party discovers the endpoint and sends a fake “envelope completed” event. Your backend trusts the payload and closes a deal automatically.
Or your security team mandates OAuth, but your gateway only supports static API-key validation and cannot validate rotating bearer tokens.
This guide focuses specifically on **authenticating inbound webhook requests** from Verdocs to your infrastructure.
It does **not** replace:
* HTTPS/TLS
* idempotency protection
* payload validation
* organization authorization checks
***
## What Verdocs sends on the wire [#what-verdocs-sends-on-the-wire]
Webhook deliveries are typically sent as:
* `POST` requests
* `Content-Type: application/json`
* JSON payloads containing fields such as:
* `id`
* `event`
* `created_at`
* `organization_id`
* `data`
Always treat the Webhooks reference as the source of truth for exact payload structures and field names.
### Delivery expectations [#delivery-expectations]
Webhook handlers should respond quickly - typically within a few seconds.
Long-running tasks should be queued asynchronously after validation succeeds. Your endpoint should acknowledge receipt with a `2xx` response once the request has been authenticated and accepted.
Do not block the response while downstream systems finish processing.
***
## Option A - HMAC (shared secret) [#option-a---hmac-shared-secret]
### Mental model [#mental-model]
Verdocs and your application share a secret. Each webhook delivery includes a cryptographic signature derived from the payload. Your server recomputes the signature and verifies it matches. If an attacker does not know the secret, they cannot forge a valid request.
***
### Configuration [#configuration]
In the Verdocs webhook configuration:
* choose the HMAC authentication method
* configure a shared secret
Store the same secret securely in your own infrastructure.
***
### Verification flow [#verification-flow]
#### 1. Read the raw request body [#1-read-the-raw-request-body]
Read the request payload before modifying or reparsing it. Many integrations accidentally break verification by changing whitespace or serialization order before hashing.
#### 2. Read the signature header [#2-read-the-signature-header]
Verdocs sends a signature in: `x-webhook-signature`.
#### 3. Recompute the HMAC [#3-recompute-the-hmac]
Use the documented signing algorithm (currently SHA-256 for modern integrations).
#### 4. Compare securely [#4-compare-securely]
Use a constant-time comparison function to avoid timing attacks.
Reject requests when:
* the header is missing
* the signature does not match
* the payload is malformed
***
### Important implementation detail [#important-implementation-detail]
The signature is tied to the event payload Verdocs defines in the webhook contract - not necessarily the entire outer request wrapper.
Always implement verification against the exact signing input documented in the Webhooks reference. If your computed hash disagrees with the reference behavior, the reference documentation is the contract.
***
### Operational guidance [#operational-guidance]
#### Rotate secrets periodically [#rotate-secrets-periodically]
Use the documented secret rotation workflow and coordinate deployment timing carefully.
#### Treat secrets like passwords [#treat-secrets-like-passwords]
Never log secrets, commit them to source control, or expose them client-side
***
### When HMAC fits well [#when-hmac-fits-well]
HMAC is usually a good fit when:
* your deployment model is simple
* you want minimal infrastructure dependencies
* you do not already operate OAuth token issuance infrastructure
* your gateways validate static secrets more easily than bearer tokens
***
## Option B - OAuth client credentials [#option-b---oauth-client-credentials]
### Mental model [#mental-model-1]
Verdocs acts as an OAuth client to your authorization server. Before sending webhooks, Verdocs requests an access token using the `client_credentials` grant.
Verdocs then calls your webhook endpoint using: `Authorization: Bearer <token>`
***
### Configuration [#configuration-1]
Webhook settings include:
| Field | Purpose |
| ---------------- | ----------------------------------------------- |
| `token_endpoint` | Your OAuth token endpoint |
| `client_id` | OAuth client ID issued to Verdocs |
| `client_secret` | OAuth client secret issued to Verdocs |
| `scope` | Optional scope value if required by your issuer |
The token request is typically sent as: `application/x-www-form-urlencoded`, using: `grant_type=client_credentials`.
Always confirm exact token request behavior against the current Webhooks reference if your OAuth provider has strict requirements.
***
### Verification flow [#verification-flow-1]
#### 1. Validate the bearer token [#1-validate-the-bearer-token]
Use your normal API token validation path:
* JWT signature verification
* token introspection
* API gateway enforcement
* opaque token lookup
#### 2. Verify audience or scope [#2-verify-audience-or-scope]
Ensure the token is intended for:
* the correct API
* the correct route
* the expected integration audience
#### 3. Reject invalid requests [#3-reject-invalid-requests]
Reject requests with:
* missing authorization headers
* expired tokens
* invalid signatures
* insufficient scopes
***
### Token reuse behavior [#token-reuse-behavior]
Verdocs may reuse tokens until expiration if your token response includes standard expiry metadata such as:
* `expires_in`
* `exp`
Short-lived access tokens are recommended for webhook integrations.
Very long-lived bearer tokens reduce the security benefits of OAuth mode.
***
### When OAuth fits well [#when-oauth-fits-well]
OAuth is often preferred when:
* your organization already standardizes on OAuth2
* security teams require centralized token issuance and auditing
* your API platform already validates JWTs or opaque bearer tokens
* you need audience, scope, or claims-based authorization
***
## Choosing between them [#choosing-between-them]
| Question | Better fit |
| ------------------------------------------------ | ---------- |
| Do we already issue OAuth clients to partners? | OAuth |
| Do we want the simplest implementation possible? | HMAC |
| Does our gateway only understand static secrets? | HMAC |
| Do we require aud/scope-based authorization? | OAuth |
Many teams start with HMAC and later migrate to OAuth as platform maturity increases.
Both are supported webhook authentication patterns.
***
## “None” is technically possible (but risky) [#none-is-technically-possible-but-risky]
Some environments permit webhook endpoints with no additional authentication beyond HTTPS.
That may be acceptable for temporary development tunnels or local testing.
For production systems, assume URLs eventually leak and enable either:
* HMAC authentication
* OAuth authentication
***
## Commonly asked questions [#commonly-asked-questions]
### Should we validate `organization_id`? [#should-we-validate-organization_id]
Yes. Authentication proves who sent the request. Your application still needs authorization logic to ensure the event belongs to a recognized tenant or customer.
***
### Is IP allowlisting enough? [#is-ip-allowlisting-enough]
IP allowlists should be treated as defense in depth, not the primary security mechanism. Cryptographic verification and bearer-token validation fail closed much more reliably.
***
### Should webhook handlers be idempotent? [#should-webhook-handlers-be-idempotent]
Strongly recommended. Retries and duplicate deliveries can occur. Use the webhook `id` or another stable event identifier to deduplicate processing.
***
### Can we subscribe to only certain events? [#can-we-subscribe-to-only-certain-events]
Yes. Webhook configurations allow selecting specific event types. In production, subscribing narrowly reduces load and operational surprises.
***
## Takeaway [#takeaway]
* **HMAC** uses a shared secret and request signature verification. It is operationally simple and works well for straightforward deployments.
* **OAuth client credentials** uses short-lived bearer tokens issued by your authorization server. It fits best when OAuth is already your organization’s standard for machine-to-machine authentication.
Both approaches secure inbound webhook traffic effectively when implemented correctly.
**Learn More:** [Webhooks](https://developers.verdocs.com/docs/reference/Rest-API/webhooks) · [Web SDK v6.6.0 - webhook authentication](https://developers.verdocs.com/docs/learn/whats-new/web-sdk-v6-6-0)
# Send an envelope without a template (/docs/guides/tutorials/send-an-envelope-without-a-template)
**Goal:** Create and send a signing envelope when you already have a PDF (or DOCX) and do **not** want to create a Verdocs template first.
**Who this is for:** Backend engineers automating one-off agreements, generated documents, or workflows where the PDF is produced by your own system.
**What you will use:** The same **Create Envelope** capability you use with templates - omit `template_id` and supply the document another way. Official parameters and edge cases always live in the Create Envelope REST reference and the JS/TS SDK if you call Verdocs from Node or the browser.
***
## When this pattern fits [#when-this-pattern-fits]
Use this approach when:
* Your app already has the final (or near-final) PDF, or a DOCX you convert through Verdocs-supported upload paths.
* You do not need a reusable template in the Verdocs UI for this document family.
* You are comfortable defining recipients (and optional fields) in the create request, or relying on tags inside the PDF for field placement.
If you send the same agreement shape repeatedly and non-technical users edit it in Verdocs, a template-based workflow is usually the better fit.
***
## Prerequisites [#prerequisites]
### 1. Organization automation identity [#1-organization-automation-identity]
A profile and API key (or OAuth client credentials) your server uses to call Verdocs, scoped to the correct organization.
If API results seem inconsistent between environments or users, review the “Understanding Profiles” guide.
### 2. Authentication [#2-authentication]
Obtain a bearer access token using your existing authentication flow.
### 3. A document [#3-a-document]
Typically a PDF, or a DOCX Verdocs can convert during upload.
Check the Create Envelope reference for supported MIME types, filename expectations, and account-specific limits.
***
## The idea in one sentence [#the-idea-in-one-sentence]
If you do not send `template_id`, you must send a `name` and at least one entry in `documents`.
Recipients are still required, just like any other envelope workflow. Verdocs creates the envelope, attaches your file(s), wires recipients, and derives fields from your request and/or PDF tags - without creating a saved template record first.
***
## Step 1 - Shape the JSON body [#step-1---shape-the-json-body]
### Core fields [#core-fields]
| Field | Required without template? | Notes |
| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
| `name` | Yes | Envelope title users see in the UI. |
| `template_id` | No | Omit it entirely for this workflow. |
| `documents` | Yes | Array of uploaded or referenced documents. |
| `recipients` | Yes | At least one signer or participant. Recipient email addresses must be unique within the envelope. |
| `fields` | Usually optional | Include if you place fields via API instead of PDF tags. |
| `no_contact` | Optional | Set to `true` if your app - not Verdocs - delivers signing links. |
Optional envelope-level settings such as reminders, expiration, or visibility are documented in the Create Envelope reference.
***
## Step 2 - Attach the PDF (or DOCX) [#step-2---attach-the-pdf-or-docx]
Each entry in `documents` supplies a file using one of the supported methods.
### Option 1: Base64 data [#option-1-base64-data]
Provide:
* `data`
* `mime`
* `name`
This is the easiest option for scripts and server-generated PDFs, but large files can increase request size significantly.
### Option 2: HTTPS URI [#option-2-https-uri]
Provide:
* `uri`
* `name`
Verdocs fetches the file from your HTTPS endpoint or signed CDN URL. HTTP URLs are rejected.
### Option 3: Multipart upload [#option-3-multipart-upload]
Some integrations upload files as multipart form data alongside the JSON payload. Use the exact field names and request structure documented for your SDK or REST version.
### DOCX conversion [#docx-conversion]
If you upload a DOCX, Verdocs converts it to PDF during ingestion. Always verify supported MIME types and conversion behavior in the latest API reference.
### Multiple documents [#multiple-documents]
If the envelope contains multiple files, set `order` on each document to keep rendering and signing behavior deterministic.
***
## Step 3 - Define recipients [#step-3---define-recipients]
Recipients should include the fields your workflow expects, typically:
* `role_name`
* `type`
* `first_name`
* `last_name`
* `email`
Use `sequence` (or `order`, depending on API version) to control routing order for multiple signers.
If you plan to use KBA, passcodes, or other verification methods, additional authentication fields may be required. For a first integration, it is usually easier to validate the basic signing flow before enabling advanced recipient authentication.
***
## Step 4 - Call Create Envelope [#step-4---call-create-envelope]
### Request basics [#request-basics]
* Method: `POST`
* Authentication: `Authorization: Bearer <access_token>`
* Content type: `application/json` for JSON-only requests
### Example request shape (base64 upload) [#example-request-shape-base64-upload]
```
{
"name": "Order form - Acme Corp",
"no_contact": false,
"documents": [
{
"name": "OrderForm.pdf",
"mime": "application/pdf",
"data": "",
"order": 1
}
],
"recipients": [
{
"role_name": "Customer",
"type": "signer",
"first_name": "Jane",
"last_name": "Signer",
"email": "jane.signer@example.com",
"sequence": 1
}
]
}
```
### Example request shape (HTTPS URL) [#example-request-shape-https-url]
```
{
"name": "Order form - Acme Corp",
"documents": [
{
"name": "OrderForm.pdf",
"uri": "https://cdn.example.com/contracts/abc123.pdf",
"order": 1
}
],
"recipients": [
{
"role_name": "Customer",
"type": "signer",
"first_name": "Jane",
"last_name": "Signer",
"email": "jane.signer@example.com",
"sequence": 1
}
]
}
```
On success, Verdocs returns an envelope object your integration can persist, typically including at least the envelope `id` and current `status`.
***
## Step 5 - What happens next [#step-5---what-happens-next]
After creation:
* Verdocs processes uploads asynchronously (conversion, previews, tag detection, and field extraction).
* Your integration can either:
* poll Get Envelope Details until the envelope is ready, or
* subscribe to webhooks for lifecycle updates.
### Contact behavior [#contact-behavior]
If `no_contact` is `false`, Verdocs sends recipient invitations automatically according to product workflow rules.
If `no_contact` is `true`, your application is responsible for retrieving and delivering signing links or starting signing sessions directly.
***
## Troubleshooting [#troubleshooting]
| Symptom | Things to check |
| ------------------------------ | ------------------------------------------------------------------------------------- |
| 400 on create | Missing `name` or `documents`; duplicate recipient emails; invalid expiration values. |
| Rejected `uri` | URL must use HTTPS and be reachable from Verdocs infrastructure. |
| “Recipient missing first/last” | Each recipient requires `first_name` and `last_name`. |
| Fields missing | Either provide `fields` explicitly or include valid PDF tags. |
***
## In summary [#in-summary]
To send an envelope without a template:
1. Omit `template_id`
2. Provide `name`
3. Attach one or more `documents`
4. Include `recipients`
The result is the same envelope workflow used by template-based sends - without maintaining a reusable template in Verdocs first.
**Primary Links:** [Create Envelope](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/envelopes/createEnvelope) · [Get envelope details](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/envelopes/getEnvelope) · [Tagging Dynamic Documents](https://developers.verdocs.com/docs/guides/tutorials/tagging-dynamic-documents) · [Understanding Profiles](https://developers.verdocs.com/docs/guides/tutorials/understanding-profiles-or-why-do-my-api-calls-return-the-wrong-data)
# Server Workflow with Static Templates (/docs/guides/tutorials/server-workflow-with-static-templates)
This workflow is the simplest use-case, and is the recommended place to start when building an e-Signing experience using Verdocs.
## Create a free account [#create-a-free-account]
Access to Verdocs is broken down into two components that work together to control who can create, edit, and use templates in signing requests:
* \*\*Organizations \*\*represent groups of user profiles, and manage the permissions and features those users have within the system.
* \*\*Profiles \*\*represent an individual user within an organization. Note that a person may be a member of more than one organization.
When creating an account, both a profile and organization will be created at the same time. The first profile will automatically be granted Owner-level access within that organization.
Get started by creating an account at [app.verdocs.com](https://app.verdocs.com).
## Basic terminology [#basic-terminology]
In addition to organizations and profiles, it is helpful to understand a few additional terms that will be used in the workflow:
* **Templates** are reusable collections of documents, fields, and roles that can be used within a signing flow. For example, a purchase agreement might have the bill of sale document, signature and date fields, and roles defined as Buyer and Seller.
* **Envelopes** are individual instances of templates. For the above purchase agreement, one envelope might be John buying a motorcycle from Sally, and another might be Richard buying an excavator from Jason.
* **Roles** are individual instances of templates. For the above purchase agreement, one envelope might be John buying a motorcycle from Sally, and another might be Richard buying an excavator from Jason.
* \*\*Recipients \*\*are pre-defined participants in a template, such as Buyer or Seller. A role MAY be pre-defined (e.g. an Officer Manager or company officer might be known ahead of time) but this is not required).
## Create a Template [#create-a-template]
After creating an account, you will be taken to a dashboard without any content created yet. Click New Template to get started:
This will present a wizard that walks you through the template creation process. At a minimum, you should:
1. Select and upload a PDF file to use as the first document to be signed.
2. On the next tab, add at least one role by clicking the (+) button. You can drag roles up to down to set the order in which they will act while signing. Roles that are on the same line (at the same sequence) will act in parallel, and will receive invites at the same time. Roles on separate lines will act in series, and will not receive invites until all previous participants have completed their steps.
3. Add at least one field on the Fields tab. NOTE: For a template to be "sendable", it must contain
4. At least one role, and
5. Every role must have at least one field assigned.
If you would like to test the template, navigate to the Preview tab. You can send the template to yourself manually from there to verify it is working as expected.
## Send an envelope programmatically [#send-an-envelope-programmatically]
To send copies of that template programmatically, you will first need to create an API key. To do this, navigate to Settings->API Keys, and click \[Create Key]. Copy the Client ID and Secret from this dialog into your code.
Create a simple project as follows:
```bash
md verdocs-quickstart
cd verdocs-quickstart
npm init (accept all the defaults)
npm i -S @verdocs/js-sdk
```
You will also need the template ID, which you can get from the URL bar of your browser while previewing it.
The following code will then create and send an envelope using your account:
`import { createEnvelope, authenticateApp } from '@verdocs/js-sdk';`
```typescript
const client_id = 'REPLACE_ME';
const client_secret = 'REPLACE_ME';
const template_id = 'REPLACE_ME';
```
\`async function runMe() \{
await authenticateApp(VerdocsEndpoint.getDefault(), \{ client\_id, client\_secret });
const request: ICreateEnvelopeRequest = \{
template\_id,
name: '51 Academy Ln, Apt. 2 Lease Agreement, 5/1/24 - 4/30/25',
roles: \[
\{ type: 'signer', name: 'Lessee1', email: '[lessee@nomail.com](mailto:lessee@nomail.com)', sequence: 1 },
\{ type: 'signer', name: 'LeasingAgent', email: '[agent@nomail.com](mailto:agent@nomail.com)', sequence: 2 },
],
};
const envelope = await createEnvelope(VerdocsEndpoint.getDefault(), request);
console.log(envelope); // \<-- Will contain all metadata for the newly-created envelope
}
\`
That's all there is to it! The response from createEnvelope will include all of the metadata required to work with the envelope again in the future. The most important field is its id, so you may want to record this in your own database. The envelope ID may be used in future calls to retrieve that envelope's status, cancel it, or retrieve its final, signed document attachments.
## Self-managed email and other contact methods [#self-managed-email-and-other-contact-methods]
Using the above workflow, Verdocs will automatically invite users to sign documents via email or SMS invitations, depending on the values you supply when creating the envelope. If you want to handle communications yourself, to customize the email template and/or the entire signing experience, include no\_contact in the call:
\`import \{ getInPersonLink } from '@verdocs/js-sdk';
Include no\_contact in the request:
const request: ICreateEnvelopeRequest = \{
... other fields as illustrated above
no\_contact: true
};
const envelope = await createEnvelope(VerdocsEndpoint.getDefault(), request);
// Get signing links for all recipients
for await let (recipient of envelope.recipients) \{
const link = await getInPersonLink(VerdocsEndpoint.getDefault(), envelope.id, recipient.role\_name);
console.log(link); // \<-- Will contain a URL that you may email to the recipient to sign the document
}
\`
# Tagging Dynamic Documents (/docs/guides/tutorials/tagging-dynamic-documents)
Some types of documents may not be suitable for working with in a graphical "template builder", particularly:
* Dynamic documents that are generated programmatically in back-end systems, where the fields needed, and their locations, may change based on business logic, or
* One-off documents that are generated and used only for a single signing operation, where a manual process for placing and defining fields is not wanted.
In these cases, developers may embed "tags" in both Word (DOCX) and PDF files to identify where signing fields should be placed and managed by Verdocs. Tags are defined using a Handlebars-style format as follows:
`{{fieldtype:"RoleName";option1;option2...}}`
## Field types [#field-types]
The following field types are supported:
* **attachment**: A file attachment, to be uploaded by the user
* **checkbox**: A single check-box that may be selected or deselected. Check boxes may be "grouped", and will appear in output metadata as an array of the values that were selected.
* **date:** A date. When clicked, a date picker will be presented to the user.
* **dropdown**: A drop-down box.
* **initial**: An initial-here field.
* **radio**: A radio button. Radio buttons act like check boxes, but only one option in a group may be selected at a time.
* **signature**: A sign-here field.
* **textbox**: A text input field. If the default size is used, will be presented as a single-line field. Increase the
height to allow multiple lines to be entered.
* **timestamp**: A date/time stamp that will be automatically filled in when the user submits the document.
## Roles [#roles]
All fields must be assigned to a "role". Roles are defined by you (the user or developer) and are usually generic names such as "Buyer", "Leasing Agent," or even as simple as "Recipient 1". Role names can be anything you want, but keep the following rules in mind:
1. Role names must be between 3 and 30 characters long.
2. Simpler names are better. Role names become the IDs used later in metadata to identify the values used fill in for a document's fields. It may be easier to write code to look for `"submittedData.OfficeMgr"` than `"submittedData['Assistant to the President']"`.
3. Role names are case-sensitive and must be unique. Be sure to be consistent and avoid confusion with terms such as using "officemgr" in one field and "OfficeMgr" in another.
## Field options [#field-options]
All fields share a common set of options. Options are separated by semicolons. Where options require parameters, they are delimited with colons. For example:
`opt;w:150`
indicates a field that is required (r) and has a width of 150.
Most options may be specified inline, with no additional delimiters. However, where special characters such as spaces or punctuation are included, they may be enclosed in double-quotes. **NOTE: When producing templates in Word/DOCX format, be sure to disable "Smart Quotes" for these markers!**
`p:"Enter your full name";w:150`
The following options are available for most fields:
* **opt**: By default, fields are required. If this flag is included, the field will be optional.
* **w**: Set the width of the field (PDFs are typically 72dpi so a field with a width of 150 is typically \~2" in effective print width).
* **h**: Set the height of the field.
* **n**: Set the name of the field. If a name is not supplied, a system-generated name will be created and user-submitted data will still be available in the submittedData collection once signing is complete. For signature, initial, and timestamp fields, most apps rarely access the submitted data anyway and a name is not generally useful. However, it is generally recommended to include names for user input fields such as dates, textboxes and textareas.
* **p**: Set the "placeholder" for the field. This text will be displayed until the user enters a value in the field as a hint for what they are expected to enter (e.g. "Enter your full name").
* **d**:Set the "default" value for the field.
* **k**: Set your data key for the field's value, such as `k:applicant.full_name`. Fields that show the same value can share a key, and the key comes back on the envelope's fields and in webhooks.
Note that some fields have exceptions, specifically:
* Signature and initial fields have fixed widths and heights, and w/h options will be ignored.
* **group** applies only to checkboxes and radio buttons, and will be ignored for other fields.
* **options** applies only to dropdowns.
* **value** applies only to radio buttons.
* **p** applies only to textbox and textarea fields.
* **d** applies only to textbox, textarea, checkbox, dropdown, and radio fields.
* **k** applies only to textbox, textarea, date, checkbox, dropdown, and radio fields.
## Placing fields [#placing-fields]
Tags should generally be written in-line, in the places where signature fields belong in the final document. Most fields are small, and generally line up well with "typical" document formats and styles. When tags are detected, a signature field will be placed in each tag's location, and the tags will be redacted from the source document.
A common confusion when working with source documents is that most editors (e.g. Microsoft Word) work from the top down (0,0 is the top-left corner of a page). Final page layouts are not determined until a document is printed, or converted to a print-compatible format such as PDF. In contrast, for historical reasons, PDF documents are laid out from the bottom up (0,0 is the bottom-left corner of a page). Therefore, when adding white-space around tags to leave room for them in a final document, be sure to place the tag in the bottom of the empty space, as shown with this textarea field for the Buyer's Address:
Be sure to leave enough space for large fields, such as textareas.
## Alternative definition method [#alternative-definition-method]
Defining fields inline using the above tags is the fastest and most streamlined option, but fields with many options may interfere with creating an elegant template in Word or other editors. In this case, you may use a simplified tag definition, referring to the tag by its unique ID, e.g. `{{Buyer-Address}}` or even `{{F1}}`.
When using this syntax, you must follow a few additional rules:
* Field names must be unique
* Field names must be between 2-30 characters, begin with a letter, and consist only of alphanumeric characters, dashes, and spaces.
* Spaces are allowed, but not recommended. Some API calls that include role names as a parameter will require URL-encoding these, e.g. a field named "Buyer Address" would need to be referred to as "Buyer Address").
Finally, when fields are specified in this way, you must include an additional fields definition array in API calls to create templates and envelopes using these documents, to provide the types and other options to assign to these fields.
# Template Changes and Sent Envelopes (/docs/guides/tutorials/template-changes-and-sent-envelopes)
Updating a template in Verdocs does not affect envelopes already sent. Each new envelope receives its own envelope documents, envelope fields, and recipient records. Later template edits do not replace the documents or field definitions in those sent envelopes.
## How templates and envelopes relate [#how-templates-and-envelopes-relate]
A template defines a reusable signing workflow: its documents, field placements, and roles. An envelope is an individual signing transaction, with its own documents, fields, recipients, and status.
Roles describe participants in the template, such as Buyer or Seller. Recipients are the participants for a particular envelope. Each EnvelopeField belongs to an EnvelopeDocument and identifies its recipient by role name.
When an envelope is created from a template, the distinction is:
| Resource | Relationship to the envelope |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Documents | The envelope receives its own envelope documents. |
| Fields | The envelope receives its own envelope fields. |
| Recipients | The envelope has its own recipient records for the transaction. |
| Roles | Roles stay on the template. Each recipient and envelope field stores its own copy of the role name, so renaming or deleting a template role later doesn't change envelopes already sent. |
The envelope's relationship to its source template does not make its documents and fields a live view of that template. Editing the template does not synchronize those edits into envelopes already sent.
## Example: updating a service agreement [#example-updating-a-service-agreement]
[Suppose you create and send an envelope](/docs/reference/Rest-API/api-docs/envelopes/createEnvelope) from a service agreement template. You then replace the template's agreement document and move a signature field.
The sent envelope keeps its own agreement document and signature field placement. A new envelope created from the updated template uses the revised template documents and fields. You can therefore update the template for future transactions without changing the documents and fields in the envelope you already sent.
## What this means for integrations [#what-this-means-for-integrations]
Use template edits to prepare future envelopes. If a document or field needs to change for a transaction already sent, editing the source template will not apply that correction to the existing envelope.
Sent envelopes can't be amended, either. [Update Envelope](/docs/reference/Rest-API/api-docs/envelopes/updateEnvelope) changes metadata such as the name, reminders, and expiration, but not documents, fields, or recipients. To correct a wrong document, field, or role assignment, [cancel the envelope](/docs/reference/Rest-API/api-docs/envelopes/resetEnvelope) and send a new one from the corrected template.
Deleting a template doesn't affect envelopes already sent. The envelope's `template_id` is cleared, and its documents, fields, and recipients stay intact.
When [retrieving an existing transaction](/docs/reference/Rest-API/api-docs/envelopes/getEnvelope), use its [envelope documents](/docs/reference/Rest-API/api-docs/envelope-documents/getEnvelopeDocument) and fields rather than reconstructing it from the current template. The template may have changed since that envelope was created.
This behavior describes the effect of **template edits**. An envelope still progresses through its own signing workflow, including recipients entering field values and completing their actions.
For a step-by-step implementation, see [Server Workflow with Static Templates](/docs/guides/tutorials/server-workflow-with-static-templates). For related concepts, see the [Templates & Documents FAQ](/docs/learn/FAQ#templates--documents) and the [REST API reference](/docs/reference/Rest-API).
# Testing KBA with the Sandbox (/docs/guides/tutorials/testing-kba-with-the-sandbox)
Knowledge-based authentication (KBA) is hard to test. Every attempt is a paid lookup against a third-party identity provider, the questions are generated from real public records, and they change every session. None of that is something you can assert on in CI.
The **KBA sandbox** replaces the identity provider with a deterministic stand-in, for organizations you set aside for testing. Nothing else changes: you call the same [Verify Signer](/docs/reference/Rest-API/api-docs/recipients/verifySigner) endpoint, the recipient moves through the same auth states, and failures produce the same errors and webhooks they would in production.
You choose the outcome per request with `sandbox_test_type`:
KBA completes immediately. No questions are asked.
KBA fails immediately, as if the identity provider couldn't find the person.
Four questions with known answers, graded by the sandbox.
***
## How a request is routed [#how-a-request-is-routed]
A KBA attempt runs in the sandbox only when **both** of these are true:
1. The organization has the `kba_sandbox` entitlement.
2. The signer submits the sandbox identity.
`sandbox_test_type` on the same request then picks the scenario. Everything else is rejected before anything is sent to the identity provider:
Routing for the identity step. When the sandbox asks questions, it grades the answers too.
Both `400`s are deliberate guard rails:
| Situation | Response | Why |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `sandbox_test_type` sent, but the organization doesn't have the sandbox | `400` "The KBA sandbox is not enabled for this organization." | A misconfigured test fails fast instead of running a real lookup with a fake identity. |
| The organization has the sandbox, but the signer submits any other identity | `400` "This organization is in KBA sandbox mode. Use the sandbox identity to test KBA." | A test organization can never run a real person through KBA. |
***
## Enable the sandbox [#enable-the-sandbox]
`kba_sandbox` is an organization [entitlement](/docs/guides/tutorials/entitlements). Verdocs grants it on request: contact your account team or [support@verdocs.com](mailto:support@verdocs.com). It's never included in a subscription, so it can't be switched on by accident.
Once an organization has the sandbox, **every** KBA signer in it must use the sandbox identity, and real signers are turned away. Don't enable it on an organization that sends real envelopes.
***
## The sandbox identity [#the-sandbox-identity]
The signer must submit these values exactly. The match is case-sensitive, and all seven fields are required.
| Field | Value |
| ------------ | ------------------- |
| `first_name` | `VERDOCS` |
| `last_name` | `SANDBOX` |
| `address` | `888 TURNKEY DRIVE` |
| `city` | `NYC` |
| `state` | `NY` |
| `zip` | `99999` |
| `dob` | `01/13/1982` |
***
## Walkthrough [#walkthrough]
### Create an envelope with a KBA recipient [#create-an-envelope-with-a-kba-recipient]
Create the envelope as usual with [Create Envelope](/docs/reference/Rest-API/api-docs/envelopes/createEnvelope), and add `kba` to the recipient's `auth_methods`:
```json
{
"role_name": "Signer",
"first_name": "Verdocs",
"last_name": "Sandbox",
"email": "kba-tests@example.com",
"auth_methods": ["kba"]
}
```
### Start a signing session [#start-a-signing-session]
Start a session for the recipient with [Start Signing Session](/docs/reference/Rest-API/api-docs/recipients/startSigningSession), and keep the `access_token` from the response. Every call below uses it as the bearer token, not your API key.
### Submit the sandbox identity [#submit-the-sandbox-identity]
Send the identity with the scenario you want. Leave out `sandbox_test_type` to get `questions`.
```bash
curl -X POST https://api.verdocs.com/v2/sign/verify \
-H "Authorization: Bearer $SIGNING_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"auth_method": "kba",
"first_name": "VERDOCS",
"last_name": "SANDBOX",
"address": "888 TURNKEY DRIVE",
"city": "NYC",
"state": "NY",
"zip": "99999",
"dob": "01/13/1982",
"sandbox_test_type": "questions"
}'
```
```typescript
import {verifySigner} from '@verdocs/js-sdk';
// `endpoint` is a VerdocsEndpoint holding the signing session token
const session = await verifySigner(endpoint, {
auth_method: 'kba',
first_name: 'VERDOCS',
last_name: 'SANDBOX',
address: '888 TURNKEY DRIVE',
city: 'NYC',
state: 'NY',
zip: '99999',
dob: '01/13/1982',
sandbox_test_type: 'questions',
});
```
The response is the usual signing session payload. Read the outcome from `recipient.auth_method_states.kba`. For `pass` and `fail` you're done here: see the [scenario reference](#scenario-reference).
### Answer the questions [#answer-the-questions]
For `questions`, `recipient.kba_questions` holds four questions. Each one tells you its answer:
```json
[
{"type": "sandbox.question.1", "prompt": "The correct answer is 1", "answer": ["1", "2", "3", "4"]},
{"type": "sandbox.question.2", "prompt": "The correct answer is 2", "answer": ["1", "2", "3", "4"]},
{"type": "sandbox.question.3", "prompt": "The correct answer is 3", "answer": ["1", "2", "3", "4"]},
{"type": "sandbox.question.4", "prompt": "The correct answer is 4", "answer": ["1", "2", "3", "4"]}
]
```
Answer all four in one request, pairing each `type` with the option you pick:
```bash
curl -X POST https://api.verdocs.com/v2/sign/verify \
-H "Authorization: Bearer $SIGNING_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"auth_method": "kba",
"responses": [
{"type": "sandbox.question.1", "answer": "1"},
{"type": "sandbox.question.2", "answer": "2"},
{"type": "sandbox.question.3", "answer": "3"},
{"type": "sandbox.question.4", "answer": "4"}
]
}'
```
To test a failure, change any one answer.
***
## Scenario reference [#scenario-reference]
**Identity step**
| `sandbox_test_type` | Response | `auth_method_states.kba` |
| ------------------------ | ------------------------------------------------------------------------ | ------------------------ |
| `pass` | `200` signing session | `complete` |
| `fail` | `400` "Authentication failed. Please contact the sender for assistance." | `failed` |
| `questions` (or omitted) | `200` signing session, with four `kba_questions` | `questions` |
| Anything else | `400` validation error | Unchanged |
**Answers step** (`questions` only)
| Answers | Response | `auth_method_states.kba` |
| ---------------------------------------------- | ------------------------------------------------------------------------ | ------------------------ |
| All four correct | `200` signing session | `complete` |
| Any answer wrong | `400` "Authentication failed. Please contact the sender for assistance." | `failed` |
| Fewer than four, or a `type` that wasn't asked | `400` "Please answer every question." | Unchanged: answer again |
A failure marks the recipient failed and fires the `recipient_auth_fail` webhook, exactly as a real KBA failure does (see [The Recipient Auth Ladder](/docs/guides/tutorials/the-recipient-auth-ladder)).
***
## Things to know [#things-to-know]
* **The identity provider is never called.** Sandbox attempts don't leave Verdocs, so they have no lookup cost and always behave the same way.
* **`complete` and `failed` are final, as in production.** A failed recipient can't retry. Use a fresh envelope per test case, or [reset the envelope](/docs/reference/Rest-API/api-docs/envelopes/resetEnvelope), which clears every recipient's auth state.
* **Grading is stricter than production.** Any wrong answer fails, whereas production may allow a few. Don't use the sandbox to test pass thresholds.
* **The 24-hour window still applies.** KBA must be completed within 24 hours of starting it, as in production.
* **There's no differentiator step.** Production KBA can occasionally ask one extra question to tell people with similar records apart before the main questions. The sandbox goes straight to its four questions.
# The Recipient Auth Ladder (/docs/guides/tutorials/the-recipient-auth-ladder)
## What “auth methods” actually means here [#what-auth-methods-actually-means-here]
Think of `auth_methods` as a **checklist of gates** the recipient must clear before they are allowed to treat the session as a normal signing flow. Verdocs does **not** run them in “whatever order the JSON happened to serialize.” It applies a **single, platform-defined sequence** every time.
That order is fixed so behavior stays consistent for your app, for signers, and for support. Reordering the array in your request does not reorder the gates.
### Rough ladder (first incomplete method wins) [#rough-ladder-first-incomplete-method-wins]
| Order | Method | What “next” usually looks like |
| ----- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1 | **Passcode** | Recipient must satisfy the passcode step (see `auth_step` and related state on the recipient) before anything below is considered. |
| 2 | **Email** | OTP-style flow: a verification window, optional resend, then validating a short-lived code. |
| 3 | **SMS** | Same overall shape as email in the product model. Confirm in your environment and contract before you promise SMS in customer-facing copy - capabilities can differ by rollout or configuration. |
| 4 | **KBA** | Identity verification: collect required identity fields, then challenge questions or follow-up steps from the provider, then complete or fail. |
| 5 | **ID** | Additional identity verification where enabled. Treat as optional until your account team confirms it is supported for your use case. |
If a method is **not** in `auth_methods`, it is skipped. If it **is** included, earlier methods must reach **`complete`** (or equivalent) before later ones are even considered.
***
## Failure is a full stop (by design) [#failure-is-a-full-stop-by-design]
If **any** configured method’s state becomes **`failed`**, the recipient cannot continue. The API returns a clear error asking them to contact the sender, and a **`recipient_auth_fail`** webhook is available so your backend can react (pause CRM state, alert ops, and so on).
For some methods, repeated wrong answers eventually mark the method failed and may notify the sender - not on every single wrong keystroke. That pattern reduces noise and lowers the risk of a malicious signer spamming your sender’s inbox.
***
## Where the ladder runs (why refresh behaves) [#where-the-ladder-runs-why-refresh-behaves]
Whenever a signer **starts or resumes** a signing session, the API reloads envelope and recipient data and **re-evaluates which gate applies** from stored state - not from whatever your SPA last assumed.
That is why a browser refresh “snaps” the user back to the correct step: durable fields such as `auth_step`, `auth_method_states`, and KBA-related session data are the source of truth.
Your front end should render the next UI from the **signing session response** and the **recipient** object you get back from Verdocs, not only from the template defaults you used at send time.
***
## Verify signer: one endpoint, several modes [#verify-signer-one-endpoint-several-modes]
Signers complete gates through the **Verify signer** API while using a **signing session** token - not your organization’s API key. The request names which `auth_method` this round is for (`passcode`, `email`, `kba`, and so on).
Patterns that trip people up the first time:
* **Passcode / email OTP**: Wrong answers increment toward a hard failure; after enough failures the method can move to `failed`, the sender may be notified, and webhooks may fire - read response messages carefully.
* **KBA**: Early calls often supply identity fields; later calls supply `responses` for challenge or follow-up phases. There is a bounded verification window tied to when the step started (`auth_started`). If the signer waits too long, the flow can time out, fail the method, and notify the sender.
* **Already complete**: Calling verify again for a method that is already `complete` should return a fresh signing payload instead of forcing the user through the gate again.
For product context on which methods exist and how they behave at a high level, see *New Recipient Authentication Options* in What’s New.
Starting or refreshing the session itself is covered under *Start Signing Session*.
# Understanding and Managing Profiles (/docs/guides/tutorials/understanding-and-managing-profiles)
Like most other software-as-a-service offerings, Verdocs is "multi-tenant." Our permission management mechanisms are designed to allow users to perform actions on behalf of more than one organization at a time. This is achieved by separating the concept of a "user" (a single person, with a unique name and identity) from a "profile" (that person, acting on behalf of one organization). Consider the diagram below:
In this scenario, Paige Turner works for Odyssey Gym and regularly creates Liability Waivers for new members to sign. Paige is one person and has one profile, which defines her relationship to Odyssey Gym.
Will Power is one person but has two profiles. Will works for Greene CPAs during the week as an assistant, so he regularly sends IRS e-File Authorizations to clients of the firm. On the weekend, will also works for Odyssey Gym, and thus has also a profile defining his responsibilities there.
## "Current" profile [#current-profile]
Although Will Power has two profiles, only one is active, or "current," at a time. This may be changed at any time in the Verdocs Web App by choosing a different organization in the top-left menu, or via an API call:
```bash
curl -X POST 'https://stage-api.verdocs.com/v2/profiles/NEWPROFILEID/switch' \
-H "Content-Type: application/json" \
-H 'authorization: Bearer ey........Nc'
```
After switching profiles, calls to list templates, envelopes, or other data will "act as" the new current profile.
## Overriding the "Current" profile [#overriding-the-current-profile]
For historical reasons, switching the current profile will return new authentication tokens because they refresh the user's session. However, while tokens contain the user's profile\_id, this is only a convenience to help client-side code identify the current profile for the user ***at the time the token was issued***. That may not be the current profile for the user if it is changed later.
Previously issued tokens are not invalidated because there are legacy applications for which this behavior is required. But this can cause confusion for developers new to Verdocs if profiles are being switched regularly because calls may not return the data expected, particularly if you use your personal account when making calls, and change your current profile regularly.
The easiest way to avoid this is to create an "API User" that is only used for API calls. If this user never changes its current profile, you will never encounter this issue. However, in highly dynamic workflows where profiles and even organizations are created via the API rather than manually, there is a header you can set when making calls that will override this default behavior:
```bash
curl -X GET 'https://stage-api.verdocs.com/v2/templates' \
-H "Content-Type: application/json" \
-H 'authorization: Bearer ey........Nc' \
-H 'x-ignore-current: true'
```
Setting this header will instruct our API to disregard the current profile for the user making the call, and use the profile\_id encoded in the access token instead.
# Understanding Profiles, or "Why do my API calls return the wrong data?" (/docs/guides/tutorials/understanding-profiles-or-why-do-my-api-calls-return-the-wrong-data)
Periodically, we receive support requests from developers who believe they are receiving the wrong template/envelope data when querying lists of those records. A common source of this issue is a misunderstanding in the concept of a "Profile" within the Verdocs ecosystem.
Verdocs is a SaaS platform, with two specific challenges:
1. A human being might be a member of more than one organization. Consider the diagram below. Will Power is an employee of All Ways Fitness and does not use e-signing anywhere else. But Paige Turner is both an employee of Holden Accounting during the week and also on weekends works at All Ways Fitness as well.
2. An organization might have hierarchy. Many Verdocs customers/developers are resellers who manage their own client accounts on the platform. A single developer might therefore have access to many organizations.
There are three critical terms in this structure:
* **User**: A single person, regardless of their relationship with different organizations. In the diagram above, this would be Will Power or Paige Turner.
* **Organization**: A single entity, typically a company, which has one or more members (typically employees). Each member has different rights depending on their role, e.g. member vs. admin vs. owner. In the diagram above this would be Holden Accounting or All Ways Fitness.
* **Profile**: Maps a person's relationship to an organization. In the diagram above there are three profiles: Paige Turner as an Admin of Holden Accounting, Paige Turner as an Admin of All Ways Fitness, and Will Power also as an admin of All Ways Fitness.
Most users understand this structure, and this is how most SaaS platforms work. However, there can be a point of confusion for developers regarding the concept of a "current" profile. In the diagram above, the bold purple borders indicate each user's current profile - both Paige Turner and Will Power are currently working with All Ways Fitness.
In Verdocs, data is always returned for a user's current profile by default, **regardless of the access token that was used to make an API call**. Access tokens are checked for validity based on a number of criteria, but as long as they are valid, the token is only used to identify the person making the call. Once that is done, the "current" profile takes over and data will be retrieved/manipulated on that basis. In the diagram above, if a developer writing an app for Paige Turner requests her data, the templates and envelopes returned will be for All Ways Fitness, **even if the access token used in the call was issued while Holden Accounting was current when it as generated.** This is because in Web applications, users tend to remember what "mode" they are in, and it can be confusing for them if this gets overridden, e.g. Paige is working at All Ways Fitness on Saturday and suddenly seeing Holden Accounting data.
As a developer, you have three options to override this behavior:
1. Call the "[Switch Profile](https://developers.verdocs.com/rest-api/api-browser#tag/Profiles/operation/switchProfile)" endpoint (`POST /v2/profiles/{profile_id}/switch` or `switchProfile()` in the JS SDK) prior to making any calls, to ensure the profile you wish to use is selected as "current". This is the best option if you want to stay in sync with Web/Teams/other apps so users see consistent data across all their experiences.
2. Create separate developer-only profiles in each organization that you manage for each client that you onboard. This is the recommended option for resellers who may manage/oversee many client sub-accounts, and need admin access to their data regardless of what users do themselves.
3. Override this default behavior entirely by setting the header `x-ignore-current: true` in API calls. If this header is set, both the `profile_id` and `organization_id` from the access token will be used rather than the current profile in the database. This option is recommended for developers that want the lowest-code option without having to track or be aware of what profile is "current" for any given API call.
# Verifying a Completed Verdocs PDF Signature (/docs/guides/tutorials/verifying-a-completed-verdocs-pdf-signature)
A completed Verdocs PDF should be verified directly within the **desktop version of Adobe Acrobat** or **Adobe Acrobat Reader**. The [European Commission DSS web site](https://ec.europa.eu/digital-building-blocks/DSS/webapp-demo/validation) is not the appropriate validation method for this document, because the PDF uses an embedded document-signing certificate trusted through the **Adobe Approved Trust List (AATL)**.
***
## How to verify the document [#how-to-verify-the-document]
### 1. Open the original PDF in Adobe Acrobat [#1-open-the-original-pdf-in-adobe-acrobat]
Download the original PDF and open it locally in Adobe Acrobat or Acrobat Reader. Do **not** rely on an in-browser PDF preview.
### 2. Open the Signatures panel [#2-open-the-signatures-panel]
In Acrobat, open the **Signatures** panel.
### 3. Expand the Verdocs signature entry [#3-expand-the-verdocs-signature-entry]
Expand the entry labeled:
> Rev. 1: Signed by Verdocs, Inc. [support@verdocs.com](mailto:support@verdocs.com)
### 4. Confirm the validation results [#4-confirm-the-validation-results]
Acrobat should display a green checkmark and confirm that:
* The signature is valid
* The document has not been modified since the signature was applied
* The signer's identity is valid
* The signature includes an embedded timestamp
* The signature is LTV enabled (Long-Term Validation)
### 5. Review the certificate details [#5-review-the-certificate-details]
Select **Certificate Details** to review the certificate and its complete trust chain. Acrobat should show that the certificate path is valid and was issued through the **Sectigo** document-signing chain.
***
## Expected verification results [#expected-verification-results]
The screenshots below show the expected Adobe verification results for this document.
### Signatures panel [#signatures-panel]
Adobe Acrobat Signatures panel showing a valid Verdocs signature
### Certificate details [#certificate-details]
Adobe Acrobat Certificate Viewer showing a valid Sectigo-issued Verdocs certificate path
***
## Understanding the signature model [#understanding-the-signature-model]
Individual signer fields should **not** be expected to appear as separate certificate-backed signatures in the DSS validator.
For this document, the cryptographic verification point is the **Verdocs digital certificate** applied to the completed PDF. That certificate confirms:
* The **authenticity** and **integrity** of the final document
* Whether the document has been **altered** since certification
***
## Important: use the original downloaded PDF [#important-use-the-original-downloaded-pdf]
Make sure the supplier is reviewing the **original downloaded PDF**.
Printing the document to PDF, flattening it, or resaving it through another application can remove or disrupt the embedded validation information. Any of these actions may cause verification to fail even when the original document is valid.
***
## Troubleshooting [#troubleshooting]
If the supplier does not see the same verification results shown above, please send us:
1. The exact PDF they are reviewing
2. Their Adobe Acrobat version
We can then investigate further.
# Why am I not receiving Verdocs email notifications? (/docs/guides/tutorials/why-am-i-not-receiving-verdocs-email-notifications)
Has someone told you they sent you a document to sign, but you never got the email? Verdocs sends transactional messages when envelopes are sent, reminders are issued, and other signing events occur. Those messages are sometimes filtered by your email provider, corporate mail server, or inbox rules before they reach you.
This article covers the most common causes and what to do about them.
***
## Solution 1: Check spam and add trusted senders [#solution-1-check-spam-and-add-trusted-senders]
* **Check your Junk or Spam folder.** If you find a Verdocs message there, mark it as *Not junk* or *Not spam* so future messages are delivered to your inbox.
* **Add Verdocs as trusted senders** in your email client (sometimes called *Safe senders* or *Trusted senders*). Allowlist these addresses:
* `support@verdocs.com`
* `noreply@verdocs.com`
* `notifications@verdocs.com`
* **Forward these steps to your IT team** if you use a corporate mailbox (Microsoft 365, Google Workspace, etc.):
* Allow email from the domain `verdocs.com` and the sender addresses listed above.
* Review quarantine, advanced threat protection, and third-party email security gateways for blocked messages from Verdocs.
* Confirm your mail server accepts modern TLS (TLS 1.2 or later).
After your IT team or email provider updates their filters, ask the sender to **resend the envelope** or send a reminder so a fresh message is delivered.
***
## Solution 2: Confirm the correct email address [#solution-2-confirm-the-correct-email-address]
Verdocs sends notifications to the **email address on the envelope** for each recipient. If you use multiple inboxes or aliases, the message may have gone to a different address than the one you are checking.
* Ask the sender which email they used for you on the envelope.
* If you have access to the sending application or portal, confirm your profile or recipient record shows the right address.
* Typos in the recipient email are a frequent cause of “missing” notifications. The sender may need to correct the address and resend.
***
## Solution 3: Access the document without waiting for email [#solution-3-access-the-document-without-waiting-for-email]
If you need to sign right away:
* **Open the signing link from another channel.** The sender’s application may provide a direct signing URL, in-app notification, or SMS (if enabled on their account).
* **Use embedded signing** if the sender’s product supports it - you may complete the document inside their app without relying on email delivery.
If you still cannot access the envelope, contact the sender or your organization’s Verdocs administrator.
***
## Solution 4: Notification settings and how your sender delivers mail [#solution-4-notification-settings-and-how-your-sender-delivers-mail]
Not every Verdocs integration sends email from Verdocs directly.
* Some platforms use **bring-your-own notification** and deliver invite links from **their own domain** instead of `notifications@verdocs.com`. If your sender uses that mode, check messages from their company’s domain as well.
* **Reminders** and some follow-up messages are email-only. If you received the first invite through another channel but expected a later reminder by email, confirm with the sender that reminders are enabled and that your address is correct.
* If you are a **Verdocs platform administrator**, review notification templates and workflow settings in your organization to ensure the expected events are configured to send email.
***
## Still need help? [#still-need-help]
If you have completed the steps above and still do not receive expected messages:
* Ask the sender to verify the envelope was sent successfully and to resend or issue a reminder.
* Contact [**support@verdocs.com**](mailto:support@verdocs.com) with the email address you expected to receive mail on, the approximate send time, and the name of the organization that sent the document.
Your IT team can also request delivery details from the sender’s administrator if messages are being blocked at the organizational level.
# AcroForm Support (/docs/learn/whats-new/acroform-support)
**2026-06-30**
## What is AcroForm support? [#what-is-acroform-support]
Many PDFs are authored as **fillable forms**: text boxes, checkboxes, dropdowns, and signature areas defined inside the PDF itself using the AcroForm standard (common in government, HR, and banking documents).
Previously, turning one of these PDFs into a Verdocs template meant **manually placing every field** in the template builder - or rewriting the document with handlebars-style `{{...}}` tags.
With AcroForm support, Verdocs **inspects the PDF on upload**, maps each detected widget to a Verdocs field type, and creates the corresponding template fields automatically. Detected fields flow through the same role-and-field pipeline used by Dynamic Tagging, so once the template is built you send envelopes the same way you always have.
***
## How it works [#how-it-works]
When you [attach a PDF to a template](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/template-documents/createTemplateDocument):
1. Verdocs checks whether the PDF contains Verdocs text tags.
2. If **no text tags** are found and your organization has opted in, Verdocs scans for AcroForm widgets.
3. Each widget is mapped to a Verdocs field type (for example textbox, checkbox, dropdown, date, initial, or signature) based on the PDF field type and name.
4. A single signer role - **Recipient** - is created and all detected fields are assigned to it. AcroForm PDFs do not encode which signer owns which widget, so Verdocs uses one role by default. You can rename or split roles afterward in the template builder or via the API.
5. Non-signing controls such as **Reset** and **Print** buttons are ignored.
If detection fails for any reason, the upload still succeeds - the document is stored without auto-generated fields.
***
## Supported field types [#supported-field-types]
Verdocs maps common AcroForm widget types to signing fields:
| AcroForm widget | Verdocs field |
| -------------------------------- | -------------------------------------------- |
| Text (`Tx`) | Textbox (multiline when the PDF flag is set) |
| Text with date-style naming | Date |
| Text with signature-style naming | Signature |
| Text with initial-style naming | Initial |
| Button (`Btn`, checkbox) | Checkbox |
| Button (`Btn`, radio) | Radio |
| Choice (`Ch`) | Dropdown |
| Signature (`Sig`) | Signature |
Field labels are derived from the PDF's internal field names, so deeply nested government-form names are cleaned up into readable placeholders.
***
## How to enable it [#how-to-enable-it]
AcroForm auto-detection is **opt-in** per organization. It is controlled by the `process_acroforms` pipeline setting and is `false`\*\* by default\*\* for new organizations.
Organization admins can enable it with:
```
PATCH /v2/organizations/{organization_id}/pipeline-settings
{
"process_acroforms": true
}
```
AcroForm detection is independent of text-tag processing (`process_tags`). It runs only when **no Verdocs text tags** are present on the PDF, so you can use Dynamic Tagging and AcroForm detection in the same account without them conflicting.
For full details on pipeline settings - including where they apply and recommended configurations - see the [Organization pipeline settings](https://developers.verdocs.com/docs/guides/tutorials/organization-pipeline-settings) guide *(link when published)*.
***
## When to use AcroForm vs Dynamic Tagging [#when-to-use-acroform-vs-dynamic-tagging]
| Approach | Best for |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **AcroForm auto-detection** | PDFs that already exist as fillable forms; quick onboarding of standard documents like I-9 or signature cards |
| **Dynamic Tagging** | Server-generated PDFs and DOCX files where you control the source and embed `{{...}}` tags; multi-signer workflows with explicit role names in the document |
You do not need to modify the source PDF to use AcroForm support - upload the file as-is. If you need multiple signers with distinct roles defined in the document itself, Dynamic Tagging remains the better fit.
***
## Related documentation [#related-documentation]
* [Tagging Dynamic Documents](https://developers.verdocs.com/docs/guides/tutorials/tagging-dynamic-documents) - embed tags for programmatic field placement
* [Attach a document to a template](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/template-documents/createTemplateDocument)
* [Send an envelope without a template](https://developers.verdocs.com/docs/guides/tutorials/send-an-envelope-without-a-template) - AcroForm detection also applies when documents are attached directly to an envelope
# Corporate Email Safeguard (/docs/learn/whats-new/corporate-email-safeguard)
**2026-05-11** | Profile
**Summary:** Verdocs now applies the same corporate-email requirement to both self-service signup and organization invitation resend flows. If the email address belongs to a major consumer webmail provider, the request is rejected with guidance to use a work-owned email address instead.
**Who this affects:** Developers testing signup flows, admins resending organization invitations, growth teams linking self-service onboarding pages, and integrators automating organization onboarding workflows.
***
## Why we added this safeguard [#why-we-added-this-safeguard]
Self-service onboarding works best when organizations are tied to identifiable business contacts. Using generic consumer inboxes makes it harder to:
* associate accounts with real companies
* support customers effectively
* reduce throwaway or mistyped registrations
* maintain clean B2B onboarding flows
This safeguard only applies to specific account and organization entry points. It does not affect document recipients or signing participants.
***
## Where it applies [#where-it-applies]
### 1. Self-service signup (Create profile) [#1-self-service-signup-create-profile]
The validation runs when:
* a user registers through the unauthenticated Create Profile signup flow
* the request is creating a brand-new organization/account
* the submitted email passes normal formatting validation
This does not affect adding members while already authenticated inside an existing organization. If self-service signup is disabled in your environment, this flow may not be publicly exposed.
#### Affected APIs [#affected-apis]
The signup flow is exposed through:
* the REST API Profiles endpoints
* the JS/TS SDK signup/profile helpers
Exact endpoint naming may vary slightly by release.
***
### 2. Resend organization invitation [#2-resend-organization-invitation]
When an administrator resends a pending organization invitation, the invitee email address is validated against the same corporate-email rules before Verdocs sends the invitation again. This prevents teams from bypassing the safeguard by switching to personal inboxes during invitation resend flows.
#### Affected API [#affected-api]
The resend flow is handled through the organization invitation resend endpoint. Always confirm the exact route and request shape against the live API reference for your environment and API version.
***
## What “corporate email” means [#what-corporate-email-means]
The email address must:
1. be syntactically valid
2. use a domain that is not on Verdocs’ maintained consumer-webmail blocklist
***
### Commonly rejected domains [#commonly-rejected-domains]
Examples typically rejected include domains associated with:
| Gmail | Yahoo |
| ------- | ---------- |
| Outlook | Hotmail |
| iCloud | ProtonMail |
| AOL | |
The exact blocklist can evolve over time.
***
### Commonly accepted domains [#commonly-accepted-domains]
Examples typically accepted include:
* `you@acmecorp.com`
* `you@yourbrand.com`
* `you@lawfirm.co.uk`
* `you@partner-company.io`
Custom domains hosted through Google Workspace or Microsoft 365 are treated as corporate domains because the domain belongs to the organization.
***
### Subdomains [#subdomains]
Subdomains are evaluated normally.
For example: `you@mail.yourcompany.com` is treated as a corporate domain if the full domain is not on the consumer-provider blocklist.
***
## What users see when validation fails [#what-users-see-when-validation-fails]
The API returns an error message directing the user to use a corporate email address.
Typical messaging:
> Please use your corporate email address
Your application should surface this message clearly or present equivalent wording with the same meaning. There is no override flag for these protected flows.
***
## What this does not change [#what-this-does-not-change]
This safeguard does **not** affect:
* envelope recipients
* document signers
* external participants invited to sign documents
People signing documents can still use personal email addresses. This validation specifically applies to:
* unauthenticated self-service profile creation
* organization invitation resend operations
Other organization and member-management APIs may use different validation behavior depending on the operation.
***
## Guidance for integrators and QA [#guidance-for-integrators-and-qa]
| Situation | Recommendation |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Automated signup tests | Use a domain your organization controls instead of personal Gmail accounts. |
| CI or staging environments | Use dedicated test domains or subdomains. |
| “Sign up with Google” discussions | Treat social login as a separate product capability from raw email/password signup. |
| Customers using only personal email | Route through sales, support, or organization-admin invitation flows instead of self-service signup. |
| QA for invitation resend | Expect the same corporate-email validation behavior during resend testing. |
***
## Multi-tenant SaaS note [#multi-tenant-saas-note]
If you build a multi-tenant SaaS product on top of Verdocs, you should still use dedicated organization-scoped service identities and API credentials for each customer organization.
This safeguard does not replace normal tenant-isolation or organization-management practices.
# Custom Disclaimers (/docs/learn/whats-new/custom-disclaimers)
**2025-04-07**
Continuing our commitment to offering a fully white-labeled solution, we have added an organization-level setting that allows you to customize the e-signing disclaimer/disclosure shown to recipients before signing a document. This is accessible under Settings -> Disclaimer.
This feature has legal implications, and changing it requires approval by Verdocs. If you do not yet have access to the function in your organization, please use the bottom-right support button to request it.
# Disclosures are now tracked at signing (/docs/learn/whats-new/disclosures-are-now-tracked-at-signing)
**2025-05-22**
e-Signing Disclosures are now customizable as part of an Organization's settings. Because they can change over time, you need to know the precise language presented to each recipient at the time they signed an envelope in case it has changed. To support this, recipient metadata blocks will now track the text of the language the user agreed to when accepting those disclosures. Additionally, this language, and the date/time of acceptance, will now be displayed in Envelope Certificates, for later reference.
# DOCX Support (/docs/learn/whats-new/docx-support)
**2024-07-28** | Documentation
The e-signature industry revolves around PDF files for legal and security reasons. Once signed and stamped with our document signing certificate, PDFs are tamper-proof and reliable as an archival copy of the signed docment for long-term storage.
However, many of our users work with DOCX files as their source documents, and it is not always convenient to convert these to PDFs before sending them for signature. Developers often prefer to work with DOCX format files when creating templates programmatically, because they are easier to generate dynamically.
Now you can have the best of both worlds! Verdocs now supports DOCX files as source documents, and will handle the conversion to PDF for signature automatically. This means you can upload DOCX files directly to Verdocs, and they will be converted to PDFs when you create a template from them.
# Dynamic Tagging (/docs/learn/whats-new/dynamic-tagging)
**2024-08-05** | Documentation
Placing fields by hand means working out pixel positions for every document. With dynamic tagging, you can place fields automatically by including handlebars-style tags in the source document template. When you create a template from a tagged document, roles and fields will be automatically recognized and placed in the appropriate locations.
Head to [our guide](/docs/guides/tutorials/tagging-dynamic-documents) to learn more about this new feature and how to use it in your templates.
# IFRAME Embed Events (/docs/learn/whats-new/iframe-embed-events)
**2026-10-28** | Embeds
If you show Verdocs in an [IFRAME embed](/docs/guides/tutorials/iframe-embeds), your page can now follow along with what happens inside it. Each embed posts a small message to its parent window as things happen, such as a signer agreeing to the disclosures, submitting, or declining, so you can close a dialog or move your user to the next step without polling the API.
```js
window.addEventListener('message', (e) => {
if (e.origin !== 'https://app.verdocs.com' || e.data?.source !== 'verdocs') {
return;
}
if (e.data.embed === 'sign' && e.data.event === 'submitted') {
// e.data.envelope_id and e.data.role_name identify who finished
}
});
```
Every embed reports events for its own work: Sign reports `loaded`, `agreed`, `later`, `printed`, `submitted`, and `declined`, Build and Send report `sent` with the new envelope's id, Auth reports `authenticated`, and all of them report `error` when a request fails. Messages include ids and event names only, so use the ids with the API or [webhooks](/docs/reference/Rest-API/webhooks) when you need more detail.
Embeds also post a `resize` message with the height their content needs, so you can size the IFRAME to fit instead of picking a fixed height and scrolling inside it.
The full list of events and the fields each one includes is in the [Events section](/docs/guides/tutorials/iframe-embeds#events) of the IFRAME embeds guide.
## Send embed fix [#send-embed-fix]
The Send embed at `https://app.verdocs.com/embeds/send/TEMPLATE_ID` now shows the send form. It previously showed the template preview, the same as `https://app.verdocs.com/embeds/preview/TEMPLATE_ID`.
# What's New? (/docs/learn/whats-new)
### [IFRAME Embed Events](/docs/learn/whats-new/iframe-embed-events) [#iframe-embed-events]
**2026-10-28**
IFRAME embeds now tell your page what happens inside them, such as a signer finishing, and how tall their content is.
***
### [SMS Notifications](/docs/learn/whats-new/sms-notifications) [#sms-notifications]
**2026-07-07**
Use SMS to keep recipients up-to-date on the status of their envelopes.
***
### [AcroForm Support](/docs/learn/whats-new/acroform-support) [#acroform-support]
**2026-06-30**
Save time by leveraging AcroForms to generate your document's fields automatically.
***
### [Corporate Email Safeguard](/docs/learn/whats-new/corporate-email-safeguard) [#corporate-email-safeguard]
**2026-05-11**
Verdocs now enforces a corporate-email safeguard on: unauthenticated Create Profile signup flows and organization invitation resend operations.
***
### [Web SDK v6.6.0](/docs/learn/whats-new/web-sdk-v6-6-0) [#web-sdk-v660]
**2026-02-23**
v6.6.0 introduces a number of new features, including a streamlined signing workflow, much faster final signing/stamping, Webhook authentication, and much more.
***
### [Disclosures are now tracked at signing](/docs/learn/whats-new/disclosures-are-now-tracked-at-signing) [#disclosures-are-now-tracked-at-signing]
**2025-05-22**
e-Signing Disclosures are now tracked when recipients sign envelopes.
***
### [Knowledge-Based Authentication now requires SSN-Last-4](/docs/learn/whats-new/knowledge-based-authentication-now-requires-ssn-last-4) [#knowledge-based-authentication-now-requires-ssn-last-4]
**2025-05-20**
Based on customer feedback, we have re-activated the collection of SSN-Last-4 during KBA workflows.
***
### [Custom Disclaimers](/docs/learn/whats-new/custom-disclaimers) [#custom-disclaimers]
**2025-04-07**
This release adds support for custom disclaimers, plus other bug fixes and performance improvements.
***
### [New Recipient Authentication Options](/docs/learn/whats-new/new-recipient-authentication-options) [#new-recipient-authentication-options]
**2025-03-28**
Ensuring documents are signed by the correct individuals is a crucial component in e-signing workflows. To help achieve this, we have added several new authentication methods to our platform.
***
### [Sender Name Overrides](/docs/learn/whats-new/sender-name-overrides) [#sender-name-overrides]
**2025-01-01**
To increase customization options when sending envelopes, it is now possible to override the "name" used in outbound emails and text messages.
***
### [New Developer Center Released](/docs/learn/whats-new/new-developer-center-released) [#new-developer-center-released]
**2024-10-28**
The Verdocs Developer Center has been rebuilt and is now live. It brings the API reference, the SDKs, and the guides together in one place, so you are not jumping between sources to build against the Verdocs platform.
***
### [SDKs Revamped](/docs/learn/whats-new/sdks-revamped) [#sdks-revamped]
**2024-10-01**
We rebuilt the SDKs around developer feedback: clearer type definitions, better documentation, and a more predictable shape for integrating them into your applications.
***
### [Dynamic Tagging](/docs/learn/whats-new/dynamic-tagging) [#dynamic-tagging]
**2024-08-05**
Placing fields by hand means working out pixel positions for every document. With dynamic tagging,
you can place fields automatically by including handlebars-style tags in the source document
template.
***
### [DOCX Support](/docs/learn/whats-new/docx-support) [#docx-support]
**2024-07-28**
The e-signature industry revolves around PDF files for legal and security reasons. Once signed and stamped with our document signing certificate, PDFs are tamper-proof and reliable as an archival copy of the signed document for long-term storage.
***
# Knowledge-Based Authentication now requires SSN-Last-4 (/docs/learn/whats-new/knowledge-based-authentication-now-requires-ssn-last-4)
**2025-05-20**
Based on customer feedback, we have re-activated the collection of SSN-Last-4 during KBA workflows. This can significantly increase matching accuracy when authenticating recipients, reduce matching costs, and may be required in some workflows.
Developers do not need to do anything to accommodate this change. The KBA Dialog component will automatically collect and process the field.
# New Developer Center Released (/docs/learn/whats-new/new-developer-center-released)
**2024-10-28** | Documentation
The Verdocs Developer Center has been rebuilt and is now live. It brings the API reference, the SDKs, and the guides together in one place, so you are not jumping between sources to build against the Verdocs platform. It includes a comprehensive API reference, SDKs, and guides to help you get started quickly.
# New Recipient Authentication Options (/docs/learn/whats-new/new-recipient-authentication-options)
**2025-03-28**
Ensuring documents are signed by the correct individuals is a crucial component in e-signing workflows. To help achieve this, we have added several new authentication methods to our platform. These may be selected on a per-recipient basis when creating new envelopes to sign:
* **Passcode**: A pre-defined password or PIN code is set by the sender. This method is best suited for cases where the sender has a pre-existing, extended relationship with the recipient. Typically, the passcode is determined ahead of time by the recipient and kept on file by the sender.
* **Email One-Time-Passcode**: A 6-digit passcode will be emailed to the recipient. This code is valid for 1 hour, after which a new code may be requested if necessary.
* **SMS One-Time-Passcode**: A 6-digit passcode will be sent via SMS to the recipient. This code is valid for 1 hour, after which a new code may be requested if necessary.
* **Knowledge-based Authentication**: The recipient will be prompted for personal details such as their address and date of birth, then challenged with questions such as prior addresses to verify their identity.
* **Scan/Verify**: The recipient will be prompted to capture their photograph and government-issued identity documents such as their license or passport.
*NOTE: Some methods such as SMS and KBA require activation before they may be used. Some fees may apply.*
# SDKs Revamped (/docs/learn/whats-new/sdks-revamped)
**2024-10-01** | SDK
We rebuilt the SDKs around developer feedback: clearer type definitions, better documentation, and a more predictable shape for integrating them into your applications. Some highlights:
* **Improved documentation**: Detailed guides, code samples, and API references, reorganized so you can find things by task.
* **Streamlined type definitions**: These include minor true-ups such as renaming `setting` to `settings` as well as adding new top-level fields for user-submitted values and other important metadata.
* **data attributes**: Both templates and envelopes now allow developers to store arbitrary application-provided data with these objects, making it much easier to correlate Verdocs objects with your applications' data.
Please head to [Verdocs JS SDK on Github](https://github.com/verdocs/js-sdk) and [Verdocs Web SDK on Github](https://github.com/verdocs/web-sdk) to view the full changelogs and release notes.
# Sender Name Overrides (/docs/learn/whats-new/sender-name-overrides)
**2025-01-01** | Documentation
To increase customization options when sending envelopes, it is now possible to override the "name" used in outbound emails and text messages. Previously, this used the name of the profile sending the envelope, falling back on the organization name, e.g. "First Last \". This made sense for most users, but was an extra step for developers because customizing this name required creating and updating a new profile for each sender.
When making a request to send an envelope, you can now specify a `sender_name` field in the request body as follows:
```
{
"template_id": "...",
"sender_name": "Custom Name",
"recipients": [
{
"email": "..."
}
]
}
```
This will override the sender name for the envelope, e.g. "Custom Name \". Since this is a one-time operation per envelope, it is not necessary to create a new profile for each sender.
You cannot override the email address, only the name. It is not possible for us to impersonate email addresses and still maintain deliverability.
**Update:** The From line on Verdocs email now comes from the envelope's brand, falling back on the organization name, so `sender_name` no longer changes it. `sender_name` still names the sender inside the email body ("Custom Name sent you a document"), and `sender_email` is where completion notices and recipient questions go. To change the name recipients see in their inbox, set the brand's sender name, or send from your own address with [a custom email domain](/docs/guides/tutorials/add-a-custom-email-domain-to-your-brand).
# SMS Notifications (/docs/learn/whats-new/sms-notifications)
**2026-07-07** | SMS, Notifications
## Transactional SMS in the Verdocs API [#transactional-sms-in-the-verdocs-api]
Your signers live on their phones. For many workflows, a text message is the fastest way to get someone into a signing session. Verdocs supports **transactional SMS** - automated, event-driven text messages tied to envelope activity - alongside email. This article covers how that works today, what you need to enable it, and what to expect when you integrate.
***
## What is transactional SMS? [#what-is-transactional-sms]
Transactional SMS messages are automated texts Verdocs sends when something meaningful happens in a signing workflow. They are not marketing blasts. Each message is tied to a specific envelope event, includes a direct link to act, and is sent as a **transactional** message (with standard opt-out language appended).
**For the time being, only one notification event sends SMS**: `recipient:invited` - the initial invitation when a signer is asked to review and sign. Other lifecycle events (reminders, completion, cancellation, delegation, and so on) may send email notifications, but not SMS.
Unlike email notifications, SMS copy is **not customizable** through [notification templates](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/notifications/getNotificationTemplates). Verdocs uses a fixed, concise format so messages stay readable on small screens and compliant with carrier expectations.
***
## When does Verdocs send an SMS? [#when-does-verdocs-send-an-sms]
### Supported events (today) [#supported-events-today]
Verdocs routes SMS through the same notification system as email, but **only one event is enabled for the SMS channel right now**:
| Event | Sends SMS? | Typical trigger |
| ------------------------- | --------------- | ----------------------------------------------------- |
| `recipient:invited` | **Yes** | A signer is invited to an envelope for the first time |
| `recipient:reminder` | No (email only) | Automated or manual reminder to sign |
| All other envelope events | No | Completion, cancellation, delegation, CC, etc. |
If you are building against the API or debugging delivery, look for `recipient:invited` - that is the only event that will queue an outbound text today.
When that event fires and a signer is invited, Verdocs may deliver both an email and a text - if all of the conditions below are met.
| Condition | Why it matters |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Your organization has the **SMS notifications** entitlement | Without it, Verdocs skips SMS silently and still sends email. See [Understanding Entitlements](https://developers.verdocs.com/docs/guides/tutorials/organization-hierarchies#entitlements). |
| The recipient has a **phone number** on their record | SMS is only queued when `phone` is present at invite time. |
| The envelope is **not** `no_contact` | Bring-your-own-notification envelopes skip all outbound contact from Verdocs. See [Bring-Your-Own Notification](https://developers.verdocs.com/docs/guides/tutorials/bring-your-own-notification). |
| The recipient has **not opted out** of SMS | Recipients who reply `STOP`, `CANCEL`, or `END` will not receive further texts. |
**Reminders and resends** use `recipient:reminder`, which is **email-only**. A new SMS is not sent on reminder or manual resend - even if the recipient has a phone number. Only the original `recipient:invited` event triggers a text.
### What the message looks like [#what-the-message-looks-like]
An invitation SMS follows this pattern:
```
Action required - {envelope name}
{sender name} invited you to review and sign a document.
Sign here: {signing link}
Reply STOP to cancel.
```
The signing link respects your [Brand](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/brands/getBrand) configuration: if the envelope uses a brand with an active custom app domain, the link points there; otherwise it uses the default Verdocs signing host. The link includes the recipient's role and a secure access key - the same style of deep link recipients receive by email.
***
## How SMS fits into your integration [#how-sms-fits-into-your-integration]
### Provide a phone number on the recipient [#provide-a-phone-number-on-the-recipient]
When you [create an envelope](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/envelopes/createEnvelope), include a `phone` value on each recipient who should be reachable by text. At least one of `email` or `phone` is required per recipient; many teams supply both so Verdocs can reach signers on either channel.
Use a valid, internationally formatted number (E.164). Verdocs normalizes phone numbers before sending. Invalid numbers are rejected at send time rather than retried indefinitely.
### Email and SMS run in parallel [#email-and-sms-run-in-parallel]
Invitations are not either/or. When a recipient has both email and phone, Verdocs queues **both** channels independently. That is why you may see envelope history entries for an email invite and an SMS invite for the same recipient - and why a missing SMS entitlement does not block email delivery.
### Opt-out and consent [#opt-out-and-consent]
SMS consent works differently from email:
* **Email** recipients are treated as opted in by default for transactional messages.
* **SMS** recipients are not auto-opted-in. Verdocs tracks consent per organization and phone number. A recipient who has not opted out (`pending` or `opted_in`) can receive messages; an `opted_out` recipient will not.
Every transactional message includes **"Reply STOP to cancel."** Inbound replies of `STOP`, `CANCEL`, or `END` mark the number as opted out for that organization. Future invitations to that number are suppressed for SMS while email continues to work.
### Bring-your-own notification [#bring-your-own-notification]
If your application owns all signer communication, set `no_contact: true` on the envelope. Verdocs will not send invitation emails **or** SMS for that envelope. You are responsible for delivering the signing link yourself - typically via [Start Signing Session](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/recipients/startSigningSession) or your own link construction.
***
## Observability: history, certificates, and usage [#observability-history-certificates-and-usage]
Verdocs gives you several ways to confirm what happened - useful for support tickets and billing reconciliation.
**Envelope history** records whether a recipient was invited via email or SMS. In the dashboard, you will see messages like *"Jane Doe has been invited via sms"* alongside the email equivalent. When a recipient opens the document, history also notes whether they arrived through the email link or SMS link.
**Completion certificates** include an **SMS Invitation** indicator when the signer entered the workflow through a text-message link (alongside Email Invitation, In-Person Link, and In-App options). This helps demonstrate how the signer was reached during an audit.
**Usage metering** records each SMS invitation as `sms_invite` in your organization's usage metrics. Query [Get organization usage](https://developers.verdocs.com/docs/reference/Rest-API/api-docs/organizations/getOrganizationUsage) or listen for the `entitlement_used` [webhook](https://developers.verdocs.com/docs/reference/Rest-API/webhooks) event to feed internal billing or dashboards - especially valuable with [organization hierarchies](https://developers.verdocs.com/docs/guides/tutorials/organization-hierarchies).
# Web SDK v6.6.0 (/docs/learn/whats-new/web-sdk-v6-6-0)
**2026-02-23**
We are proud to announce a major release with a number of significant new features. There are no breaking changes in our API / JS-SDKs, but we bumped those to v6.6.0 to match the same major version bump in our Web SDK, which does have a few breaking changes to note.
### Webhook enhancements [#webhook-enhancements]
In this release, low-level definitions in our SDKs have been refined to true up the options listed. Please see our [JS-SDK v6.6.0 Release Notes](https://github.com/Verdocs/js-sdk/releases/tag/6.6.0) for details on these. The Settings panel in the Verdocs Web App also now reflects these changes, and adds status displays for the most recent successful/failing deliveries to help troubleshoot delivery issues.
We have always had delivery-retry logic, but we never formally documented how it works. We use Graphile Worker for our async task handling, which uses an exponential backoff algorithm to handle failures and will attempt each delivery up to 25 times. For more information on how this works please [see here](https://worker.graphile.org/docs/exponential-backoff). We do not delete failed deliveries, but we will stop trying pending human intervention to avoid "spamming" client systems. (If you need to schedule redelivery please contact us for assistance.) For developers requiring the most reliability, we recommend leveraging highly-available service layers such as AWS Lambda or equivalent in combination with tools such as "dead letter queues" per the best practices recommended by the cloud vendor you are using.
Webhooks also now support two authentication modes: HMAC and OAuth2. HMAC will use a pre-shared key to generate a hash of the Webhook payload. To activate this method, call "PATCH /v2/webhooks" to set "auth\_method" to "hmac". Then call "PUT /v2/webhooks/rotate-secret" to generate a new secret key, which will be returned in the response to that call. To prevent theft of this key, it may not be read back later, but it may be rotated as many times as needed. Finally, to validate the hash, use code such as the following:
```typescript
const requestBody = req.body;
const jsonBody = JSON.stringify(requestBody.body);
const hash = createHmac('sha256', SECRET_KEY).update(jsonBody).digest('hex');
if (hash !== req.headers['x-webhook-signature']) {
// Handle error here
}
```
If auth\_method is set to "client\_credentials", then developers should also set client\_id and client\_secret. In this case, Verdocs will make an OAuth2-compliant "Client Credentials" auth request before delivering the Webhook, and set the resulting access\_token in the Webhook call's "Authorization: Bearer ACCESS\_TOKEN..." header instead.
We do not currently cache this access token, but may in the future. To prevent this, developers may set the exp expiration in the token to 0. We will still use the access token for the current delivery, but not cache it beyond that.
### General UI and workflow improvements [#general-ui-and-workflow-improvements]
We have been hard at work streamlining our signing flow and have made a number of improvements in our Verdocs Sign embed to support this. Some of the highlights include:
* Modernizing all dialog boxes and providing a more consistent look and feel, with a "card-style" title and close button, content region, and footer buttons.
* To reduce the number of clicks required to sign a document, recipients will now be asked to adopt a signature block one time, when they first start signing. Both Signature and Initials blocks will be generated. Clicking signature/initials fields will apply the adopted block with no additional dialogs.
* Recipients may now change their signature/initials blocks. When hovering a signature or initials field, a clear button will allow them to erase what they completed, and an edit button will allow them to change their signature block.
* Zoom in/out buttons will let users adjust their view while signing.
* A progress indicator will clearly communicate to recipients how many fields they have left to complete before submitting, with both Next and Prev buttons to navigate between fields.
* A flag will be shown next to the next required or optional field to be completed. To save room, these flags will be hidden on narrow/mobile devices. Flags next to optional fields will include a "Skip" option as an additional means of jumping to the next field.
* Envelopes that contain multiple documents will now display a file name header above each document as a visual separator.
* Text and date fields may now be resized below their previous minimum dimensions. If this is done, the display font size will be automatically reduced to help the values "fit" the smaller fields.
* The signing experience "footer" now provides several layout/branding options:
* Three buttons will always be displayed centered for common operations like Ask a Question, with an optional fourth if Delegation is enabled for the recipient.
* Organization settings now support an optional "Powered by" style label that will be shown in the bottom left corner, which developers may use to provide "Powered by MyAppSign" branding. This label may also have an optional link configured, such as to provide recipients with a link to the organization's Web site.
* Organization settings may also be configured with Terms of Service and Privacy Policy links, which will be displayed in the bottom-right.
* The download dialog has been enhanced in several ways
* The filename of the document is more clearly displayed.
* If there are two documents, two download options will be shown. If there are three or more, a message will be shown asking the user to download the Zip file instead. (Our internal analytics suggest 3+ document envelopes are rare and we didn't want to complicate the UI for that case.)
* If documents are still being processed, an indicator will clearly communicate this to the user. (The majority of documents are processed in \<5 seconds, but if users click download very quickly after signing, this will prevent them from clicking too quickly.)
### Branding and styling overrides [#branding-and-styling-overrides]
In the latest Web SDK release, we have significantly modernized how our default styles may be overridden by developers. We have always promoted a fully white-labeled approach, but previously each component was styled individually. Based on developer feedback, v6.6.0 migrates the 50 most commonly overridden properties (particularly base colors and fonts) to CSS variables, allowing multiple components to be themed at once.
To help developers take advantage of these variables we have published a sample [overrides.css](https://github.com/Verdocs/web-sdk/blob/main/verdocs-web-sdk/src/overrides.css) file in the SDK. (Please see the comments in that file for instructions.) We have also added a dropdown theme selector to our [component catalog](https://developers.verdocs.com/sdks/embeds/components) to help developers visualize the effects of these sample overrides. As a bonus feature, we added a feature to our component catalog to remember property input values, so navigating to different components in the catalog or reloading the page will no longer clear those options.
In an upcoming release, we plan to add options to organization settings to allow these overrides be to set even when Verdocs hosts the signing experience. This means even developers not leveraging our Web Components will be able to fully white-label the experience. Stay tuned!
# Rest API (/docs/reference/Rest-API)
## Getting Started [#getting-started]
If you have not already done so, [Create a free Verdocs Account](https://app.verdocs.com/signup) for your development use. If you are developing an application for an existing organization, you will need Admin or Owner rights to it. (API keys are tied to organizations.)
Then visit your API Key Settings in the Verdocs Web App. Create an API key to access the API, and save the Client ID and Secret Key that this generates.
The secret key is used only for server-to-server calls. It should never be embedded in a front-end Web or mobile application!
## Implementation Notes [#implementation-notes]
The Verdocs API may be used directly from both server- and client-side applications written in any language, Verdocs also offers language-specific SDKs
that abstract away much of the complexity of calling the API directly. We recommend using an SDK if one is available for your target environment, whenever
possible.
The Verdocs API may be used directly from both server- and client-side applications written in any language, Verdocs also offers language-specific SDKs
that abstract away much of the complexity of calling the API directly. We recommend using an SDK if one is available for your target environment, whenever
possible.
# Webhooks (/docs/reference/Rest-API/webhooks)
Rather than constantly polling for updates, Webhooks allow your application to receive immediate updates as users interact with Templates and Documents. To receive Webhook calls, you must provide an endpoint within your app reachable via an HTTPS `POST` call. When enabled, your endpoint will be called once per event.
To enable Webhooks, visit your **Organization Settings** panel in the Verdocs Dashboard and open Developer Settings. Here you can configure your Webhook endpoint and the events you wish to receive:
## Webhook Events [#webhook-events]
Select an event to see the full TypeScript shape of its request body and an example. All dates in payloads are ISO 8601 strings.
### Envelope events
#### envelope_created
An envelope is created, either from a template or directly. Only the envelope record is sent; fetch the envelope if you need its recipients, documents, or fields.
`data`: `EnvelopeBase`
#### envelope_updated
A recipient submits or delegates, a preparer finishes, or an expired or failed envelope is reset. Delegation sends the envelope wrapped as { envelope }.
`data`: `Envelope | { envelope: Envelope }`
#### envelope_completed
Every recipient has acted and all documents, including the certificate, are signed. Each document includes a download link that expires after 1 hour.
`data`: `CompletedEnvelope`
#### envelope_canceled
The sender cancels the envelope.
`data`: `Envelope`
#### envelope_expired
The envelope reaches its expires_at date before it is completed. Expired envelopes can be reset.
`data`: `Envelope`
### Recipient events
#### recipient_invited
A recipient is sent an invitation: when their turn comes, when the sender resends it, when the envelope is reset, or when they request a fresh link.
`data`: `Recipient`
#### recipient_reminded
The envelope's reminder schedule re-sends a recipient's invitation.
`data`: `Recipient`
#### recipient_invite_failed
An invitation could not be sent, for example because the envelope was created with no_contact set.
`data`: `Recipient`
#### recipient_opened
A recipient opens the envelope. Repeat opens by the same recipient within 2 hours are not sent.
`data`: `Recipient`
#### recipient_disclosure_accepted
A recipient accepts the electronic signature disclosures.
`data`: `Recipient`
#### kba_event
Sent at each step of a recipient's knowledge-based authentication (KBA). data.event says which: questions were issued, a differentiator question was issued, verification passed, or it failed.
`data`: `KbaEvent`
#### recipient_auth_fail
A recipient has failed one of their authentication methods and can no longer continue. The sender can reset the envelope to let them try again.
`data`: `Recipient`
#### recipient_docs_downloaded
A recipient previews or downloads one of the envelope's documents.
`data`: `Recipient`
#### recipient_delegated
A recipient delegates their role to someone else, who is then invited in their place.
`data`: `RecipientDelegated`
#### recipient_submitted
A recipient finishes and submits their part of the envelope.
`data`: `Recipient`
#### recipient_declined
A recipient declines to sign. The envelope's status also becomes declined.
`data`: `Recipient`
#### recipient_updated
A recipient's status changes: they submit, they decline, or they are locked out after too many failed authentication attempts (sent with status failed).
`data`: `Recipient`
### Template events
#### template_created
A template is created.
`data`: `Template`
#### template_updated
A template's settings, fields, or roles change.
`data`: `Template`
#### template_used
An envelope is created from the template. An envelope_created event is sent at the same time.
`data`: `Template`
#### template_deleted
A template is deleted. The payload is the template as it was just before deletion.
`data`: `Template`
### Organization events
#### entitlement_used
A billable action is recorded, such as creating an envelope, sending an SMS invite, or a recipient being assigned an authentication method.
`data`: `EntitlementUsed`
#### organization_deleted
The organization is deleted. Includes a link to a backup of its data. Because the webhook settings are deleted along with the organization, this is attempted once and never retried.
`data`: `OrganizationDeleted`
### Payload types
```ts
interface Envelope extends EnvelopeBase {
// The sender's profile
profile: Profile | null;
organization: Organization | null;
documents: EnvelopeDocument[];
fields: EnvelopeField[];
recipients: Recipient[];
history_entries: EnvelopeHistoryEntry[];
}
interface EnvelopeBase {
id: string;
name: string | null;
status:
| 'pending'
| 'in progress'
| 'complete'
| 'declined'
| 'canceled'
| 'expired';
profile_id: string | null;
organization_id: string | null;
template_id: string | null;
sender_name: string | null;
sender_email: string | null;
visibility: 'private' | 'shared';
// True when Verdocs doesn't email or text recipients
no_contact: boolean;
// Reminder intervals, in milliseconds
initial_reminder: number | null;
followup_reminders: number | null;
max_reminder_days: number;
next_reminder: string | null;
expires_at: string | null;
canceled_at: string | null;
signed: boolean;
brand_key: string | null;
// Custom data supplied when the envelope was created
data: Record | null;
created_at: string;
updated_at: string;
}
interface CompletedEnvelope extends Omit {
documents: (EnvelopeDocument & {
// Presigned link to the signed PDF or certificate. Expires
// after 1 hour. null if the link couldn't be generated.
downloadUrl: string | null;
})[];
}
interface EnvelopeDocument {
id: string;
envelope_id: string;
template_document_id: string | null;
type: 'attachment' | 'certificate';
name: string;
order: number;
pages: number;
// Keyed by page number
page_sizes: Record | null;
// In bytes
size: number;
mime: string;
signed: boolean;
created_at: string;
updated_at: string;
}
interface EnvelopeField {
name: string;
envelope_id: string;
document_id: string;
role_name: string;
type: FieldType;
page: number;
x: number;
y: number;
width: number;
height: number;
required: boolean;
readonly: boolean;
multiline: boolean;
prepared: boolean;
label: string | null;
placeholder: string | null;
default: string | null;
group: string | null;
validator: string | null;
// Dropdown choices
options: { id: string; label: string }[] | null;
settings: Record;
value: string | null;
is_valid: boolean;
// Set on attachment fields once a file is uploaded
file_name: string | null;
file_size: number | null;
file_mime: string | null;
file_key: string | null;
}
// In PDF points
interface PageSize {
width: number;
height: number;
rotation: number;
}
type FieldType =
| 'signature'
| 'initial'
| 'checkbox'
| 'radio'
| 'textbox'
| 'textarea'
| 'date'
| 'timestamp'
| 'dropdown'
| 'attachment'
| 'payment';
interface Recipient {
envelope_id: string;
// Unique within the envelope
role_name: string;
profile_id: string | null;
status:
| 'pending'
| 'invited'
| 'opened'
| 'signed'
| 'submitted'
| 'declined'
| 'canceled'
| 'failed';
type: 'signer' | 'cc' | 'approver';
email: string | null;
phone: string | null;
full_name: string | null;
first_name: string | null;
last_name: string | null;
address: string | null;
city: string | null;
state: string | null;
zip: string | null;
// Lower sequences act first. Equal sequences act together.
sequence: number;
order: number;
message: string | null;
// Whether this recipient may delegate to someone else
delegator: boolean;
delegated_to: string | null;
delegated_from: string | null;
claimed: boolean;
// Whether the recipient accepted the e-signing disclosures
agreed: boolean;
disclosures: string | null;
disclosures_accepted_at: string | null;
name_locked: boolean;
passcode: string | null;
auth_methods:
| ('passcode' | 'email' | 'sms' | 'kba' | 'id')[]
| null;
// Progress per auth method, e.g. { "passcode": "complete" }
auth_method_states: Record | null;
// The auth method the recipient must complete next
auth_step: string | null;
key_used_to_conclude: string | null;
last_reminder: number;
last_attempt_at: string | null;
timezone: string | null;
locale: string | null;
created_at: string;
updated_at: string;
}
interface EnvelopeHistoryEntry {
id: string;
envelope_id: string;
// Set for recipient events
role_name: string | null;
// e.g. 'recipient:invited' or 'recipient:submitted'
event: string;
// e.g. the channel an invite went out on: 'mail' or 'sms'
event_detail: string | null;
created_at: string;
}
interface Profile {
id: string;
user_id: string | null;
organization_id: string;
first_name: string | null;
last_name: string | null;
email: string | null;
phone: string | null;
picture: string | null;
timezone: string | null;
locale: string | null;
current: boolean;
permissions: string[];
roles: string[];
plans: string[];
created_at: string;
updated_at: string;
}
interface Organization {
id: string;
name: string;
parent_id: string | null;
slug: string | null;
url: string | null;
address: string | null;
address2: string | null;
phone: string | null;
contact_email: string | null;
full_logo_url: string | null;
thumbnail_url: string | null;
primary_color: string | null;
secondary_color: string | null;
style_overrides: string | null;
disclaimer: string | null;
terms_use_url: string | null;
privacy_policy_url: string | null;
powered_by_label: string | null;
powered_by_url: string | null;
default_brand_id: string | null;
separate_cert: boolean | null;
hipaa_complaint: boolean | null;
deletion_protected: boolean;
timezone: string | null;
locale: string | null;
data: Record | null;
pipeline_settings: Record | null;
created_at: string;
updated_at: string;
}
interface Template {
id: string;
name: string;
description: string | null;
profile_id: string;
organization_id: string;
// Whose profile this template's envelopes are sent from
sender: 'envelope_creator' | 'template_owner';
visibility: 'private' | 'shared' | 'public';
is_personal: boolean;
is_public: boolean;
is_sendable: boolean;
tags: string[];
// Custom data stored on the template
data: Record | null;
// Default reminder intervals for envelopes, in milliseconds
initial_reminder: number | null;
followup_reminders: number | null;
max_reminder_days: number;
// Number of envelopes created from this template
counter: number;
star_counter: number;
last_used_at: string | null;
created_at: string;
updated_at: string;
documents: TemplateDocument[];
fields: TemplateField[];
roles: TemplateRole[];
}
interface TemplateDocument {
id: string;
template_id: string;
name: string;
order: number;
pages: number;
// Keyed by page number
page_sizes: Record | null;
// In bytes
size: number;
mime: string;
created_at: string;
updated_at: string;
}
interface TemplateField {
name: string;
template_id: string;
document_id: string;
role_name: string;
type: FieldType;
page: number;
x: number;
y: number;
width: number;
height: number;
required: boolean;
readonly: boolean;
multiline: boolean;
label: string | null;
placeholder: string | null;
default: string | null;
group: string | null;
validator: string | null;
// Dropdown choices
options: { id: string; label: string }[] | null;
settings: Record;
}
interface TemplateRole {
template_id: string;
name: string;
type: 'signer' | 'cc' | 'approver';
full_name: string | null;
first_name: string | null;
last_name: string | null;
email: string | null;
phone: string | null;
message: string | null;
sequence: number;
order: number;
delegator: boolean;
name_locked: boolean;
}
interface RecipientDelegated {
// The delegating recipient, as it was just before
delegator: Recipient;
// The new recipient. role_name is 'delegated_by_'.
recipient: Recipient;
// The envelope as it was just before delegating
envelope: Envelope;
}
interface KbaEvent {
event:
| 'kba_questions'
| 'kba_differentiator'
| 'kba_successful'
| 'kba_failed';
organization_id: string;
recipient: Recipient;
// The verification provider's result, minus its questions
response: KbaResponse;
}
interface KbaResponse {
'id-number': number;
results: { key: string; message: string };
'summary-result': { key: string; message: string };
'iq-summary-result'?: 'pass' | 'fail';
'idliveq-result'?: { key: string; message: string };
'idliveq-error'?: { key: string; message: string };
qualifiers?: { qualifier: { key: string; message: string }[] };
'answers-received'?: string;
}
interface EntitlementUsed {
organization_id: string;
usage_type:
| 'envelope'
| 'envelope_canceled'
| 'envelope_expired'
| 'template'
| 'sms_invite'
| 'auth_passcode'
| 'auth_email'
| 'auth_sms'
| 'auth_kba'
| 'auth_id';
// Template ID for 'template', otherwise the envelope ID
object_id: string;
}
interface OrganizationDeleted {
event: 'organization_deleted';
organization_id: string;
organization_name: string;
deleted_at: string;
// Presigned link to a zip backup of the organization's data
backup_url: string;
// When backup_url stops working, 14 days after deletion
backup_expires_at: string;
}
```
# Endpoints (/docs/reference/SDK/languages/endpoints)
# Getting Started (/docs/reference/SDK/languages/getting-started)
# Helpers (/docs/reference/SDK/languages/helpers)
# Components (/docs/reference/SDK/web/components)
# Get Started (/docs/reference/SDK/web/get-started)
The Verdocs Web SDK provides wrappers that make it easy to import our components into your project. These wrappers provide strong typing and code-completion for your IDE while building user interfaces with our components.
### Installation [#installation]
Begin by installing the Verdocs Web SDK in your project:
```bash
# NPM
npm i -S @verdocs/web-sdk
# Yarn
yarn add @verdocs/web-sdk
# PNPM
pnpm add @verdocs/web-sdk
```
## React [#react]
React developers should use our React-specific SDK. As of React v18, Web components are supported but [with some
caveats](https://custom-elements-everywhere.com/). Our React-specific SDK provides a more seamless integration.
## Usage [#usage]
React
Vue
# Web SDK (/docs/reference/SDK/web)
Web Components vs IFRAMEs
We recomend using Web components over IFRAMEs for three reasons:
1. *IFRAMEs are hard to style.* Generally, you can only make alterations that the developer specifically provided options for. In contrast, Web Components can be styled with CSS just like any other HTML element, making it much easier to achieve the look and feel you want.
2. *IFRAMEs are harder to control.* In modern browsers, they must channel events and callbacks through mechanisms like postMessage(), limiting the amount of control you have over the component's behavior and visibility into its status.
3. *Web Components are faster.* They are bundled into your Web app's distribution files and load immediately when each page is displayed, where IFRAMEs are loaded remotely in a second step.
# Styling (/docs/reference/SDK/web/styling)
Learn By Doing
In most cases, you do not need to read any documentation or memorize lists of class names or patterns. Every Verdocs component has Verdocs-prefixed classnames to prevent conflicts with other components in host applications.
For example, suppose you want to change the color of the header/toolbar shown when viewing an Envelope from our default of dark-blue (`#33354C`) to one of your brand colors:
If you inspect the header you can see the classname or ID that controls this color. In this case an ID was applied because some applications may choose to move the toolbar entirely (such as to make it float):
Changing the background to a new color such as (`#1b7591`) is as simple as including the following CSS anywhere in your application:
```css
#verdocs-view-header {
background-color: #1b7591 !important;
}
```
Be sure to set a higher specificity to ensure your overrides take effect, either via the `!important` operator or with additional ID/class specifiers,
such as `#my-view #verdocs-view-header ...`.
When you are done, you should see the following:
## CSS Variables [#css-variables]
Class and ID rules can reach anything, but the handful of things most apps want to change (the brand color, fonts, corner radius, and field styling) are also exposed as CSS variables, so one rule restyles every component at once. These are the same variables a brand's published styles set, which is how the hosted signing page picks up your brand. Set them on `:root` so every component sees them:
```css
:root {
--verdocs-primary-color: #654dcb;
--verdocs-primary-font: Georgia, serif;
--verdocs-button-radius: 999px;
--verdocs-field-background: #8dc63f1a;
}
```
| Variable | What it controls |
| ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `--verdocs-primary-color` | Primary buttons, dialog OK buttons, and other accents. |
| `--verdocs-primary-color-hover` | Hover state for the same. |
| `--verdocs-primary-font` | The font stack used across the components. |
| `--verdocs-body-color` | Body text color. |
| `--verdocs-link-color` | Link color. |
| `--verdocs-button-radius` | Corner radius on buttons. |
| `--verdocs-button-secondary-color`, `--verdocs-button-secondary-border`, `--verdocs-button-secondary-hover-bg` | Secondary buttons. |
| `--verdocs-button-disabled-color`, `--verdocs-button-disabled-bg` | Disabled buttons. |
| `--verdocs-field-background`, `--verdocs-field-border`, `--verdocs-field-radius`, `--verdocs-field-text-color` | Signing fields. |
| `--verdocs-required-field-border` | Border color on required fields. Takes a bare color, not a full border. |
| `--verdocs-checkbox-color` | Checkbox and radio fill. |
| `--verdocs-dialog-radius`, `--verdocs-dialog-title-color`, `--verdocs-dialog-title-weight`, `--verdocs-dialog-content-color` | Dialogs such as the disclosure and completion prompts. |
Anything not in this list is still one inspect-and-override away with the approach above.
# Create API key (/docs/reference/Rest-API/api-docs/api-keys/createApiKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/api-keys
`POST https://api.verdocs.com/v2/api-keys`
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string, required): A name used to identify the key in the Verdocs Web App.
- `profile_id` (string, uuid, required): The profile ID that calls made using the key will act as.
- `global_admin` (boolean): If true, the key has full access to the organization, overriding the permissions of its assigned profile. Defaults to false.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IApiKey`
- `client_id` (string, required): Only returned when a key is created or rotated.
- `client_secret` (string): Only returned when a key is created or rotated.
- `created_at` (string, required): Creation date/time.
- `global_admin` (boolean, required): If set, the key has full access to the organization, overriding the permissions of its assigned profile.
- `last_used_at` (string, required): Last date/time the key was used.
- `name` (string, required): User-provided name for the key. Only used for identification.
- `organization_id` (string, required): Organization the key is connected to.
- `profile_id` (string, required): The profile calls made with this key will act as. Ignored if global_admin is set.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/api-keys" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete API key (/docs/reference/Rest-API/api-docs/api-keys/deleteApiKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/api-keys/{client_id}
`DELETE https://api.verdocs.com/v2/api-keys/{client_id}`
### Path parameters
- `client_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `TBasicResponse`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/api-keys/CLIENT_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get API keys (/docs/reference/Rest-API/api-docs/api-keys/getApiKeys)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/api-keys
`GET https://api.verdocs.com/v2/api-keys`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IApiKey[]`
- `client_id` (string, required): Only returned when a key is created or rotated.
- `client_secret` (string): Only returned when a key is created or rotated.
- `created_at` (string, required): Creation date/time.
- `global_admin` (boolean, required): If set, the key has full access to the organization, overriding the permissions of its assigned profile.
- `last_used_at` (string, required): Last date/time the key was used.
- `name` (string, required): User-provided name for the key. Only used for identification.
- `organization_id` (string, required): Organization the key is connected to.
- `profile_id` (string, required): The profile calls made with this key will act as. Ignored if global_admin is set.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/api-keys" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Rotate API key (/docs/reference/Rest-API/api-docs/api-keys/rotateApiKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/api-keys/{client_id}/rotate
`POST https://api.verdocs.com/v2/api-keys/{client_id}/rotate`
### Path parameters
- `client_id` (string, uuid, required): The client ID of the key to rotate.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IApiKey`
- `client_id` (string, required): Only returned when a key is created or rotated.
- `client_secret` (string): Only returned when a key is created or rotated.
- `created_at` (string, required): Creation date/time.
- `global_admin` (boolean, required): If set, the key has full access to the organization, overriding the permissions of its assigned profile.
- `last_used_at` (string, required): Last date/time the key was used.
- `name` (string, required): User-provided name for the key. Only used for identification.
- `organization_id` (string, required): Organization the key is connected to.
- `profile_id` (string, required): The profile calls made with this key will act as. Ignored if global_admin is set.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/api-keys/CLIENT_ID/rotate" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update API key (/docs/reference/Rest-API/api-docs/api-keys/updateApiKey)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/api-keys/{client_id}
`PATCH https://api.verdocs.com/v2/api-keys/{client_id}`
### Path parameters
- `client_id` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string): New name for the API key.
- `profile_id` (string, uuid): New profile ID that calls made using the key will act as.
- `global_admin` (boolean): If true, the key has full access to the organization, overriding the permissions of its assigned profile.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IApiKey`
- `client_id` (string, required): Only returned when a key is created or rotated.
- `client_secret` (string): Only returned when a key is created or rotated.
- `created_at` (string, required): Creation date/time.
- `global_admin` (boolean, required): If set, the key has full access to the organization, overriding the permissions of its assigned profile.
- `last_used_at` (string, required): Last date/time the key was used.
- `name` (string, required): User-provided name for the key. Only used for identification.
- `organization_id` (string, required): Organization the key is connected to.
- `profile_id` (string, required): The profile calls made with this key will act as. Ignored if global_admin is set.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/api-keys/CLIENT_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Authenticate (/docs/reference/Rest-API/api-docs/authentication/authenticate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/oauth2/token
`POST https://api.verdocs.com/v2/oauth2/token`
### Request body
Content type `application/json`, required. Body Parameters.
- `grant_type` (login, required): The type of grant to request. API callers should nearly always use 'client_credentials'. Third-party OAuth2 integrations use 'authorization_code'. The mfa-otp and mfa-recovery-code grants complete a sign-in that was answered with an 'mfa_required' challenge, and the login-code grant completes a Google or Microsoft sign-in. One of: `"client_credentials"`, `"refresh_token"`, `"password"`, `"authorization_code"`, `"urn"`.
- `client_id` (string, uuid): If grant_type is client_credentials, refresh_token, or authorization_code, the client ID to use.
- `client_secret` (string, uuid): If grant_type is client_credentials or authorization_code, the secret key to use.
- `username` (string): If grant_type is password, the username to authenticate with.
- `password` (string): If grant_type is password, the password to authenticate with.
- `code` (string): If grant_type is authorization_code, the authorization code received from the authorize endpoint.
- `redirect_uri` (string, uri): If grant_type is authorization_code, must match the redirect_uri used in the authorize request.
- `mfa_token` (string): If grant_type is an MFA type, the token returned from the challenge.
- `otp` (string): If grant_type is an MFA-with-OTP type, the six-digit code from the user's authenticator.
- `recovery_code` (string): If grant_type is an MFA-with-recovery-code type, the backup code.
- `login_code` (string): If grant_type is a PKCE type, the login code from the IdP.
- `code_verifier` (string): If grant_type is is a PKCE type, the PKCE verifier from the challenge.
- `scope` (string): Optional scope to limit the auth token to. Do not specify this unless you are instructed to by a Verdocs Support rep.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IAuthenticateResponse`
- `refresh_token` (string): Only API key (client_credentials) sign-ins and their refreshes return a refresh token.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/oauth2/token" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Change the caller's password (/docs/reference/Rest-API/api-docs/authentication/changePassword)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/users/change-password
`POST https://api.verdocs.com/v2/users/change-password`
### Request body
Content type `application/json`, required. Body Parameters.
- `old_password` (string, required): Current password for the caller.
- `new_password` (string, required): New password to set for the caller. Must meet strength requirements.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/users/change-password" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get the caller's user record. (/docs/reference/Rest-API/api-docs/authentication/getMyUser)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/users/me
`GET https://api.verdocs.com/v2/users/me`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IUser`
- `appleId` (string, required): If set, the Apple account ID for the user. Set only for users logging in via Apple.
- `b2cId` (string, required): If set, the Azure B2C ID for the user. Generally set only for Teams/PowerAutomate users.
- `email` (string, required): Email address.
- `email_verified` (boolean, required): If true, the email has been verified in some way (e.g. OTP verification or trusted third party.
- `githubId` (string): If set, the Github account ID for the user. Set only for users logging in via Github.
- `googleId` (string, required): If set, the Google account ID for the user. Set only for users logging in via Google.
- `has_password` (boolean, required): Social-IdP accounts have no password set. Used to gate some front-end features like password-reset UI controls.
- `last_active_at` (string): When the user was last seen in any session. Only present for admins or owners.
- `locale` (string): The long-form timezone.
- `lock_reason` (string): Reason the account is locked. Only visible to admins or owners.
- `locked` (boolean): True if the account is locked, typically due to failed sign-in attempts. Only visible to admins or owners.
- `login_failures` (integer): Consecutive failed sign-in attempts. Only visible to admins or owners.
- `mfa_enabled` (boolean): True if the user has multi-factor authentication enrolled. Only present for admins or owners.
- `mfa_enrolled_at` (string): When multi-factor authentication was enrolled, if it is. Only present for admins or owners.
- `pass_hash` (string): Password hash, present only for type consistency. Marked optional, but will never be returned by the backend.
- `password_changed_at` (string, required): Last password-change datetime.
- `preferences` (string): Present only on the caller's own record from getMyUser, and null until something is set.
- `sign_in_providers` (string, required): Linked social IdP's if any.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/users/me" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Initiate an OAuth2 authorization code flow (/docs/reference/Rest-API/api-docs/authentication/getOAuth2AuthorizeUrl)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/oauth2/authorize
`GET https://api.verdocs.com/v2/oauth2/authorize`
### Query parameters
- `client_id` (string, uuid, required): The client ID of the registered OAuth2 application.
- `redirect_uri` (string, uri, required): The URI to redirect to after authorization. Must match a registered redirect URI for the application.
- `response_type` (string, required): Must be 'code' for authorization code flow. One of: `"code"`.
- `state` (string): An opaque value used to prevent CSRF attacks. Returned unchanged in the redirect.
- `scope` (string): Optional scope to request.
### Responses
#### 200: Success
Content type `application/json`.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/oauth2/authorize?param=value" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Begin a Google or Microsoft sign-in (/docs/reference/Rest-API/api-docs/authentication/getSocialLoginUrl)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/oauth2/social/{provider}/start
`GET https://api.verdocs.com/v2/oauth2/social/{provider}/start`
### Path parameters
- `provider` (string, required): The identity provider to sign in with. One of: `"google"`, `"microsoft"`.
### Query parameters
- `return_uri` (string, uri, required): Where to send the user after the provider returns. Must belong to a registered origin.
- `code_challenge` (string, required): The PKCE challenge, the base64url SHA-256 of the verifier the app keeps.
- `code_challenge_method` (string, required): Always 'S256'. One of: `"S256"`.
- `state` (string, required): An opaque value returned unchanged to the app, used to prevent CSRF attacks.
### Responses
#### 200: Success
Content type `application/json`.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/oauth2/social/PROVIDER/start?param=value" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get the identity providers enabled in this environment (/docs/reference/Rest-API/api-docs/authentication/getSocialProviders)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/oauth2/social/providers
`GET https://api.verdocs.com/v2/oauth2/social/providers`
### Responses
#### 200: Success
Content type `application/json`.
Type: `ISocialProviders`
The identity providers enabled in the current environment. Buttons for providers that are not enabled should be hidden, because their sign-in URLs will return 404.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/oauth2/social/providers" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Resend an email verification request for a "partially" authenticated user (authenticated, but not yet verified) (/docs/reference/Rest-API/api-docs/authentication/resendVerification)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/users/resend-verification
`POST https://api.verdocs.com/v2/users/resend-verification`
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/users/resend-verification" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Reset a password for a user (/docs/reference/Rest-API/api-docs/authentication/resetPassword)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/users/reset-password
`POST https://api.verdocs.com/v2/users/reset-password`
### Request body
Content type `application/json`, required. Body Parameters.
- `email` (string, required): Email address for the user account.
- `code` (string): To initiate a reset request, omit this field. To complete it, provide the emailed code received by the user.
- `new_password` (string): To initiate a reset request, omit this field. To complete it, provide the new password the user wishes to use.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/users/reset-password" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update the caller's preferences. (/docs/reference/Rest-API/api-docs/authentication/updateMyPreferences)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/users/me/preferences
`PATCH https://api.verdocs.com/v2/users/me/preferences`
### Request body
Content type `application/json`, required. Body Parameters.
- `template_builder` (string): The template builder to show. Set to null to reset to the default, `verdocs-build`. One of: `"build"`, `"builder"`.
- `high_contrast` (boolean): Draw Builder fields in high contrast. Set to null to follow the browser's contrast setting.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IUserPreferences`
Verdocs apps read the keys listed here. Your own apps may store others.
- `high_contrast` (boolean): Draw Builder fields in high contrast. Unset follows the browser's own contrast setting.
- `template_builder` (string): The template builder to show:.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/users/me/preferences" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Resend the email verification request if both the email and token are known. Used if the token is valid but has expired. (/docs/reference/Rest-API/api-docs/authentication/verifyEmail)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/users/verify
`POST https://api.verdocs.com/v2/users/verify`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IAuthenticateResponse`
- `refresh_token` (string): Only API key (client_credentials) sign-ins and their refreshes return a refresh token.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/users/verify" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Add app domain (/docs/reference/Rest-API/api-docs/brands/addBrandAppDomain)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organizations/{organizationid}/brands/{brandid}/app-domain
`POST https://api.verdocs.com/v2/organizations/{organizationid}/brands/{brandid}/app-domain`
### Path parameters
- `organizationid` (string, required)
- `brandid` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `subdomain` (string, required): The subdomain to serve Verdocs from (e.g. sign.acme.com).
### Responses
#### 200: Success
Content type `application/json`.
Type: `IBrand`
- `email_display_name` (string, required): @deprecated. Use email_sender_name instead.
- `locale` (string): The long-form timezone.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands/BRANDID/app-domain" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Add email domain (/docs/reference/Rest-API/api-docs/brands/addBrandEmailDomain)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organizations/{organizationid}/brands/{brandid}/email-domain
`POST https://api.verdocs.com/v2/organizations/{organizationid}/brands/{brandid}/email-domain`
### Path parameters
- `organizationid` (string, required)
- `brandid` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `subdomain` (string, required): The email subdomain (e.g. notify.acme.com).
- `local_part` (string, required): The local part of the from address (e.g. notifications).
### Responses
#### 200: Success
Content type `application/json`.
Type: `IBrand`
- `email_display_name` (string, required): @deprecated. Use email_sender_name instead.
- `locale` (string): The long-form timezone.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands/BRANDID/email-domain" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create brand (/docs/reference/Rest-API/api-docs/brands/createBrand)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organizations/{organizationid}/brands
`POST https://api.verdocs.com/v2/organizations/{organizationid}/brands`
### Path parameters
- `organizationid` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `key` (string, required): A unique key for the brand (lowercase alphanumeric + hyphens).
- `timezone` (string): Define the long-form timezone.
- `locale` (string): Define the locale code.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IBrand`
- `email_display_name` (string, required): @deprecated. Use email_sender_name instead.
- `locale` (string): The long-form timezone.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete brand (/docs/reference/Rest-API/api-docs/brands/deleteBrand)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organizations/{organizationid}/brands/{brandid}
`DELETE https://api.verdocs.com/v2/organizations/{organizationid}/brands/{brandid}`
### Path parameters
- `organizationid` (string, required)
- `brandid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands/BRANDID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get brand (/docs/reference/Rest-API/api-docs/brands/getBrand)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organizationid}/brands/{brandid}
`GET https://api.verdocs.com/v2/organizations/{organizationid}/brands/{brandid}`
### Path parameters
- `organizationid` (string, required)
- `brandid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IBrand`
- `email_display_name` (string, required): @deprecated. Use email_sender_name instead.
- `locale` (string): The long-form timezone.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands/BRANDID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# List brands (/docs/reference/Rest-API/api-docs/brands/getBrands)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organizationid}/brands
`GET https://api.verdocs.com/v2/organizations/{organizationid}/brands`
### Path parameters
- `organizationid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IBrand[]`
- `email_display_name` (string, required): @deprecated. Use email_sender_name instead.
- `locale` (string): The long-form timezone.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Remove app domain (/docs/reference/Rest-API/api-docs/brands/removeBrandAppDomain)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organizations/{organizationid}/brands/{brandid}/app-domain
`DELETE https://api.verdocs.com/v2/organizations/{organizationid}/brands/{brandid}/app-domain`
### Path parameters
- `organizationid` (string, required)
- `brandid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IBrand`
- `email_display_name` (string, required): @deprecated. Use email_sender_name instead.
- `locale` (string): The long-form timezone.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands/BRANDID/app-domain" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Remove email domain (/docs/reference/Rest-API/api-docs/brands/removeBrandEmailDomain)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organizations/{organizationid}/brands/{brandid}/email-domain
`DELETE https://api.verdocs.com/v2/organizations/{organizationid}/brands/{brandid}/email-domain`
### Path parameters
- `organizationid` (string, required)
- `brandid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IBrand`
- `email_display_name` (string, required): @deprecated. Use email_sender_name instead.
- `locale` (string): The long-form timezone.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands/BRANDID/email-domain" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update brand thumbnail (/docs/reference/Rest-API/api-docs/brands/updateBrandThumbnail)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/organizations/{organizationid}/brands/{brandid}
`PATCH https://api.verdocs.com/v2/organizations/{organizationid}/brands/{brandid}`
### Path parameters
- `organizationid` (string, required)
- `brandid` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `thumbnail` (string, binary, required): Form-encoded file to upload.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IBrand`
- `email_display_name` (string, required): @deprecated. Use email_sender_name instead.
- `locale` (string): The long-form timezone.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands/BRANDID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Verify app domain (/docs/reference/Rest-API/api-docs/brands/verifyBrandAppDomain)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organizations/{organizationid}/brands/{brandid}/app-domain/verify
`POST https://api.verdocs.com/v2/organizations/{organizationid}/brands/{brandid}/app-domain/verify`
### Path parameters
- `organizationid` (string, required)
- `brandid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IBrand`
- `email_display_name` (string, required): @deprecated. Use email_sender_name instead.
- `locale` (string): The long-form timezone.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands/BRANDID/app-domain/verify" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Verify email domain (/docs/reference/Rest-API/api-docs/brands/verifyBrandEmailDomain)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organizations/{organizationid}/brands/{brandid}/email-domain/verify
`POST https://api.verdocs.com/v2/organizations/{organizationid}/brands/{brandid}/email-domain/verify`
### Path parameters
- `organizationid` (string, required)
- `brandid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IBrand`
- `email_display_name` (string, required): @deprecated. Use email_sender_name instead.
- `locale` (string): The long-form timezone.
- `timezone` (string): The locale code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/brands/BRANDID/email-domain/verify" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Apply a data catalog update (/docs/reference/Rest-API/api-docs/data-catalogs/applyDataCatalogUpdate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organizations/{organizationid}/data-catalogs/{catalogid}/update
`POST https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}/update`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `resolutions` (object): By key, "source" or "local".
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalog`
- `created_at` (string, required): When the catalog was created.
- `description` (string, required): What the catalog is for.
- `entries` (string): The entries (when getting one catalog). Members see live entries and their own proposals; admins see every proposal.
- `entry_count` (integer): How many live entries it has (in lists).
- `has_unreleased_changes` (boolean): For a shared or previously released catalog, whether its live entries differ from its latest release.
- `id` (string, required): The catalog's ID.
- `is_default` (boolean): Whether this is the organization's default catalog.
- `latest_version` (integer, required): The newest released version, 0 until the first release.
- `name` (string, required): The catalog's name.
- `organization_id` (string, required): The organization that owns it.
- `public_version` (string, required): The version Verdocs approved for the public marketplace, null when it isn't listed there.
- `sharing` (string, required): "shared" makes released versions available to every organization below this one.
- `source` (string, required): How it started: from scratch, from an import, or from the marketplace.
- `source_catalog_id` (string, required): For a catalog imported from the marketplace, the catalog it came from.
- `source_version` (string, required): The source version this catalog was imported or last updated from.
- `submission` (string): The newest public marketplace submission (when getting one catalog), null if there's never been one.
- `update_available` (boolean): For an imported catalog, whether its source has released a newer version.
- `updated_at` (string, required): When the catalog last changed.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID/update" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create a data catalog (/docs/reference/Rest-API/api-docs/data-catalogs/createDataCatalog)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organizations/{organizationid}/data-catalogs
`POST https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs`
### Path parameters
- `organizationid` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string): Required unless importing from the marketplace, where it defaults to the source's name.
- `description` (string): What the catalog is for.
- `import` (IDataCatalogImport): Create the entries from a JSON sample, JSON Schema, or CSV header row.
- `content` (string, required): The sample or schema, as an object or a JSON string. A CSV header row is a string, and only its first line is read.
- `format` (string, required): A sample payload (nested objects become dotted keys), a JSON Schema, or a CSV header row (each column becomes a text key).
- `keep_examples` (boolean): Use the sample's values (or the schema's examples) as entry examples. Defaults to true.
- `entries` (ISaveDataCatalogEntry[]): The entries to start with. Send one of import, entries, or from_catalog_id.
- `description` (string): What the value is.
- `example` (string): An example value.
- `key` (string, required): Letters, digits, "_", and "-", with "." between levels.
- `label` (string, required): What template owners see for this key.
- `options` (string): For a choice, the accepted values.
- `sensitive` (boolean): Keeps the example out of MCP answers and AI prompts. Defaults to false.
- `type` (string): Defaults to text. A choice needs options.
- `from_catalog_id` (string): Import a copy of a marketplace catalog's newest version.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalog`
- `created_at` (string, required): When the catalog was created.
- `description` (string, required): What the catalog is for.
- `entries` (string): The entries (when getting one catalog). Members see live entries and their own proposals; admins see every proposal.
- `entry_count` (integer): How many live entries it has (in lists).
- `has_unreleased_changes` (boolean): For a shared or previously released catalog, whether its live entries differ from its latest release.
- `id` (string, required): The catalog's ID.
- `is_default` (boolean): Whether this is the organization's default catalog.
- `latest_version` (integer, required): The newest released version, 0 until the first release.
- `name` (string, required): The catalog's name.
- `organization_id` (string, required): The organization that owns it.
- `public_version` (string, required): The version Verdocs approved for the public marketplace, null when it isn't listed there.
- `sharing` (string, required): "shared" makes released versions available to every organization below this one.
- `source` (string, required): How it started: from scratch, from an import, or from the marketplace.
- `source_catalog_id` (string, required): For a catalog imported from the marketplace, the catalog it came from.
- `source_version` (string, required): The source version this catalog was imported or last updated from.
- `submission` (string): The newest public marketplace submission (when getting one catalog), null if there's never been one.
- `update_available` (boolean): For an imported catalog, whether its source has released a newer version.
- `updated_at` (string, required): When the catalog last changed.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete a data catalog (/docs/reference/Rest-API/api-docs/data-catalogs/deleteDataCatalog)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organizations/{organizationid}/data-catalogs/{catalogid}
`DELETE https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete a data catalog entry (/docs/reference/Rest-API/api-docs/data-catalogs/deleteDataCatalogEntry)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organizations/{organizationid}/data-catalogs/{catalogid}/entries/{key}
`DELETE https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}/entries/{key}`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
- `key` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID/entries/KEY" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get a data catalog (/docs/reference/Rest-API/api-docs/data-catalogs/getDataCatalog)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organizationid}/data-catalogs/{catalogid}
`GET https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalog`
- `created_at` (string, required): When the catalog was created.
- `description` (string, required): What the catalog is for.
- `entries` (string): The entries (when getting one catalog). Members see live entries and their own proposals; admins see every proposal.
- `entry_count` (integer): How many live entries it has (in lists).
- `has_unreleased_changes` (boolean): For a shared or previously released catalog, whether its live entries differ from its latest release.
- `id` (string, required): The catalog's ID.
- `is_default` (boolean): Whether this is the organization's default catalog.
- `latest_version` (integer, required): The newest released version, 0 until the first release.
- `name` (string, required): The catalog's name.
- `organization_id` (string, required): The organization that owns it.
- `public_version` (string, required): The version Verdocs approved for the public marketplace, null when it isn't listed there.
- `sharing` (string, required): "shared" makes released versions available to every organization below this one.
- `source` (string, required): How it started: from scratch, from an import, or from the marketplace.
- `source_catalog_id` (string, required): For a catalog imported from the marketplace, the catalog it came from.
- `source_version` (string, required): The source version this catalog was imported or last updated from.
- `submission` (string): The newest public marketplace submission (when getting one catalog), null if there's never been one.
- `update_available` (boolean): For an imported catalog, whether its source has released a newer version.
- `updated_at` (string, required): When the catalog last changed.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Preview a marketplace catalog (/docs/reference/Rest-API/api-docs/data-catalogs/getDataCatalogListing)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organizationid}/data-catalog-marketplace/{catalogid}
`GET https://api.verdocs.com/v2/organizations/{organizationid}/data-catalog-marketplace/{catalogid}`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalogListingPreview`
A marketplace catalog with the keys of its newest released version.
- `description` (string, required): What the catalog is for.
- `entries` (string, required): The keys an import would copy.
- `id` (string, required): The catalog's ID, for createDataCatalog's from_catalog_id.
- `imported` (boolean, required): Whether this organization already imported it.
- `key_count` (integer, required): How many keys that version has.
- `listing` (string, required): How it's offered: "shared" by an organization above this one, or "public" in the marketplace Verdocs reviews.
- `name` (string, required): The catalog's name.
- `publisher` (string, required): The organization that publishes it.
- `released_at` (string, required): When that version was released.
- `version` (integer, required): The version this organization can import: the newest release when shared, the approved version when public.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalog-marketplace/CATALOGID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Browse the data catalog marketplace (/docs/reference/Rest-API/api-docs/data-catalogs/getDataCatalogMarketplace)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organizationid}/data-catalog-marketplace
`GET https://api.verdocs.com/v2/organizations/{organizationid}/data-catalog-marketplace`
### Path parameters
- `organizationid` (string, required)
### Query parameters
- `q` (string): Text to search catalog names, descriptions, publishers, and keys for.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalogListing[]`
- `description` (string, required): What the catalog is for.
- `id` (string, required): The catalog's ID, for createDataCatalog's from_catalog_id.
- `imported` (boolean, required): Whether this organization already imported it.
- `key_count` (integer, required): How many keys that version has.
- `listing` (string, required): How it's offered: "shared" by an organization above this one, or "public" in the marketplace Verdocs reviews.
- `name` (string, required): The catalog's name.
- `publisher` (string, required): The organization that publishes it.
- `released_at` (string, required): When that version was released.
- `version` (integer, required): The version this organization can import: the newest release when shared, the approved version when public.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalog-marketplace?param=value" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Review a data catalog update (/docs/reference/Rest-API/api-docs/data-catalogs/getDataCatalogUpdate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organizationid}/data-catalogs/{catalogid}/update
`GET https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}/update`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalogUpdate`
- `changes` (string, required): What applying the update would change. Empty when there's nothing to apply.
- `from_version` (integer): The source version this catalog is on.
- `to_version` (integer): The source's newest version.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID/update" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# List data catalog versions (/docs/reference/Rest-API/api-docs/data-catalogs/getDataCatalogVersions)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organizationid}/data-catalogs/{catalogid}/versions
`GET https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}/versions`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalogVersion[]`
- `catalog_id` (string, required): The catalog it belongs to.
- `created_at` (string, required): When it was released.
- `entries` (string, required): The catalog's live entries when the version was released.
- `id` (string, required): The version's ID.
- `notes` (string, required): What changed in this version.
- `released_by` (string, required): The profile that released it.
- `version` (integer, required): The version number, starting at 1.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID/versions" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# List data catalogs (/docs/reference/Rest-API/api-docs/data-catalogs/getDataCatalogs)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organizationid}/data-catalogs
`GET https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs`
### Path parameters
- `organizationid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalog[]`
- `created_at` (string, required): When the catalog was created.
- `description` (string, required): What the catalog is for.
- `entries` (string): The entries (when getting one catalog). Members see live entries and their own proposals; admins see every proposal.
- `entry_count` (integer): How many live entries it has (in lists).
- `has_unreleased_changes` (boolean): For a shared or previously released catalog, whether its live entries differ from its latest release.
- `id` (string, required): The catalog's ID.
- `is_default` (boolean): Whether this is the organization's default catalog.
- `latest_version` (integer, required): The newest released version, 0 until the first release.
- `name` (string, required): The catalog's name.
- `organization_id` (string, required): The organization that owns it.
- `public_version` (string, required): The version Verdocs approved for the public marketplace, null when it isn't listed there.
- `sharing` (string, required): "shared" makes released versions available to every organization below this one.
- `source` (string, required): How it started: from scratch, from an import, or from the marketplace.
- `source_catalog_id` (string, required): For a catalog imported from the marketplace, the catalog it came from.
- `source_version` (string, required): The source version this catalog was imported or last updated from.
- `submission` (string): The newest public marketplace submission (when getting one catalog), null if there's never been one.
- `update_available` (boolean): For an imported catalog, whether its source has released a newer version.
- `updated_at` (string, required): When the catalog last changed.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Release a data catalog version (/docs/reference/Rest-API/api-docs/data-catalogs/releaseDataCatalogVersion)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organizations/{organizationid}/data-catalogs/{catalogid}/versions
`POST https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}/versions`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `notes` (string): What changed in this version.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalogVersion`
- `catalog_id` (string, required): The catalog it belongs to.
- `created_at` (string, required): When it was released.
- `entries` (string, required): The catalog's live entries when the version was released.
- `id` (string, required): The version's ID.
- `notes` (string, required): What changed in this version.
- `released_by` (string, required): The profile that released it.
- `version` (integer, required): The version number, starting at 1.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID/versions" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Save data catalog entries (/docs/reference/Rest-API/api-docs/data-catalogs/saveDataCatalogEntries)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organizations/{organizationid}/data-catalogs/{catalogid}/entries
`POST https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}/entries`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `entries` (ISaveDataCatalogEntry[], required): Up to 500 entries. Each key may appear only once.
- `description` (string): What the value is.
- `example` (string): An example value.
- `key` (string, required): Letters, digits, "_", and "-", with "." between levels.
- `label` (string, required): What template owners see for this key.
- `options` (string): For a choice, the accepted values.
- `sensitive` (boolean): Keeps the example out of MCP answers and AI prompts. Defaults to false.
- `type` (string): Defaults to text. A choice needs options.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalogEntry[]`
- `catalog_id` (string, required): The catalog the entry belongs to.
- `created_at` (string, required): When the entry was created.
- `description` (string, required): What the value is.
- `example` (string, required): An example value, real or made up, as the organization chose.
- `id` (string, required): The entry's ID.
- `key` (string, required): Matches the data_key on template and envelope fields, such as "applicant.full_name".
- `label` (string, required): What template owners see for this key, such as "Applicant name".
- `options` (string, required): For a choice, the accepted values.
- `proposed_by` (string, required): The profile that proposed the entry, if a member did.
- `sensitive` (boolean, required): Keeps the example out of MCP answers and AI prompts.
- `source_entry` (string, required): For an entry imported from the marketplace, the source's version of it, used to review updates.
- `status` (string, required): "active" entries can be used; "proposed" entries wait for an admin to approve them.
- `type` (string, required): What a caller sends for this key.
- `updated_at` (string, required): When the entry last changed.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID/entries" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Submit a data catalog to the public marketplace (/docs/reference/Rest-API/api-docs/data-catalogs/submitDataCatalog)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organizations/{organizationid}/data-catalogs/{catalogid}/submissions
`POST https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}/submissions`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `notes` (string): What reviewers should know about this catalog.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalogSubmission`
A request to list one released version of a catalog in the public marketplace, and Verdocs' decision on it.
- `notes` (string, required): What the submitter wanted reviewers to know.
- `review_notes` (string, required): The reason for a rejection.
- `reviewed_at` (string, required): When Verdocs decided.
- `submitted_by` (string, required): The profile that submitted it.
- `version` (integer, required): The released version under review.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID/submissions" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update a data catalog (/docs/reference/Rest-API/api-docs/data-catalogs/updateDataCatalog)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/organizations/{organizationid}/data-catalogs/{catalogid}
`PATCH https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string): The catalog's name.
- `description` (string): What the catalog is for.
- `sharing` (string): "shared" makes released versions available to every organization below this one. One of: `"private"`, `"shared"`.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalog`
- `created_at` (string, required): When the catalog was created.
- `description` (string, required): What the catalog is for.
- `entries` (string): The entries (when getting one catalog). Members see live entries and their own proposals; admins see every proposal.
- `entry_count` (integer): How many live entries it has (in lists).
- `has_unreleased_changes` (boolean): For a shared or previously released catalog, whether its live entries differ from its latest release.
- `id` (string, required): The catalog's ID.
- `is_default` (boolean): Whether this is the organization's default catalog.
- `latest_version` (integer, required): The newest released version, 0 until the first release.
- `name` (string, required): The catalog's name.
- `organization_id` (string, required): The organization that owns it.
- `public_version` (string, required): The version Verdocs approved for the public marketplace, null when it isn't listed there.
- `sharing` (string, required): "shared" makes released versions available to every organization below this one.
- `source` (string, required): How it started: from scratch, from an import, or from the marketplace.
- `source_catalog_id` (string, required): For a catalog imported from the marketplace, the catalog it came from.
- `source_version` (string, required): The source version this catalog was imported or last updated from.
- `submission` (string): The newest public marketplace submission (when getting one catalog), null if there's never been one.
- `update_available` (boolean): For an imported catalog, whether its source has released a newer version.
- `updated_at` (string, required): When the catalog last changed.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update a data catalog entry (/docs/reference/Rest-API/api-docs/data-catalogs/updateDataCatalogEntry)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/organizations/{organizationid}/data-catalogs/{catalogid}/entries/{key}
`PATCH https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}/entries/{key}`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
- `key` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `label` (string): What template owners see for this key.
- `type` (string): What a caller sends for this key. One of: `"text"`, `"date"`, `"boolean"`, `"choice"`.
- `description` (string): What the value is.
- `example` (string): An example value.
- `options` (IDataCatalogOption[]): For a choice, the accepted values.
- `label` (string, required): What the signer sees for this choice.
- `value` (string, required): What to send in prefill_data. The label is accepted too.
- `sensitive` (boolean): Keeps the example out of MCP answers and AI prompts.
- `status` (string): Set to "active" to approve a proposal. One of: `"active"`.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalogEntry`
An entry's content, as versions freeze it and update reviews compare it.
- `catalog_id` (string, required): The catalog the entry belongs to.
- `created_at` (string, required): When the entry was created.
- `description` (string, required): What the value is.
- `example` (string, required): An example value, real or made up, as the organization chose.
- `id` (string, required): The entry's ID.
- `key` (string, required): Matches the data_key on template and envelope fields, such as "applicant.full_name".
- `label` (string, required): What template owners see for this key, such as "Applicant name".
- `options` (string, required): For a choice, the accepted values.
- `proposed_by` (string, required): The profile that proposed the entry, if a member did.
- `sensitive` (boolean, required): Keeps the example out of MCP answers and AI prompts.
- `source_entry` (string, required): For an entry imported from the marketplace, the source's version of it, used to review updates.
- `status` (string, required): "active" entries can be used; "proposed" entries wait for an admin to approve them.
- `type` (string, required): What a caller sends for this key.
- `updated_at` (string, required): When the entry last changed.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID/entries/KEY" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Withdraw a data catalog submission (/docs/reference/Rest-API/api-docs/data-catalogs/withdrawDataCatalogSubmission)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organizations/{organizationid}/data-catalogs/{catalogid}/submission
`DELETE https://api.verdocs.com/v2/organizations/{organizationid}/data-catalogs/{catalogid}/submission`
### Path parameters
- `organizationid` (string, required)
- `catalogid` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataCatalogSubmission`
A request to list one released version of a catalog in the public marketplace, and Verdocs' decision on it.
- `notes` (string, required): What the submitter wanted reviewers to know.
- `review_notes` (string, required): The reason for a rejection.
- `reviewed_at` (string, required): When Verdocs decided.
- `submitted_by` (string, required): The profile that submitted it.
- `version` (integer, required): The released version under review.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organizations/ORGANIZATIONID/data-catalogs/CATALOGID/submission" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get envelope document (/docs/reference/Rest-API/api-docs/envelope-documents/getEnvelopeDocument)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/envelope-documents/{id}
`GET https://api.verdocs.com/v2/envelope-documents/{id}`
### Path parameters
- `id` (string, uuid, required): The ID of the document to retrieve.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IEnvelopeDocument`
An EnvelopeDocument is an individual document inside an Envelope package.
- `created_at` (string, required): Date/time when the document was created.
- `envelope_id` (string, required): Unique identifier for the envelope (UUID).
- `id` (string, required): Unique identifier for the document (UUID).
- `mime` (string, required): MIME type.
- `name` (string, required): The name of the document.
- `order` (integer, required): The order in which the document appears in the envelope.
- `page_sizes` (string, required): Collection of width/height dimensions for each page.
- `pages` (integer, required): Page count.
- `signed` (boolean, required): Whether the file has been signed. Note that document.signed is different from envelope.signed. Documents are signed first, then the certificate is created and signed, then the envelope is finally marked signed.
- `size` (integer, required): File size (bytes).
- `template_document_id` (string, required): Unique identifier for the template (UUID). May be null for envelopes created without templates.
- `type` (string, required): Whether the document is a signer-supplied attachment or a Verdocs-generated certificate.
- `updated_at` (string, required): Date/time when the document was created.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/envelope-documents/ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Download envelope document file (/docs/reference/Rest-API/api-docs/envelope-documents/getEnvelopeFile)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/envelope-documents/{document_id}
`GET https://api.verdocs.com/v2/envelope-documents/{document_id}`
### Path parameters
- `document_id` (string, uuid, required): The ID of the document to retrieve.
### Query parameters
- `type` (string, required): Return the document binary content. One of: `"file"`.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string, binary`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/envelope-documents/DOCUMENT_ID?param=value" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create Envelope (/docs/reference/Rest-API/api-docs/envelopes/createEnvelope)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/envelopes
`POST https://api.verdocs.com/v2/envelopes`
### Request body
Content type `application/json`, required. Body Parameters.
- `template_id` (string, uuid, required): If using a template, the ID of the template to copy.
- `recipients` (ICreateEnvelopeRecipientDirectly[], required): A list of recipients to include in the workflow. Must specify one recipient to match each template Role, except optional roles (required false), which may be left out. An optional role left out is dropped from the envelope along with its fields.
- `address` (string): Pre-fill KBA address for the recipient, if known.
- `auth_methods` (string): To enable authentication for the recipient, set to 'pin' or 'identity'.
- `city` (string): Pre-fill KBA city for the recipient, if known.
- `delegator` (boolean): Whether the recipient may delegate their tasks to others. Should be false for most standard workflows.
- `dob` (string): Pre-fill KBA date-of-birth for the recipient, if known.
- `email` (string): The email address of the recipient. One of.
- `first_name` (string, required): The name of the recipient as it will be displayed in reports and queries, e.g. 'Paige Turner'.
- `message` (string): A custom message to include in the email or SMS invitation. May be left blank for a default message.
- `order` (integer): The 1-based order within the sequence for the recipient. Recipients at the same sequence act in parallel, so this is only for display purposes.
- `passcode` (string): If Passcode-based authentication is used, the passcode to challenge the user to enter.
- `phone` (string): The phone number of the recipient. One of.
- `phone_auth` (string): If SMS-based authentication is used, the phone number to which one-time codes should be sent. NOTE: This may be different from the phone number used for notifications, but leaving it blank will trigger an error rather than defaulting to the notifications phone number to avoid mistaken assumptions (e.g. if SMS notifications are not enabled for the organization, but SMS authentication is).
- `role_name` (string, required): Unique identifier for the recipient. When using a template, must match one of the pre-defined roles in the template's Recipients list.
- `sequence` (integer): The 1-based sequence number for the recipient. This can be used to override the template's workflow. Recipients are processed in parallel for each matching sequence number (e.g. all recipients at level "1" may act in parallel) and in series between sequence numbers (e.g. all recipients at level "1" must complete their tasks before recipients at level "2" may act).
- `ssn_last_4` (string): Pre-fill KBA SSN-Last-4 for the recipient, if known.
- `state` (string): Pre-fill KBA state for the recipient, if known.
- `type` (string, required): The type of role to create. Most participants in standard flows will be "signer" recipients.
- `zip` (string): Pre-fill KBA zip for the recipient, if known.
- `documents` (IEnvelopeDocument[]): If not using a template, a list of documents to include in the envelope.
- `created_at` (string, required): Date/time when the document was created.
- `envelope_id` (string, required): Unique identifier for the envelope (UUID).
- `id` (string, required): Unique identifier for the document (UUID).
- `mime` (string, required): MIME type.
- `name` (string, required): The name of the document.
- `order` (integer, required): The order in which the document appears in the envelope.
- `page_sizes` (string, required): Collection of width/height dimensions for each page.
- `pages` (integer, required): Page count.
- `signed` (boolean, required): Whether the file has been signed. Note that document.signed is different from envelope.signed. Documents are signed first, then the certificate is created and signed, then the envelope is finally marked signed.
- `size` (integer, required): File size (bytes).
- `template_document_id` (string, required): Unique identifier for the template (UUID). May be null for envelopes created without templates.
- `type` (string, required): Whether the document is a signer-supplied attachment or a Verdocs-generated certificate.
- `updated_at` (string, required): Date/time when the document was created.
- `fields` (IEnvelopeField[]): If not using a template, a list of fields to include in the envelope.
- `config` (string): Settings for this field's type. Its type always matches the field's, so checking config.type narrows the rest.
- `data_key` (string): Your key for this field's value, copied from the template field.
- `default` (string, required): The default value for the field.
- `document_id` (string, required): The ID of the document the field is for.
- `envelope_id` (string, required): The ID of the envelope the field is for.
- `group` (string, required): For fields that support grouping (radio buttons and check boxes) the value selected will be stored under this name.
- `height` (integer, required): The height of the field.
- `label` (string, required): If set, the placeholder/label for the field.
- `multiline` (boolean, required): For text boxes, allows more than one line of text to be entered.
- `name` (string, required): The machine name of the field, e.g.
- `options` (string, required): For dropdowns, the options that are selectable.
- `page` (integer, required): The 1-based page number the field is displayed on. "Self-placed" fields that the user must apply will be on page 0.
- `placeholder` (string, required): The placeholder to show in the field.
- `prepared` (string, required): Not sent by the server. Used in the UI to identify prepared fields.
- `readonly` (string, required): If true, the field will be not be editable by the participant(s). NOTE: Fields may not be both required and readonly.
- `required` (string, required): If true, the field will be required.
- `role_name` (string, required): The ID of the role in the recipients list, e.g.
- `settings` (string, required): @deprecated. Use top-level fields instead.
- `type` (string, required): The type of the field.
- `width` (integer, required): The width of the field.
- `x` (integer, required): The X position of the field.
- `y` (integer, required): The Y position of the field.
- `name` (string): Override the name of the envelope (defaults to the template name).
- `description` (string): Override the description of the envelope (defaults to the template description).
- `no_contact` (boolean): If set to true, no email or SMS messages will be sent to any recipients.
- `initial_reminder` (integer): Override the template initial-reminder setting in ms.
- `followup_reminders` (integer): Override the template initial-reminder setting in ms.
- `max_reminder_days` (number): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `expires_at` (string): If set, the envelope expires at this date and time and its status becomes 'expired'. Must be at least 1 day in the future.
- `timezone` (string): Define the long-form timezone.
- `locale` (string): Define the locale code.
- `prefill_data` (object): Values for fields that have a data_key, keyed by data_key. Nested objects and dotted keys mean the same key. With a template_id, a fields entry for the same field wins; without one, a field that already has a default keeps it. The response then includes prefill_result, with how many fields were filled and any keys that went unused, were missing, or didn't fit their field or its format.
- `prefill_options` (object): Set "strict" to true to reject the request, creating nothing, when a key goes unused, a value doesn't fit its field or its format, or the key for a read-only field is missing. Add "ignore_unused": true to still list unused keys without rejecting the request for them.
- `data_catalog_id` (string, uuid): The data catalog the field data_keys come from, recorded on the envelope. Defaults to the template's catalog, then the organization default.
- `dry_run` (boolean): Run every check a real send makes and return the value each field would get (and any prefill_result) without creating or sending anything.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IEnvelope`
An Envelope is a workflow wrapper that shepherds one or more Documents through the various recipients in a signing process.
- `canceled_at` (string, required): Date/time when the envelope was canceled, or null. Expiring does not set this.
- `created_at` (string, required): Date/time when the envelope was created.
- `data` (string): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Envelopes back to internal systems/applications.
- `data_catalog_id` (string): The data catalog in effect when the envelope was created.
- `documents` (string): Documents attached to this envelope.
- `expires_at` (string): Date/time when the envelope will automatically expire, or null.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): Unique identifier for the envelope (UUID).
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `name` (string, required): Name of the envelope. By defaut, inherited from the envelope's template, but may be overridden when the envelope is created.
- `next_reminder` (string, required): When the next reminder is scheduled to be sent.
- `no_contact` (boolean): If set to true, no email or SMS messages will be sent to any of the envelope's recipients.
- `organization_id` (string, required): ID of the organization to which the envelope belongs.
- `profile_id` (string, required): ID of the envelope's creator.
- `sender_email` (string, required): Where notifications meant for the sender go (completed, declined, canceled, expired, delegated, failed authentication, and recipient questions), in place of the owner's email.
- `sender_name` (string, required): Sender name recipients see in the messages Verdocs sends them, in place of the owner's name. The email From line comes from the brand, then the organization.
- `signed` (boolean, required): If true, the envelope is fully submitted, processed, certificate-generated, and all documents have been stamped and signed.
- `status` (string, required): Current status of the envelope. Note that 'complete', 'declined', and 'canceled' are immutable/permanent end states. 'expired' is set when.
- `template_id` (string, required): ID of the template from which the envelope was created.
- `updated_at` (string, required): Date/time when the envelope was created.
- `visibility` (string, required): Defaults to 'private'. If set to 'shared', this envelope will be visible to other users in the same organization. Ignored for personal profiles.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/envelopes" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get envelope details (/docs/reference/Rest-API/api-docs/envelopes/getEnvelope)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/envelopes/{id}
`GET https://api.verdocs.com/v2/envelopes/{id}`
### Path parameters
- `id` (string, uuid, required): The ID of the envelope to retrieve.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IEnvelope`
An Envelope is a workflow wrapper that shepherds one or more Documents through the various recipients in a signing process.
- `canceled_at` (string, required): Date/time when the envelope was canceled, or null. Expiring does not set this.
- `created_at` (string, required): Date/time when the envelope was created.
- `data` (string): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Envelopes back to internal systems/applications.
- `data_catalog_id` (string): The data catalog in effect when the envelope was created.
- `documents` (string): Documents attached to this envelope.
- `expires_at` (string): Date/time when the envelope will automatically expire, or null.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): Unique identifier for the envelope (UUID).
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `name` (string, required): Name of the envelope. By defaut, inherited from the envelope's template, but may be overridden when the envelope is created.
- `next_reminder` (string, required): When the next reminder is scheduled to be sent.
- `no_contact` (boolean): If set to true, no email or SMS messages will be sent to any of the envelope's recipients.
- `organization_id` (string, required): ID of the organization to which the envelope belongs.
- `profile_id` (string, required): ID of the envelope's creator.
- `sender_email` (string, required): Where notifications meant for the sender go (completed, declined, canceled, expired, delegated, failed authentication, and recipient questions), in place of the owner's email.
- `sender_name` (string, required): Sender name recipients see in the messages Verdocs sends them, in place of the owner's name. The email From line comes from the brand, then the organization.
- `signed` (boolean, required): If true, the envelope is fully submitted, processed, certificate-generated, and all documents have been stamped and signed.
- `status` (string, required): Current status of the envelope. Note that 'complete', 'declined', and 'canceled' are immutable/permanent end states. 'expired' is set when.
- `template_id` (string, required): ID of the template from which the envelope was created.
- `updated_at` (string, required): Date/time when the envelope was created.
- `visibility` (string, required): Defaults to 'private'. If set to 'shared', this envelope will be visible to other users in the same organization. Ignored for personal profiles.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/envelopes/ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get envelope document page display URI (/docs/reference/Rest-API/api-docs/envelopes/getEnvelopeDocumentPageDisplayUri)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/envelope-documents/page-image/{document_id}/{variant}/{page}
`GET https://api.verdocs.com/v2/envelope-documents/page-image/{document_id}/{variant}/{page}`
### Path parameters
- `document_id` (string, uuid, required): The ID of the document to retrieve.
- `variant` (string, required): The variant of the document to retrieve. One of: `"original"`, `"filled"`.
- `page` (integer, required): The page number to retrieve.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/envelope-documents/page-image/DOCUMENT_ID/VARIANT/PAGE" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# List envelopes (/docs/reference/Rest-API/api-docs/envelopes/getEnvelopes)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/envelopes
`GET https://api.verdocs.com/v2/envelopes`
### Query parameters
- `q` (string): Match envelopes whose name contains this string.
- `view` (string): Request pre-defined view. `inbox` returns envelopes the caller has been invited to as a recipient, including ones they have since submitted, declined, or failed authentication on. `sent` returns envelopes created by the caller. `action` returns envelopes where action is required by the caller. `waiting` returns envelopes where action is required by anyone. `completed` returns envelopes where all actions are complete. One of: `"inbox"`, `"sent"`, `"action"`, `"waiting"`, `"completed"`.
- `status` (string[]): Match envelopes in one of the specified states.
- `include_org` (boolean): If true, include organizations-shared envelopes. Default: `"false"`.
- `template_id` (string, uuid): Match envelopes created from the specified template ID.
- `created_before` (string, date): Match envelopes created before this date.
- `created_after` (string, date): Match envelopes created after this date.
- `sort_by` (string): Return results sorted by this criteria. One of: `"name"`, `"created_at"`, `"updated_at"`, `"canceled_at"`, `"status"`.
- `ascending` (boolean): Set true/false to override the sort direction. Note that the default depends on `sort_by`. Date-based sorts default to descending, while name and status default to ascending.
- `rows` (integer): Limit the number of rows returned. Default: `20`.
- `page` (integer): Specify which page of results to return. Default: `0`.
### Responses
#### 200: Success
Content type `application/json`.
- `count` (integer, int32): The total number of records matching the query, helpful for pagination.
- `rows` (integer, int32): The number of rows returned in this response page.
- `page` (integer, int32): The page number of this response.
- `envelopes` (IEnvelope[]): List of envelopes found.
- `canceled_at` (string, required): Date/time when the envelope was canceled, or null. Expiring does not set this.
- `created_at` (string, required): Date/time when the envelope was created.
- `data` (string): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Envelopes back to internal systems/applications.
- `data_catalog_id` (string): The data catalog in effect when the envelope was created.
- `documents` (string): Documents attached to this envelope.
- `expires_at` (string): Date/time when the envelope will automatically expire, or null.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): Unique identifier for the envelope (UUID).
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `name` (string, required): Name of the envelope. By defaut, inherited from the envelope's template, but may be overridden when the envelope is created.
- `next_reminder` (string, required): When the next reminder is scheduled to be sent.
- `no_contact` (boolean): If set to true, no email or SMS messages will be sent to any of the envelope's recipients.
- `organization_id` (string, required): ID of the organization to which the envelope belongs.
- `profile_id` (string, required): ID of the envelope's creator.
- `sender_email` (string, required): Where notifications meant for the sender go (completed, declined, canceled, expired, delegated, failed authentication, and recipient questions), in place of the owner's email.
- `sender_name` (string, required): Sender name recipients see in the messages Verdocs sends them, in place of the owner's name. The email From line comes from the brand, then the organization.
- `signed` (boolean, required): If true, the envelope is fully submitted, processed, certificate-generated, and all documents have been stamped and signed.
- `status` (string, required): Current status of the envelope. Note that 'complete', 'declined', and 'canceled' are immutable/permanent end states. 'expired' is set when.
- `template_id` (string, required): ID of the template from which the envelope was created.
- `updated_at` (string, required): Date/time when the envelope was created.
- `visibility` (string, required): Defaults to 'private'. If set to 'shared', this envelope will be visible to other users in the same organization. Ignored for personal profiles.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/envelopes?param=value" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Generate envelope ZIP archive (/docs/reference/Rest-API/api-docs/envelopes/getEnvelopesZip)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/envelopes/zip/{envelope_ids}
`GET https://api.verdocs.com/v2/envelopes/zip/{envelope_ids}`
### Path parameters
- `envelope_ids` (string, required): Comma-separated envelope IDs to include in the archive.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string, binary`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/envelopes/zip/ENVELOPE_IDS" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Cancel or reset envelope (/docs/reference/Rest-API/api-docs/envelopes/resetEnvelope)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PUT /v2/envelopes/{id}
`PUT https://api.verdocs.com/v2/envelopes/{id}`
### Path parameters
- `id` (string, uuid, required): The ID of the envelope to operate on.
### Request body
Content type `application/json`, required. Body Parameters.
- `action` (string, required): The action to perform. "cancel" ends the envelope permanently. "reset" revives an expired envelope, or one stalled on a recipient who failed authentication. One of: `"cancel"`, `"reset"`.
- `expires_at` (string, date): Only used with "reset". New expiration date, which must be in the future. If omitted, the envelope's expiration will be extended by its original lifetime.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IEnvelope`
An Envelope is a workflow wrapper that shepherds one or more Documents through the various recipients in a signing process.
- `canceled_at` (string, required): Date/time when the envelope was canceled, or null. Expiring does not set this.
- `created_at` (string, required): Date/time when the envelope was created.
- `data` (string): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Envelopes back to internal systems/applications.
- `data_catalog_id` (string): The data catalog in effect when the envelope was created.
- `documents` (string): Documents attached to this envelope.
- `expires_at` (string): Date/time when the envelope will automatically expire, or null.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): Unique identifier for the envelope (UUID).
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `name` (string, required): Name of the envelope. By defaut, inherited from the envelope's template, but may be overridden when the envelope is created.
- `next_reminder` (string, required): When the next reminder is scheduled to be sent.
- `no_contact` (boolean): If set to true, no email or SMS messages will be sent to any of the envelope's recipients.
- `organization_id` (string, required): ID of the organization to which the envelope belongs.
- `profile_id` (string, required): ID of the envelope's creator.
- `sender_email` (string, required): Where notifications meant for the sender go (completed, declined, canceled, expired, delegated, failed authentication, and recipient questions), in place of the owner's email.
- `sender_name` (string, required): Sender name recipients see in the messages Verdocs sends them, in place of the owner's name. The email From line comes from the brand, then the organization.
- `signed` (boolean, required): If true, the envelope is fully submitted, processed, certificate-generated, and all documents have been stamped and signed.
- `status` (string, required): Current status of the envelope. Note that 'complete', 'declined', and 'canceled' are immutable/permanent end states. 'expired' is set when.
- `template_id` (string, required): ID of the template from which the envelope was created.
- `updated_at` (string, required): Date/time when the envelope was created.
- `visibility` (string, required): Defaults to 'private'. If set to 'shared', this envelope will be visible to other users in the same organization. Ignored for personal profiles.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PUT "https://api.verdocs.com/v2/envelopes/ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update Envelope (/docs/reference/Rest-API/api-docs/envelopes/updateEnvelope)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/envelopes/{id}
`PATCH https://api.verdocs.com/v2/envelopes/{id}`
### Path parameters
- `id` (string, uuid, required): The ID of the envelope to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string): New name for the envelope.
- `sender_name` (string): New Sender Name for the envelope.
- `sender_email` (string): New Sender Email for the envelope.
- `initial_reminder` (integer): Change the initial-reminder setting (in ms).
- `followup_reminders` (integer): Change the followup-reminder setting (in ms).
- `max_reminder_days` (number): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `expires_at` (string): When the envelope expires. At that point its status becomes 'expired', and the owner can revive it with resetEnvelope.
- `visibility` (string): Change the envelope's visibility setting. One of: `"private"`, `"shared"`.
- `no_contact` (boolean): If set to true, no email or SMS messages will be sent to any recipients.
- `data` (object): Update the developer-supplied metadata attached to the envelope.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IEnvelope`
An Envelope is a workflow wrapper that shepherds one or more Documents through the various recipients in a signing process.
- `canceled_at` (string, required): Date/time when the envelope was canceled, or null. Expiring does not set this.
- `created_at` (string, required): Date/time when the envelope was created.
- `data` (string): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Envelopes back to internal systems/applications.
- `data_catalog_id` (string): The data catalog in effect when the envelope was created.
- `documents` (string): Documents attached to this envelope.
- `expires_at` (string): Date/time when the envelope will automatically expire, or null.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): Unique identifier for the envelope (UUID).
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `name` (string, required): Name of the envelope. By defaut, inherited from the envelope's template, but may be overridden when the envelope is created.
- `next_reminder` (string, required): When the next reminder is scheduled to be sent.
- `no_contact` (boolean): If set to true, no email or SMS messages will be sent to any of the envelope's recipients.
- `organization_id` (string, required): ID of the organization to which the envelope belongs.
- `profile_id` (string, required): ID of the envelope's creator.
- `sender_email` (string, required): Where notifications meant for the sender go (completed, declined, canceled, expired, delegated, failed authentication, and recipient questions), in place of the owner's email.
- `sender_name` (string, required): Sender name recipients see in the messages Verdocs sends them, in place of the owner's name. The email From line comes from the brand, then the organization.
- `signed` (boolean, required): If true, the envelope is fully submitted, processed, certificate-generated, and all documents have been stamped and signed.
- `status` (string, required): Current status of the envelope. Note that 'complete', 'declined', and 'canceled' are immutable/permanent end states. 'expired' is set when.
- `template_id` (string, required): ID of the template from which the envelope was created.
- `updated_at` (string, required): Date/time when the envelope was created.
- `visibility` (string, required): Defaults to 'private'. If set to 'shared', this envelope will be visible to other users in the same organization. Ignored for personal profiles.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/envelopes/ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Upload envelope field attachment (/docs/reference/Rest-API/api-docs/envelopes/uploadEnvelopeFieldAttachment)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PUT /v2/envelopes/{envelope_id}/recipients/{role_name}/fields/{field_name}
`PUT https://api.verdocs.com/v2/envelopes/{envelope_id}/recipients/{role_name}/fields/{field_name}`
### Path parameters
- `envelope_id` (string, uuid, required): The ID of the envelope to update.
- `role_name` (string, required): The recipient role name.
- `field_name` (string, required): The attachment field name to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `document` (string, binary, required): File to upload.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IEnvelopeFieldSettings`
- `base64` (string): Signatures and Initials, result will be "signed".
- `leading` (integer): Text field settings.
- `minimum_checked` (integer): Checkbox settings.
- `options` (string): Dropdowns, checkboxes, radio groups.
- `result` (string): If the field has been filled in, this contains the current value.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PUT "https://api.verdocs.com/v2/envelopes/ENVELOPE_ID/recipients/ROLE_NAME/fields/FIELD_NAME" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Add a field to a template (/docs/reference/Rest-API/api-docs/fields/createField)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/fields/{template_id}
`POST https://api.verdocs.com/v2/fields/{template_id}`
### Path parameters
- `template_id` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string, required): Name for the new field. Field names must be unique within a template. Although special characters are allowed, they must be URL-encoded in subsequent requests, so it is recommended to use only alphanumeric characters and hyphens if possible.
- `role_name` (string, required): Role to assign to the field. Role names must be valid, so it is recommended to create roles before fields.
- `document_id` (string, required): ID of the document upon which to place the field.
- `type` (string, required): Type of field to create. One of: `"signature"`, `"initial"`, `"checkbox"`, `"radio"`, `"textbox"`, `"timestamp"`, `"date"`, `"dropdown"`, `"textarea"`, `"attachment"`, `"payment"`.
- `required` (boolean, required): Whether the field is required. Default: `"false"`.
- `page` (integer, required): 0-based page number upon which to place the field.
- `x` (integer, required): X position for the field (left to right).
- `y` (integer, required): Y position for the field (_bottom to top!_).
- `label` (string): Optional label to display above the field.
- `width` (integer): Width of the field. Note that all fields have built-in defaults, and it is recommended that this only be set on text fields.
- `height` (integer): Height of the field. Note that all fields have built-in defaults, and it is recommended that this only be set on text fields.
- `placeholder` (string): Optional placeholder to display in text fields.
- `group` (string): For fields that support grouping (radio buttons and check boxes) the value selected will be stored under this name.
- `options` (IDropdownOption[]): For dropdown fields, the options to display.
- `default` (string): Default value to pre-fill in the field. For checkboxes and radio buttons, true or "true" starts checked. Numbers are stored as text with thousands separators, e.g. "1,234.50". A date field given an ISO 8601 date starts out showing it as MM/dd/yyyy.
- `readonly` (boolean): Whether recipients are prevented from changing the field. May not be combined with required. Default: `"false"`.
- `validator` (string): Name of a validator to apply to the field's value (e.g. "email" or "phone").
- `data_key` (string): Your key for the field's value, such as "applicant.full_name". Fields that show the same value can share a key. Letters, digits, "_", and "-", with "." between levels. Text, date, checkbox, radio, and dropdown fields only.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplateField`
- `config` (string): Settings for this field's type. Its type always matches the field's, so checking config.type narrows the rest.
- `data_key` (string): Your key for this field's value, such as "applicant.full_name". Fields that show the same value can share a key.
- `default` (string, required): The default value for the field.
- `document_id` (string, required): The ID of the document the field is for.
- `group` (string, required): For fields that support grouping (radio buttons and check boxes) the value selected will be stored under this name.
- `height` (integer, required): The height of the field.
- `multiline` (boolean, required): For text boxes, allows more than one line of text to be entered.
- `name` (string, required): The machine name of the field, e.g.
- `options` (string, required): For dropdowns, the options that are selectable.
- `placeholder` (string, required): The placeholder to show in the field.
- `readonly` (string, required): If true, the field will be not be editable by the participant(s). NOTE: Fields may not be both required and readonly.
- `role_name` (string, required): The ID of the role in the recipients list, e.g.
- `settings` (string, required): @deprecated. Use top-level fields instead.
- `template_id` (string, required): The ID of the template the field is for.
- `width` (integer, required): The width of the field.
- `x` (integer, required): The X position of the field.
- `y` (integer, required): The Y position of the field.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/fields/TEMPLATE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete a field (/docs/reference/Rest-API/api-docs/fields/deleteField)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/fields/{template_id}/{field_name}
`DELETE https://api.verdocs.com/v2/fields/{template_id}/{field_name}`
### Path parameters
- `template_id` (string, required)
- `field_name` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/fields/TEMPLATE_ID/FIELD_NAME" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update a field (/docs/reference/Rest-API/api-docs/fields/updateField)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/fields/{template_id}/{field_name}
`PATCH https://api.verdocs.com/v2/fields/{template_id}/{field_name}`
### Path parameters
- `template_id` (string, required)
- `field_name` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string): Rename the field. Template field names must be unique within a template.
- `role_name` (string, required): Role to assign to the field.
- `document_id` (string, required): ID of the document upon which to place the field.
- `type` (string): Change the field type. Note that while this is technically allowed, fields have different behaviors, validators, default sizes, etc. It is usually easier to add a new field and delete the old one. One of: `"signature"`, `"initial"`, `"checkbox"`, `"radio"`, `"textbox"`, `"timestamp"`, `"date"`, `"dropdown"`, `"textarea"`, `"attachment"`, `"payment"`.
- `required` (boolean): Whether the field is required. Default: `"false"`.
- `page` (integer): 0-based page number upon which to place the field.
- `x` (integer): X position for the field (left to right).
- `y` (integer): Y position for the field (_bottom to top!_).
- `label` (string): Optional label to display above the field.
- `width` (integer): Width of the field. Note that all fields have built-in defaults, and it is recommended that this only be set on text fields.
- `height` (integer): Height of the field. Note that all fields have built-in defaults, and it is recommended that this only be set on text fields.
- `placeholder` (string): Optional placeholder to display in text fields.
- `group` (string): For fields that support grouping (radio buttons and check boxes) the value selected will be stored under this name.
- `options` (IDropdownOption[]): For dropdown fields, the options to display.
- `default` (string): Default value to pre-fill in the field. For checkboxes and radio buttons, true or "true" starts checked. Numbers are stored as text with thousands separators, e.g. "1,234.50". A date field given an ISO 8601 date starts out showing it as MM/dd/yyyy.
- `readonly` (boolean): Whether recipients are prevented from changing the field.
- `validator` (string): Name of a validator to apply to the field's value (e.g. "email" or "phone").
- `data_key` (string): Your key for the field's value, such as "applicant.full_name". Send null to remove it.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplateField`
- `config` (string): Settings for this field's type. Its type always matches the field's, so checking config.type narrows the rest.
- `data_key` (string): Your key for this field's value, such as "applicant.full_name". Fields that show the same value can share a key.
- `default` (string, required): The default value for the field.
- `document_id` (string, required): The ID of the document the field is for.
- `group` (string, required): For fields that support grouping (radio buttons and check boxes) the value selected will be stored under this name.
- `height` (integer, required): The height of the field.
- `multiline` (boolean, required): For text boxes, allows more than one line of text to be entered.
- `name` (string, required): The machine name of the field, e.g.
- `options` (string, required): For dropdowns, the options that are selectable.
- `placeholder` (string, required): The placeholder to show in the field.
- `readonly` (string, required): If true, the field will be not be editable by the participant(s). NOTE: Fields may not be both required and readonly.
- `role_name` (string, required): The ID of the role in the recipients list, e.g.
- `settings` (string, required): @deprecated. Use top-level fields instead.
- `template_id` (string, required): The ID of the template the field is for.
- `width` (integer, required): The width of the field.
- `x` (integer, required): The X position of the field.
- `y` (integer, required): The Y position of the field.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/fields/TEMPLATE_ID/FIELD_NAME" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get current KBA step (/docs/reference/Rest-API/api-docs/kba/getKbaStep)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/kba/{envelope_id}/{role_name}
`GET https://api.verdocs.com/v2/kba/{envelope_id}/{role_name}`
### Path parameters
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The recipient role name.
### Responses
#### 200: Success
Content type `application/json`.
Type: `TRecipientKbaStep`
The recipient's current step in the KBA (Knowledge-Based Authentication) flow. Branch on
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/kba/ENVELOPE_ID/ROLE_NAME" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Submit KBA challenge responses (/docs/reference/Rest-API/api-docs/kba/submitKbaChallengeResponse)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/kba/response
`POST https://api.verdocs.com/v2/kba/response`
### Request body
Content type `application/json`, required. Body Parameters.
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The recipient role name.
- `responses` (IKbaChallengeResponse[], required): Answers in the same order as the challenge questions.
### Responses
#### 200: Success
Content type `application/json`.
Type: `TRecipientKbaStep`
The recipient's current step in the KBA (Knowledge-Based Authentication) flow. Branch on
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/kba/response" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Submit KBA identity (/docs/reference/Rest-API/api-docs/kba/submitKbaIdentity)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/kba/identity
`POST https://api.verdocs.com/v2/kba/identity`
### Request body
Content type `application/json`, required. Body Parameters.
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The recipient role name.
- `identity` (object, required): Recipient identity details used for verification.
### Responses
#### 200: Success
Content type `application/json`.
Type: `TRecipientKbaStep`
The recipient's current step in the KBA (Knowledge-Based Authentication) flow. Branch on
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/kba/identity" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Submit KBA PIN (/docs/reference/Rest-API/api-docs/kba/submitKbaPin)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/kba/pin
`POST https://api.verdocs.com/v2/kba/pin`
### Request body
Content type `application/json`, required. Body Parameters.
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The recipient role name.
- `pin` (string, required): PIN entered by the recipient.
### Responses
#### 200: Success
Content type `application/json`.
Type: `TRecipientKbaStep`
The recipient's current step in the KBA (Knowledge-Based Authentication) flow. Branch on
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/kba/pin" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Disable MFA for the caller (/docs/reference/Rest-API/api-docs/mfa/disableMFA)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/users/mfa
`DELETE https://api.verdocs.com/v2/users/mfa`
### Request body
Content type `application/json`, required. Body Parameters.
- `code` (string, required): A current six-digit code from the user's authenticator app, or an unused backup code.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/users/mfa" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Begin MFA enrollment (/docs/reference/Rest-API/api-docs/mfa/enrollMFA)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Fails with a 400 error if MFA is already enabled for the caller.
## POST /v2/users/mfa/enroll
`POST https://api.verdocs.com/v2/users/mfa/enroll`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IMFAEnrollment`
A pending MFA enrollment. The secret is not active until it is confirmed with
- `expires_at` (string, required): When the pending enrollment expires (ISO8601) if it is not confirmed.
- `otpauth_url` (string, required): The.
- `secret` (string, required): The base32-encoded TOTP secret, for users who cannot scan a QR code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/users/mfa/enroll" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get the caller's MFA status (/docs/reference/Rest-API/api-docs/mfa/getMFAStatus)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/users/mfa
`GET https://api.verdocs.com/v2/users/mfa`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IMFAStatus`
The caller's multi-factor authentication status.
- `backup_codes_remaining` (integer, required): The number of unused backup codes remaining.
- `enabled` (boolean, required): True if the caller has completed MFA enrollment.
- `enrolled_at` (string, required): When MFA was enabled (ISO8601), or null if it is not enabled.
- `type` (string, required): The type of second factor enrolled, or null if MFA is not enabled.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/users/mfa" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Regenerate the caller's backup codes (/docs/reference/Rest-API/api-docs/mfa/regenerateBackupCodes)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/users/mfa/backup-codes
`POST https://api.verdocs.com/v2/users/mfa/backup-codes`
### Request body
Content type `application/json`, required. Body Parameters.
- `code` (string, required): The current six-digit code from the user's authenticator app.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IMFABackupCodes`
A set of one-time backup codes. These are returned only once, at the moment they are generated.
- `backup_codes` (string, required): Single-use backup codes, formatted 'xxxx-xxxx'. Each may be used once in place of a TOTP code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/users/mfa/backup-codes" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Complete MFA enrollment (/docs/reference/Rest-API/api-docs/mfa/verifyMFAEnrollment)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Three incorrect codes discard the pending enrollment and the user must start over.
## POST /v2/users/mfa/enroll/verify
`POST https://api.verdocs.com/v2/users/mfa/enroll/verify`
### Request body
Content type `application/json`, required. Body Parameters.
- `code` (string, required): The current six-digit code from the user's authenticator app.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IMFABackupCodes`
A set of one-time backup codes. These are returned only once, at the moment they are generated.
- `backup_codes` (string, required): Single-use backup codes, formatted 'xxxx-xxxx'. Each may be used once in place of a TOTP code.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/users/mfa/enroll/verify" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create notification template (/docs/reference/Rest-API/api-docs/notifications/createNotificationTemplate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/notifications/templates
`POST https://api.verdocs.com/v2/notifications/templates`
### Request body
Content type `application/json`, required. Body Parameters.
- `type` (string, required): The notification channel type. One of: `"sms"`, `"email"`, `"app"`.
- `event_name` (string, required): The event that triggers this notification.
- `template_id` (string): Optional reference to an associated template.
- `html_template` (string): The HTML content for the notification. At least one of html_template or text_template is required.
- `text_template` (string): The plain-text content for the notification. At least one of html_template or text_template is required.
### Responses
#### 200: Success
Content type `application/json`.
Type: `INotificationTemplate`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/notifications/templates" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete notification template (/docs/reference/Rest-API/api-docs/notifications/deleteNotificationTemplate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/notifications/templates/{id}
`DELETE https://api.verdocs.com/v2/notifications/templates/{id}`
### Path parameters
- `id` (string, uuid, required): The notification template ID.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/notifications/templates/ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get notification template (/docs/reference/Rest-API/api-docs/notifications/getNotificationTemplate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/notifications/templates/{id}
`GET https://api.verdocs.com/v2/notifications/templates/{id}`
### Path parameters
- `id` (string, uuid, required): The notification template ID.
### Responses
#### 200: Success
Content type `application/json`.
Type: `INotificationTemplate`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/notifications/templates/ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get notification templates (/docs/reference/Rest-API/api-docs/notifications/getNotificationTemplates)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/notifications/templates
`GET https://api.verdocs.com/v2/notifications/templates`
### Responses
#### 200: Success
Content type `application/json`.
Type: `INotificationTemplate[]`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/notifications/templates" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get notifications (/docs/reference/Rest-API/api-docs/notifications/getNotifications)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/notifications
`GET https://api.verdocs.com/v2/notifications`
### Responses
#### 200: Success
Content type `application/json`.
Type: `INotification[]`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/notifications" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update notification template (/docs/reference/Rest-API/api-docs/notifications/updateNotificationTemplate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/notifications/templates/{id}
`PATCH https://api.verdocs.com/v2/notifications/templates/{id}`
### Path parameters
- `id` (string, uuid, required): The notification template ID.
### Request body
Content type `application/json`, required. Body Parameters.
- `html_template` (string): The HTML content for the notification. At least one of html_template or text_template is required.
- `text_template` (string): The plain-text content for the notification. At least one of html_template or text_template is required.
### Responses
#### 200: Success
Content type `application/json`.
Type: `INotificationTemplate`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/notifications/templates/ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create organization contact (/docs/reference/Rest-API/api-docs/organization-contacts/createOrganizationContact)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organization-contacts
`POST https://api.verdocs.com/v2/organization-contacts`
### Request body
Content type `application/json`, required. Body Parameters.
- `first_name` (string, required): Contact first name.
- `last_name` (string, required): Contact last name.
- `email` (string, required): Contact email address.
- `phone` (string): Contact phone number.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IProfile`
- `current` (boolean, required): If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile.
- `id` (string, required): The unique ID of the profile.
- `locale` (string): The long-form timezone.
- `organization_id` (string, required): The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of.
- `timezone` (string): The locale code.
- `user_id` (string, required): In Verdocs, a user may have multiple profiles. A user represents a single person. A profile represents that person within an organization. Some profiles may have no user atached, typically Contacts and Signers. This can change if that person registers for a user later.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organization-contacts" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete organization contact (/docs/reference/Rest-API/api-docs/organization-contacts/deleteOrganizationContact)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organization-contacts/{profile_id}
`DELETE https://api.verdocs.com/v2/organization-contacts/{profile_id}`
### Path parameters
- `profile_id` (string, uuid, required): The contact profile ID to delete.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organization-contacts/PROFILE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get a list of organization contacts (/docs/reference/Rest-API/api-docs/organization-contacts/getOrganizationContacts)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organization-contacts
`GET https://api.verdocs.com/v2/organization-contacts`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IProfile[]`
- `current` (boolean, required): If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile.
- `id` (string, required): The unique ID of the profile.
- `locale` (string): The long-form timezone.
- `organization_id` (string, required): The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of.
- `timezone` (string): The locale code.
- `user_id` (string, required): In Verdocs, a user may have multiple profiles. A user represents a single person. A profile represents that person within an organization. Some profiles may have no user atached, typically Contacts and Signers. This can change if that person registers for a user later.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organization-contacts" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update organization contact (/docs/reference/Rest-API/api-docs/organization-contacts/updateOrganizationContact)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/organization-contacts/{profile_id}
`PATCH https://api.verdocs.com/v2/organization-contacts/{profile_id}`
### Path parameters
- `profile_id` (string, uuid, required): The contact profile ID to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `first_name` (string): Contact first name.
- `last_name` (string): Contact last name.
- `email` (string): Contact email address.
- `phone` (string): Contact phone number.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IProfile`
- `current` (boolean, required): If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile.
- `id` (string, required): The unique ID of the profile.
- `locale` (string): The long-form timezone.
- `organization_id` (string, required): The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of.
- `timezone` (string): The locale code.
- `user_id` (string, required): In Verdocs, a user may have multiple profiles. A user represents a single person. A profile represents that person within an organization. Some profiles may have no user atached, typically Contacts and Signers. This can change if that person registers for a user later.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/organization-contacts/PROFILE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Add member to organization group (/docs/reference/Rest-API/api-docs/organization-groups/addGroupMember)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organization-groups/{group_id}/members
`POST https://api.verdocs.com/v2/organization-groups/{group_id}/members`
### Path parameters
- `group_id` (string, uuid, required): The group ID to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `profile_id` (string, uuid, required): Profile ID to add to the group.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IGroup`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organization-groups/GROUP_ID/members" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create organization group (/docs/reference/Rest-API/api-docs/organization-groups/createGroup)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organization-groups
`POST https://api.verdocs.com/v2/organization-groups`
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string, required): Name for the new group. "everyone" is reserved and may not be used.
- `permissions` (TPermission[], required): Permissions to assign to the group.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IGroup`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organization-groups" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete organization group (/docs/reference/Rest-API/api-docs/organization-groups/deleteGroup)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organization-groups/{group_id}
`DELETE https://api.verdocs.com/v2/organization-groups/{group_id}`
### Path parameters
- `group_id` (string, uuid, required): The group ID to delete. The "everyone" group cannot be deleted.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organization-groups/GROUP_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Remove member from organization group (/docs/reference/Rest-API/api-docs/organization-groups/deleteGroupMember)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organization-groups/{group_id}/members/{profile_id}
`DELETE https://api.verdocs.com/v2/organization-groups/{group_id}/members/{profile_id}`
### Path parameters
- `group_id` (string, uuid, required): The group ID to update.
- `profile_id` (string, uuid, required): Profile ID to remove from the group.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IGroup`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organization-groups/GROUP_ID/members/PROFILE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get organization group (/docs/reference/Rest-API/api-docs/organization-groups/getGroup)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organization-groups/{group_id}
`GET https://api.verdocs.com/v2/organization-groups/{group_id}`
### Path parameters
- `group_id` (string, uuid, required): The group ID to retrieve.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IGroup`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organization-groups/GROUP_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# List organization groups (/docs/reference/Rest-API/api-docs/organization-groups/getGroups)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organization-groups
`GET https://api.verdocs.com/v2/organization-groups`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IGroup[]`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organization-groups" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update organization group (/docs/reference/Rest-API/api-docs/organization-groups/updateGroup)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/organization-groups/{group_id}
`PATCH https://api.verdocs.com/v2/organization-groups/{group_id}`
### Path parameters
- `group_id` (string, uuid, required): The group ID to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string): New name for the group. "everyone" is reserved and may not be changed.
- `permissions` (TPermission[]): Updated permissions for the group.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IGroup`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/organization-groups/GROUP_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Accept an invitation (/docs/reference/Rest-API/api-docs/organization-invitations/acceptOrganizationInvitation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organization-invitations/accept
`POST https://api.verdocs.com/v2/organization-invitations/accept`
### Request body
Content type `application/json`, required. Body Parameters.
- `email` (string, required): Email address for the invitee.
- `token` (string, required): Invite token for the invitee.
- `first_name` (string, required): First name.
- `last_name` (string, required): Last name.
- `password` (string, required): Password.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IAuthenticateResponse`
- `refresh_token` (string): Only API key (client_credentials) sign-ins and their refreshes return a refresh token.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organization-invitations/accept" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Invite a new user to join the organization (/docs/reference/Rest-API/api-docs/organization-invitations/createOrganizationInvitation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organization-invitations
`POST https://api.verdocs.com/v2/organization-invitations`
### Request body
Content type `application/json`, required. Body Parameters.
- `email` (string, required): Email address to send the invitation to.
- `first_name` (string, required): First name. The user may override this after accepting the invitation.
- `last_name` (string, required): Last name. The user may override this after accepting the invitation.
- `role` (TRole, required): Initial role to assign to the user once they accept. One of: `"contact"`, `"basic_user"`, `"member"`, `"admin"`, `"owner"`.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IOrganizationInvitation`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organization-invitations" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Decline an invitation (/docs/reference/Rest-API/api-docs/organization-invitations/declineOrganizationInvitation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Mark the status "declined," providing a visual indication to the organization's admins that the invite was declined, preventing further invites from being created to the same email address, and also preventing the invitee from receiving reminders to join.
## POST /v2/organization-invitations/decline
`POST https://api.verdocs.com/v2/organization-invitations/decline`
### Request body
Content type `application/json`, required. Body Parameters.
- `email` (string, required): Email address for the invitee.
- `token` (string, required): Invite token for the invitee.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organization-invitations/decline" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete a pending invitation (/docs/reference/Rest-API/api-docs/organization-invitations/deleteOrganizationInvitation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organization-invitations/{email}
`DELETE https://api.verdocs.com/v2/organization-invitations/{email}`
### Path parameters
- `email` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organization-invitations/EMAIL" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get a pending invitation (/docs/reference/Rest-API/api-docs/organization-invitations/getOrganizationInvitation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organization-invitations/{email}/{token}
`GET https://api.verdocs.com/v2/organization-invitations/{email}/{token}`
### Path parameters
- `email` (string, required)
- `token` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IOrganizationInvitation`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organization-invitations/EMAIL/TOKEN" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get a list of invitations (/docs/reference/Rest-API/api-docs/organization-invitations/getOrganizationInvitations)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organization-invitations
`GET https://api.verdocs.com/v2/organization-invitations`
### Request body
Content type `application/json`, required. Body Parameters.
- `roles` (TRole[], required): URL to send Webhook events to. An empty or invalid URL will disable Webhook calls.
- `first_name` (string, required): First name. The user may override this after accepting the invitation.
- `last_name` (string, required): Last name. The user may override this after accepting the invitation.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IProfile[]`
- `current` (boolean, required): If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile.
- `id` (string, required): The unique ID of the profile.
- `locale` (string): The long-form timezone.
- `organization_id` (string, required): The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of.
- `timezone` (string): The locale code.
- `user_id` (string, required): In Verdocs, a user may have multiple profiles. A user represents a single person. A profile represents that person within an organization. Some profiles may have no user atached, typically Contacts and Signers. This can change if that person registers for a user later.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organization-invitations" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Send a reminder to a pending invitee (/docs/reference/Rest-API/api-docs/organization-invitations/resendOrganizationInvitation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organization-invitations/resend
`POST https://api.verdocs.com/v2/organization-invitations/resend`
### Request body
Content type `application/json`, required. Body Parameters.
- `email` (string, required): The recipient to send the reminder to.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IOrganizationInvitation`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organization-invitations/resend" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update a pending invitation (/docs/reference/Rest-API/api-docs/organization-invitations/updateOrganizationInvitation)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/organization-invitations/{email}
`PATCH https://api.verdocs.com/v2/organization-invitations/{email}`
### Path parameters
- `email` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `role` (TRole, required): Initial role to assign to the user once they accept. One of: `"contact"`, `"basic_user"`, `"member"`, `"admin"`, `"owner"`.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IOrganizationInvitation`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/organization-invitations/EMAIL" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create an organization member directly, bypassing the invite process. (/docs/reference/Rest-API/api-docs/organization-members/createOrganizationMember)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/organization-members
`POST https://api.verdocs.com/v2/organization-members`
### Request body
Content type `application/json`, required. Body Parameters.
- `email` (string, required): Email address for the member.
- `first_name` (string, required): First name for the member.
- `last_name` (string, required): Last name for the member.
- `password` (string): If set, will be used as the initial password. If omitted, a password will be generated and returned.
- `roles` (TRole[]): Roles (e.g. "member" or "admin") to assign to the user.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IProfile`
- `current` (boolean, required): If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile.
- `id` (string, required): The unique ID of the profile.
- `locale` (string): The long-form timezone.
- `organization_id` (string, required): The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of.
- `timezone` (string): The locale code.
- `user_id` (string, required): In Verdocs, a user may have multiple profiles. A user represents a single person. A profile represents that person within an organization. Some profiles may have no user atached, typically Contacts and Signers. This can change if that person registers for a user later.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organization-members" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete a member from the organization (/docs/reference/Rest-API/api-docs/organization-members/deleteOrganizationMember)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organization-members/{profile_id}
`DELETE https://api.verdocs.com/v2/organization-members/{profile_id}`
### Path parameters
- `profile_id` (string, uuid, required): The Profile ID to remove.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organization-members/PROFILE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# List current organization's members (/docs/reference/Rest-API/api-docs/organization-members/getOrganizationMembers)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organization-members
`GET https://api.verdocs.com/v2/organization-members`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IProfile[]`
- `current` (boolean, required): If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile.
- `id` (string, required): The unique ID of the profile.
- `locale` (string): The long-form timezone.
- `organization_id` (string, required): The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of.
- `timezone` (string): The locale code.
- `user_id` (string, required): In Verdocs, a user may have multiple profiles. A user represents a single person. A profile represents that person within an organization. Some profiles may have no user atached, typically Contacts and Signers. This can change if that person registers for a user later.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organization-members" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Perform an operation on an organization member. (/docs/reference/Rest-API/api-docs/organization-members/unlockOrganizationMember)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PUT /v2/organization-members/{profile_id}
`PUT https://api.verdocs.com/v2/organization-members/{profile_id}`
### Path parameters
- `profile_id` (string, uuid, required): The Profile ID to operate on.
### Request body
Content type `application/json`, required. Body Parameters.
- `action` (string, required): Action to perform. One of: `"unlock"`.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IProfile`
- `current` (boolean, required): If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile.
- `id` (string, required): The unique ID of the profile.
- `locale` (string): The long-form timezone.
- `organization_id` (string, required): The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of.
- `timezone` (string): The locale code.
- `user_id` (string, required): In Verdocs, a user may have multiple profiles. A user represents a single person. A profile represents that person within an organization. Some profiles may have no user atached, typically Contacts and Signers. This can change if that person registers for a user later.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PUT "https://api.verdocs.com/v2/organization-members/PROFILE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update an organization member. (/docs/reference/Rest-API/api-docs/organization-members/updateOrganizationMember)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/organization-members/{profile_id}
`PATCH https://api.verdocs.com/v2/organization-members/{profile_id}`
### Path parameters
- `profile_id` (string, uuid, required): The Profile ID to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `first_name` (string): First name for the member.
- `last_name` (string): Last name for the member.
- `roles` (TRole[]): Roles (e.g. "member" or "admin") to assign to the user.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IProfile`
- `current` (boolean, required): If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile.
- `id` (string, required): The unique ID of the profile.
- `locale` (string): The long-form timezone.
- `organization_id` (string, required): The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of.
- `timezone` (string): The locale code.
- `user_id` (string, required): In Verdocs, a user may have multiple profiles. A user represents a single person. A profile represents that person within an organization. Some profiles may have no user atached, typically Contacts and Signers. This can change if that person registers for a user later.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/organization-members/PROFILE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create organization (/docs/reference/Rest-API/api-docs/organizations/createOrganization)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
The caller will be assigned an "Owner" profile in the new organization, and it will be set to "current" automatically. A new set of session tokens will be issued to the caller, and the caller should update their endpoint to use the new tokens.
## POST /v2/organizations
`POST https://api.verdocs.com/v2/organizations`
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string, required): The name of the new organization.
- `parent_id` (string): If set, the new organization will be created as a child of the specified parent organization. The caller must be an admin of the parent organization.
- `contact_email` (string): Contact email for the new organization.
- `url` (string): URL for the new organization.
- `full_logo_url` (string): URL of a large-format PNG logo.
- `thumbnail_url` (string): URL of a small-format (square is recommended) PNG logo.
- `primary_color` (string): Primary brand color (hex string, e.g. "#FF0000").
- `secondary_color` (string): Secondary brand color (hex string).
- `terms_use_url` (string): URL of a Terms of Use page, shown in bottom-right of signing experience. Hidden if not set.
- `privacy_policy_url` (string): URL of a Privacy Policy page, shown in bottom-right of signing experience. Hidden if not set.
- `powered_by_label` (string): "Powered-by..." label, shown in bottom-left of signing experience. Hidden if not set.
- `powered_by_url` (string): URL for the Powered By label to show when clicked. Rendered as a static label if not set.
- `timezone` (string): Define the long-form timezone.
- `locale` (string): Define the locale code.
- `disclaimer` (string): Custom disclaimer/disclosure block to present to envelope recipients. May contain basic HTML (e.g. ol/ul/li tags) but complex or dangerous (e.g. script) tags will be rejected.
- `data` (object): Developer-supplied metadata attached to the organization.
- `deletion_protected` (boolean): Prevents the organization from being deleted until turned off. Defaults to true.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IAuthenticateResponse`
- `refresh_token` (string): Only API key (client_credentials) sign-ins and their refreshes return a refresh token.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/organizations" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete organization (/docs/reference/Rest-API/api-docs/organizations/deleteOrganization)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/organizations/{organization_id}
`DELETE https://api.verdocs.com/v2/organizations/{organization_id}`
### Path parameters
- `organization_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IAuthenticateResponse`
- `refresh_token` (string): Only API key (client_credentials) sign-ins and their refreshes return a refresh token.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/organizations/ORGANIZATION_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get organization entitlements (/docs/reference/Rest-API/api-docs/organizations/getEntitlements)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/entitlements
`GET https://api.verdocs.com/v2/organizations/entitlements`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IEntitlement[]`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/entitlements" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get organization (/docs/reference/Rest-API/api-docs/organizations/getOrganization)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organization_id}
`GET https://api.verdocs.com/v2/organizations/{organization_id}`
### Path parameters
- `organization_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IOrganization`
- `api_key` (string): If creating a child organization, an API key will be automatically created and returned. This saves a few API calls doing so in subsequent operations. Please note that this is a synthetic field and not part of the formal IOrganization definition. In API v3, this field will move to the top level, outside the organization response object.
- `contact_email` (string, required): If the organization is a business, its name. Note that a business name can be different from an organization name.
- `default_data_catalog_id` (string): The data catalog new templates start with.
- `deletion_protected` (boolean, required): If set, the organization may not be deleted. Must be set to false before calling DELETE. Defaults to true (protected).
- `id` (string, required): The unique ID of the organization.
- `locale` (string): The long-form timezone.
- `name` (string, required): The organization's name.
- `pipeline_settings` (string): Org-level document-pipeline automation flags.
- `timezone` (string): The locale code.
- `url` (string): Web site URL.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATION_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get an organization's children (/docs/reference/Rest-API/api-docs/organizations/getOrganizationChildren)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organization_id}/children
`GET https://api.verdocs.com/v2/organizations/{organization_id}/children`
### Path parameters
- `organization_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IOrganization`
- `api_key` (string): If creating a child organization, an API key will be automatically created and returned. This saves a few API calls doing so in subsequent operations. Please note that this is a synthetic field and not part of the formal IOrganization definition. In API v3, this field will move to the top level, outside the organization response object.
- `contact_email` (string, required): If the organization is a business, its name. Note that a business name can be different from an organization name.
- `default_data_catalog_id` (string): The data catalog new templates start with.
- `deletion_protected` (boolean, required): If set, the organization may not be deleted. Must be set to false before calling DELETE. Defaults to true (protected).
- `id` (string, required): The unique ID of the organization.
- `locale` (string): The long-form timezone.
- `name` (string, required): The organization's name.
- `pipeline_settings` (string): Org-level document-pipeline automation flags.
- `timezone` (string): The locale code.
- `url` (string): Web site URL.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATION_ID/children" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get organization pipeline settings (/docs/reference/Rest-API/api-docs/organizations/getOrganizationPipelineSettings)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organization_id}/pipeline-settings
`GET https://api.verdocs.com/v2/organizations/{organization_id}/pipeline-settings`
### Path parameters
- `organization_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IPipelineSettings`
Org-level document-pipeline automation flags. Note that these flags are all "opt-in" and default to false if not set. - process_acroforms: Auto-detect AcroForm (fillable PDF) fields when a document has no text tags. - process_tags: Process {{...}} text tags in uploaded documents. - ignore_invalid_roles: Skip (vs. reject) document tags whose role name is empty/invalid. - ignore_invalid_fields: Skip (vs. reject) document tags that don't form a valid field. - ai_field_suggestions: Let template editors ask a model on Amazon Bedrock to suggest field names, groups, and rules. Needs an active envelope plan.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATION_ID/pipeline-settings" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get an organization's usage metrics (/docs/reference/Rest-API/api-docs/organizations/getOrganizationUsage)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/organizations/{organization_id}/usage
`GET https://api.verdocs.com/v2/organizations/{organization_id}/usage`
### Path parameters
- `organization_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `TOrganizationUsage`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/organizations/ORGANIZATION_ID/usage" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update organization pipeline settings (/docs/reference/Rest-API/api-docs/organizations/updateOrganizationPipelineSettings)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/organizations/{organization_id}/pipeline-settings
`PATCH https://api.verdocs.com/v2/organizations/{organization_id}/pipeline-settings`
### Path parameters
- `organization_id` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `process_acroforms` (boolean): Auto-detect AcroForm (fillable PDF) fields when a document has no text tags.
- `process_tags` (boolean): Process {{...}} text tags in uploaded documents.
- `ignore_invalid_roles` (boolean): Skip (rather than reject) document tags with an empty/invalid role name.
- `ignore_invalid_fields` (boolean): Skip (rather than reject) document tags that don't form a valid field.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IPipelineSettings`
Org-level document-pipeline automation flags. Note that these flags are all "opt-in" and default to false if not set. - process_acroforms: Auto-detect AcroForm (fillable PDF) fields when a document has no text tags. - process_tags: Process {{...}} text tags in uploaded documents. - ignore_invalid_roles: Skip (vs. reject) document tags whose role name is empty/invalid. - ignore_invalid_fields: Skip (vs. reject) document tags that don't form a valid field. - ai_field_suggestions: Let template editors ask a model on Amazon Bedrock to suggest field names, groups, and rules. Needs an active envelope plan.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/organizations/ORGANIZATION_ID/pipeline-settings" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update organization thumbnail (/docs/reference/Rest-API/api-docs/organizations/updateOrganizationThumbnail)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/organizations/{organization_id}
`PATCH https://api.verdocs.com/v2/organizations/{organization_id}`
### Path parameters
- `organization_id` (string, uuid, required): The organization ID to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `thumbnail` (string, binary, required): Thumbnail image to upload.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IOrganization`
- `api_key` (string): If creating a child organization, an API key will be automatically created and returned. This saves a few API calls doing so in subsequent operations. Please note that this is a synthetic field and not part of the formal IOrganization definition. In API v3, this field will move to the top level, outside the organization response object.
- `contact_email` (string, required): If the organization is a business, its name. Note that a business name can be different from an organization name.
- `default_data_catalog_id` (string): The data catalog new templates start with.
- `deletion_protected` (boolean, required): If set, the organization may not be deleted. Must be set to false before calling DELETE. Defaults to true (protected).
- `id` (string, required): The unique ID of the organization.
- `locale` (string): The long-form timezone.
- `name` (string, required): The organization's name.
- `pipeline_settings` (string): Org-level document-pipeline automation flags.
- `timezone` (string): The locale code.
- `url` (string): Web site URL.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/organizations/ORGANIZATION_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create profile and organization (/docs/reference/Rest-API/api-docs/profiles/createProfile)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/profiles
`POST https://api.verdocs.com/v2/profiles`
### Request body
Content type `application/json`, required. Body Parameters.
- `email` (string, required): Email address for the new user.
- `password` (string, required): Password for the new user.
- `first_name` (string, required): First name.
- `last_name` (string, required): Last name.
- `org_name` (string, required): Name for the new organization.
- `phone` (string, required): Phone number.
- `timezone` (string): Long-form timezone.
- `locale` (string): Locale code.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IAuthenticateResponse`
- `refresh_token` (string): Only API key (client_credentials) sign-ins and their refreshes return a refresh token.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/profiles" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete a profile (/docs/reference/Rest-API/api-docs/profiles/deleteProfile)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/profiles/{profile_id}
`DELETE https://api.verdocs.com/v2/profiles/{profile_id}`
### Path parameters
- `profile_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IAuthenticateResponse`
- `refresh_token` (string): Only API key (client_credentials) sign-ins and their refreshes return a refresh token.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/profiles/PROFILE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get the caller's profiles (/docs/reference/Rest-API/api-docs/profiles/getProfiles)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
A user may have multiple profiles, one for each organization of which they are a member. Only one profile may be "current" at a time.
## GET /v2/profiles
`GET https://api.verdocs.com/v2/profiles`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IProfile[]`
- `current` (boolean, required): If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile.
- `id` (string, required): The unique ID of the profile.
- `locale` (string): The long-form timezone.
- `organization_id` (string, required): The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of.
- `timezone` (string): The locale code.
- `user_id` (string, required): In Verdocs, a user may have multiple profiles. A user represents a single person. A profile represents that person within an organization. Some profiles may have no user atached, typically Contacts and Signers. This can change if that person registers for a user later.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/profiles" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Change the "current" profile for the caller (/docs/reference/Rest-API/api-docs/profiles/switchProfile)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/profiles/{profile_id}/switch
`POST https://api.verdocs.com/v2/profiles/{profile_id}/switch`
### Path parameters
- `profile_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IAuthenticateResponse`
- `refresh_token` (string): Only API key (client_credentials) sign-ins and their refreshes return a refresh token.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/profiles/PROFILE_ID/switch" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Change profile photo (/docs/reference/Rest-API/api-docs/profiles/updateProfilePhoto)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/profiles/{profile_id}
`PATCH https://api.verdocs.com/v2/profiles/{profile_id}`
### Path parameters
- `profile_id` (string, uuid, required): Profile ID to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `picture` (string, binary, required): Profile photo to upload.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IProfile`
- `current` (boolean, required): If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile.
- `id` (string, required): The unique ID of the profile.
- `locale` (string): The long-form timezone.
- `organization_id` (string, required): The profile's organization ID, or a global "Verdocs" organization that all personal profiles are members of.
- `timezone` (string): The locale code.
- `user_id` (string, required): In Verdocs, a user may have multiple profiles. A user represents a single person. A profile represents that person within an organization. Some profiles may have no user atached, typically Contacts and Signers. This can change if that person registers for a user later.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/profiles/PROFILE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Ask Sender a Question (/docs/reference/Rest-API/api-docs/recipients/askQuestion)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/envelopes/{envelope_id}/recipients/{role_name}/ask-question
`POST https://api.verdocs.com/v2/envelopes/{envelope_id}/recipients/{role_name}/ask-question`
### Path parameters
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The role name to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `question` (string, required): The question to ask.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/envelopes/ENVELOPE_ID/recipients/ROLE_NAME/ask-question" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delegate Recipient (/docs/reference/Rest-API/api-docs/recipients/delegateRecipient)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/envelopes/{envelope_id}/recipients/{role_name}/delegate
`POST https://api.verdocs.com/v2/envelopes/{envelope_id}/recipients/{role_name}/delegate`
### Path parameters
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The role to operate on.
### Request body
Content type `application/json`, required. Body Parameters.
- `first_name` (string, required): The first name of the new recipient.
- `last_name` (string, required): The last name of the new recipient.
- `email` (string, required): The email address of the new recipient.
- `phone` (string): Optional phone number for the new recipient.
- `message` (string): Optional message for the new recipient's invitation.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/envelopes/ENVELOPE_ID/recipients/ROLE_NAME/delegate" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Agree to e-Signing Disclosures (/docs/reference/Rest-API/api-docs/recipients/envelopeRecipientAgree)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/envelopes/{envelope_id}/recipients/{role_name}/agree
`POST https://api.verdocs.com/v2/envelopes/{envelope_id}/recipients/{role_name}/agree`
### Path parameters
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The role to operate on.
### Request body
Content type `application/json`, required. Body Parameters.
- `timezone` (string): Define the long-form timezone.
- `locale` (string): Define the locale code.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IRecipient`
- `address` (string): Street address. Only used in KBA workflows. Combine two-line addresses into a single string.
- `auth_method_states` (string): The status of each auth method enabled.
- `auth_methods` (string): The types of authentication/verification required for this recipient.
- `auth_step` (string): The next verification step that must be performed.
- `city` (string): Zip code. Only used in KBA workflows.
- `disclosures` (string): The disclosure text the recipient accepted.
- `disclosures_accepted_at` (string): Date/time the recipient agreed to their e-signing disclosures.
- `dob` (string): Date of birth. Only used in KBA workflows.
- `full_name` (string): @deprecated. Use first_name/last_name instead.
- `id` (string): Used only by the Web SDK during builder processes. Not stored in the backend.
- `in_app_key` (string): Only returned in creation/getEnvelopeById requests by the creator. May be used for in-person signing. Note that signing sessions started with this key will be marked as "In App" authenticated. For higher authentication levels, e.g. email, the signer must follow a link send via the appropriate channel (email).
- `kba_questions` (string): If a KBA step requires the user to answer a challenge/differentiator question, the question(s) to ask.
- `locale` (string): The long-form timezone.
- `order` (integer, required): The order indicates the order in which recipients are listed in a single "level" of the workflow. Note that recipients at the same level may act in parallel despite this value. However, it can often be useful to visually arrange recipients to match related business processes so this field allows for that.
- `passcode` (string): If auth_method is set to "passcode" this is the passcode required. For security reasons, this field will only be visible to the creator of the envelope.
- `phone` (string): Phone number for SMS invites.
- `sequence` (integer, required): The sequence number indicates the order in which Recipients act. Multiple recipients may have the same sequence number, in which case they may act in parallel. (e.g. all Recipients at sequence 2 will receive invites once all Recipients at sequence 1 have signed.).
- `ssn_last_4` (string): Last 4 digits of SSN. Only used in KBA workflows.
- `state` (string): Zip code. Only used in KBA workflows.
- `timezone` (string): The locale code.
- `zip` (string): Zip code. Only used in KBA workflows.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/envelopes/ENVELOPE_ID/recipients/ROLE_NAME/agree" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Decline e-Signing Disclosures (/docs/reference/Rest-API/api-docs/recipients/envelopeRecipientDecline)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/envelopes/{envelope_id}/recipients/{role_name}/decline
`POST https://api.verdocs.com/v2/envelopes/{envelope_id}/recipients/{role_name}/decline`
### Path parameters
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The role to adjust.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IRecipient`
- `address` (string): Street address. Only used in KBA workflows. Combine two-line addresses into a single string.
- `auth_method_states` (string): The status of each auth method enabled.
- `auth_methods` (string): The types of authentication/verification required for this recipient.
- `auth_step` (string): The next verification step that must be performed.
- `city` (string): Zip code. Only used in KBA workflows.
- `disclosures` (string): The disclosure text the recipient accepted.
- `disclosures_accepted_at` (string): Date/time the recipient agreed to their e-signing disclosures.
- `dob` (string): Date of birth. Only used in KBA workflows.
- `full_name` (string): @deprecated. Use first_name/last_name instead.
- `id` (string): Used only by the Web SDK during builder processes. Not stored in the backend.
- `in_app_key` (string): Only returned in creation/getEnvelopeById requests by the creator. May be used for in-person signing. Note that signing sessions started with this key will be marked as "In App" authenticated. For higher authentication levels, e.g. email, the signer must follow a link send via the appropriate channel (email).
- `kba_questions` (string): If a KBA step requires the user to answer a challenge/differentiator question, the question(s) to ask.
- `locale` (string): The long-form timezone.
- `order` (integer, required): The order indicates the order in which recipients are listed in a single "level" of the workflow. Note that recipients at the same level may act in parallel despite this value. However, it can often be useful to visually arrange recipients to match related business processes so this field allows for that.
- `passcode` (string): If auth_method is set to "passcode" this is the passcode required. For security reasons, this field will only be visible to the creator of the envelope.
- `phone` (string): Phone number for SMS invites.
- `sequence` (integer, required): The sequence number indicates the order in which Recipients act. Multiple recipients may have the same sequence number, in which case they may act in parallel. (e.g. all Recipients at sequence 2 will receive invites once all Recipients at sequence 1 have signed.).
- `ssn_last_4` (string): Last 4 digits of SSN. Only used in KBA workflows.
- `state` (string): Zip code. Only used in KBA workflows.
- `timezone` (string): The locale code.
- `zip` (string): Zip code. Only used in KBA workflows.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/envelopes/ENVELOPE_ID/recipients/ROLE_NAME/decline" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Submit envelope (/docs/reference/Rest-API/api-docs/recipients/envelopeRecipientSubmit)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/envelopes/{envelope_id}/recipients/{role_name}/submit
`POST https://api.verdocs.com/v2/envelopes/{envelope_id}/recipients/{role_name}/submit`
### Path parameters
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The role to submit.
### Request body
Content type `application/json`, required. Body Parameters.
- `timezone` (string): Define the long-form timezone.
- `locale` (string): Define the locale code.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IRecipient`
- `address` (string): Street address. Only used in KBA workflows. Combine two-line addresses into a single string.
- `auth_method_states` (string): The status of each auth method enabled.
- `auth_methods` (string): The types of authentication/verification required for this recipient.
- `auth_step` (string): The next verification step that must be performed.
- `city` (string): Zip code. Only used in KBA workflows.
- `disclosures` (string): The disclosure text the recipient accepted.
- `disclosures_accepted_at` (string): Date/time the recipient agreed to their e-signing disclosures.
- `dob` (string): Date of birth. Only used in KBA workflows.
- `full_name` (string): @deprecated. Use first_name/last_name instead.
- `id` (string): Used only by the Web SDK during builder processes. Not stored in the backend.
- `in_app_key` (string): Only returned in creation/getEnvelopeById requests by the creator. May be used for in-person signing. Note that signing sessions started with this key will be marked as "In App" authenticated. For higher authentication levels, e.g. email, the signer must follow a link send via the appropriate channel (email).
- `kba_questions` (string): If a KBA step requires the user to answer a challenge/differentiator question, the question(s) to ask.
- `locale` (string): The long-form timezone.
- `order` (integer, required): The order indicates the order in which recipients are listed in a single "level" of the workflow. Note that recipients at the same level may act in parallel despite this value. However, it can often be useful to visually arrange recipients to match related business processes so this field allows for that.
- `passcode` (string): If auth_method is set to "passcode" this is the passcode required. For security reasons, this field will only be visible to the creator of the envelope.
- `phone` (string): Phone number for SMS invites.
- `sequence` (integer, required): The sequence number indicates the order in which Recipients act. Multiple recipients may have the same sequence number, in which case they may act in parallel. (e.g. all Recipients at sequence 2 will receive invites once all Recipients at sequence 1 have signed.).
- `ssn_last_4` (string): Last 4 digits of SSN. Only used in KBA workflows.
- `state` (string): Zip code. Only used in KBA workflows.
- `timezone` (string): The locale code.
- `zip` (string): Zip code. Only used in KBA workflows.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/envelopes/ENVELOPE_ID/recipients/ROLE_NAME/submit" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get In-Person Signing Link (/docs/reference/Rest-API/api-docs/recipients/getInPersonLink)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/sign/in-person/{envelope_id}/{role_name}
`POST https://api.verdocs.com/v2/sign/in-person/{envelope_id}/{role_name}`
### Path parameters
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The role to request.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IInPersonLinkResponse`
- `access_key` (string, required): The access key that matches the signing session. May be used for later initiation requests if in-person signing was desired, but not necessarily instant (e.g. to hand-off to a companion application. **NOTE: Access keys are as sensitive as Bearer Tokens and must be protected from theft and unauthorized sharing!**.
- `access_token` (string, required): An access token that may be used with a VerdocsEndpoint to perform signing operations. When signing, the caller's "authentication" status will be recorded as "in-person".
- `envelope` (string, required): A copy of the envelope related to the signing session. This is almost always needed when a signing session is being started, so it is included here for convenience.
- `link` (string, required): A valid Verdocs Web URL that hosts a signing experience.
- `recipient` (string, required): A copy of the recipient record related to the signing session. This is almost always needed when a signing session is being started, so it is included here for convenience.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/sign/in-person/ENVELOPE_ID/ROLE_NAME" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Request a fresh signing link (/docs/reference/Rest-API/api-docs/recipients/requestFreshSigningLink)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/sign/unauth/{envelope_id}/{role_name}/{key}/fresh-link
`POST https://api.verdocs.com/v2/sign/unauth/{envelope_id}/{role_name}/{key}/fresh-link`
### Path parameters
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The role requesting the link.
- `key` (string, required): The access key from the link the signer followed (it may be expired).
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/sign/unauth/ENVELOPE_ID/ROLE_NAME/KEY/fresh-link" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Start Signing Session (/docs/reference/Rest-API/api-docs/recipients/startSigningSession)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/sign/unauth/{envelope_id}/{role_name}/{key}
`POST https://api.verdocs.com/v2/sign/unauth/{envelope_id}/{role_name}/{key}`
### Path parameters
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The role to request.
- `key` (string, required): Access key generated by the envelope creator or email/SMS invite.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ISignerTokenResponse`
- `access_token` (string, required): An access token that may be used with a VerdocsEndpoint to perform signing operations. When signing, the caller's "authentication" status will be recorded as "in-person".
- `brand` (string): The org's default brand, if one is set. Contains style_overrides CSS and other branding fields.
- `envelope` (string, required): A copy of the envelope related to the signing session. This is almost always needed when a signing session is being started, so it is included here for convenience.
- `initials` (string): Stored initials blocks for the recipient. All entries are returned to support workflows in which that is required, but for most use-cases, only the first entry should be used.
- `recipient` (string, required): A copy of the recipient record related to the signing session. This is almost always needed when a signing session is being started, so it is included here for convenience.
- `signatures` (string): Stored signature blocks for the recipient. All entries are returned to support workflows in which that is required, but for most use-cases, only the first entry should be used.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/sign/unauth/ENVELOPE_ID/ROLE_NAME/KEY" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update Recipient (/docs/reference/Rest-API/api-docs/recipients/updateRecipient)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/envelopes/{envelope_id}/recipients/{role_name}
`PATCH https://api.verdocs.com/v2/envelopes/{envelope_id}/recipients/{role_name}`
### Path parameters
- `envelope_id` (string, uuid, required): The envelope to operate on.
- `role_name` (string, required): The role name to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `action` (string): Trigger a reminder, or fully reset the recipient. One of: `"remind"`, `"reset"`.
- `first_name` (string): Update the recipient's first name.
- `last_name` (string): Update the recipient's last name.
- `email` (string): Update the recipient's email address.
- `message` (string): Update the recipient's invite message.
- `phone` (string): Update the recipient's phone number.
- `passcode` (string): If passcode authentication is used, the recipient's address to prefill. May only be changed if the recipient has not already completed passcode-based auth.
- `address` (string): If KBA-based authentication is used, the recipient's address to prefill. May only be changed if the recipient has not already completed KBA-based auth.
- `city` (string): If KBA-based authentication is used, the recipient's city to prefill. May only be changed if the recipient has not already completed KBA-based auth.
- `state` (string): If KBA-based authentication is used, the recipient's state to prefill. May only be changed if the recipient has not already completed KBA-based auth.
- `zip` (string): If KBA-based authentication is used, the recipient's zip code to prefill. May only be changed if the recipient has not already completed KBA-based auth.
- `dob` (string): If KBA-based authentication is used, the recipient's date of birth to prefill. May only be changed if the recipient has not already completed KBA-based auth.
- `ssn_last_4` (string): If KBA-based authentication is used, the recipient's SSN-last-4 to prefill. May only be changed if the recipient has not already completed KBA-based auth.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IRecipient`
- `address` (string): Street address. Only used in KBA workflows. Combine two-line addresses into a single string.
- `auth_method_states` (string): The status of each auth method enabled.
- `auth_methods` (string): The types of authentication/verification required for this recipient.
- `auth_step` (string): The next verification step that must be performed.
- `city` (string): Zip code. Only used in KBA workflows.
- `disclosures` (string): The disclosure text the recipient accepted.
- `disclosures_accepted_at` (string): Date/time the recipient agreed to their e-signing disclosures.
- `dob` (string): Date of birth. Only used in KBA workflows.
- `full_name` (string): @deprecated. Use first_name/last_name instead.
- `id` (string): Used only by the Web SDK during builder processes. Not stored in the backend.
- `in_app_key` (string): Only returned in creation/getEnvelopeById requests by the creator. May be used for in-person signing. Note that signing sessions started with this key will be marked as "In App" authenticated. For higher authentication levels, e.g. email, the signer must follow a link send via the appropriate channel (email).
- `kba_questions` (string): If a KBA step requires the user to answer a challenge/differentiator question, the question(s) to ask.
- `locale` (string): The long-form timezone.
- `order` (integer, required): The order indicates the order in which recipients are listed in a single "level" of the workflow. Note that recipients at the same level may act in parallel despite this value. However, it can often be useful to visually arrange recipients to match related business processes so this field allows for that.
- `passcode` (string): If auth_method is set to "passcode" this is the passcode required. For security reasons, this field will only be visible to the creator of the envelope.
- `phone` (string): Phone number for SMS invites.
- `sequence` (integer, required): The sequence number indicates the order in which Recipients act. Multiple recipients may have the same sequence number, in which case they may act in parallel. (e.g. all Recipients at sequence 2 will receive invites once all Recipients at sequence 1 have signed.).
- `ssn_last_4` (string): Last 4 digits of SSN. Only used in KBA workflows.
- `state` (string): Zip code. Only used in KBA workflows.
- `timezone` (string): The locale code.
- `zip` (string): Zip code. Only used in KBA workflows.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/envelopes/ENVELOPE_ID/recipients/ROLE_NAME" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# signer (/docs/reference/Rest-API/api-docs/recipients/verifySigner)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/sign/verify
`POST https://api.verdocs.com/v2/sign/verify`
### Request body
Content type `application/json`, required. Body Parameters.
- `auth_method` (string, required): The authentication method being completed. One of: `"passcode"`, `"email"`, `"sms"`, `"kba"`, `"id"`.
- `code` (string): The passcode or OTP entered. Required for passcode, email, and SMS methods.
- `resend` (boolean): For SMS or email methods, set to send a new code.
- `first_name` (string): For KBA, the recipient's first name.
- `last_name` (string): For KBA, the recipient's last name.
- `address` (string): For KBA, the recipient's address.
- `city` (string): For KBA, the recipient's city.
- `state` (string): For KBA, the recipient's state.
- `zip` (string): For KBA, the recipient's zip code.
- `ssn_last_4` (string): For KBA, the last 4 digits of the recipient's SSN.
- `dob` (string): For KBA, the recipient's date of birthx.
- `sandbox` (string): For KBA, must have sandbox functionality unlocked. One of: `"pass"`, `"fail"`, `"questions"`.
- `responses` (IKBAResponse[]): For KBA, responses to any challenge questions presented.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ISignerTokenResponse`
- `access_token` (string, required): An access token that may be used with a VerdocsEndpoint to perform signing operations. When signing, the caller's "authentication" status will be recorded as "in-person".
- `brand` (string): The org's default brand, if one is set. Contains style_overrides CSS and other branding fields.
- `envelope` (string, required): A copy of the envelope related to the signing session. This is almost always needed when a signing session is being started, so it is included here for convenience.
- `initials` (string): Stored initials blocks for the recipient. All entries are returned to support workflows in which that is required, but for most use-cases, only the first entry should be used.
- `recipient` (string, required): A copy of the recipient record related to the signing session. This is almost always needed when a signing session is being started, so it is included here for convenience.
- `signatures` (string): Stored signature blocks for the recipient. All entries are returned to support workflows in which that is required, but for most use-cases, only the first entry should be used.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/sign/verify" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Arrange roles (/docs/reference/Rest-API/api-docs/roles/arrangeTemplateRoles)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/roles/{template_id}
`PATCH https://api.verdocs.com/v2/roles/{template_id}`
### Path parameters
- `template_id` (string, uuid, required): The template ID.
### Request body
Content type `application/json`, required. Body Parameters.
- `roles` (IRolePosition[], required): The roles to move, each with its new step (sequence) and optionally its place within the step (order).
- `name` (string, required): The role's name.
- `order` (integer): The role's place within its step, for display. Leave it out to keep the role's current order.
- `sequence` (integer, required): The step the role acts in. Roles that share a step are invited together.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IRole[]`
- `id` (string): Used only by the Web SDK during builder processes. Not stored in the backend.
- `name_locked` (boolean, required): If set, the recipient will not be allowed to change their legal name.
- `order` (integer, required): The order indicates the order in which recipients are listed in a single "level" of the workflow. Note that recipients at the same level may act in parallel despite this value. However, it can often be useful to visually arrange recipients to match related business processes so this field allows for that.
- `required` (boolean): False makes the role optional. A send from the template that leaves it out (no recipient for the role) drops the role and its fields. Defaults to true.
- `sequence` (integer, required): The sequence number indicates the order in which Roles act. Multiple roles may have the same sequence number, in which case they may act in parallel. (e.g. all Roles at sequence 2 will receive invites once all Recipients at sequence 1 have signed.).
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/roles/TEMPLATE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Add a role to a template (/docs/reference/Rest-API/api-docs/roles/createTemplateRole)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/roles/{template_id}
`POST https://api.verdocs.com/v2/roles/{template_id}`
### Path parameters
- `template_id` (string, uuid, required): The template ID.
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string, required): Name for the new role. Must be unique within the template. May include spaces, but later calls must URL-encode any references to this role, so it is recomended that special characters be avoided.
- `type` (string, required): Type of role to create. Signers act on documents by filling and signing fields. CC recipients receive a copy but do not act on the document. Approvers control the final submission of a document, but do not have fields of their own to fill out. One of: `"signer"`, `"cc"`, `"approver"`.
- `full_name` (string): Default full name for the role. May be completed/overridden later, when envelopes are made from the template.
- `email` (string): Default email address for the role. May be completed/overridden later, when envelopes are made from the template.
- `phone` (string): Default (SMS-capable) phone number for the role. May be completed/overridden later, when envelopes are made from the template.
- `message` (string): Optional message to include in email and SMS signing invitations.
- `sequence` (integer): Optional 1-based sequence number for the role. Roles that share the same sequence number act in parallel, and will receive invitations at the same time. Default: `1`.
- `order` (integer): Optional 1-based order number for the role. Controls the left-to-right display order of roles at the same sequence number in the UI components e.g. ``. Default: `1`.
- `delegator` (boolean): If true, the role may delegate their signing responsibility to another party.
- `required` (boolean): False makes the role optional, so a send from the template may leave it out. Defaults to true.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IRole`
A placeholder for an individual recipient, CC, or other party in a signing flow. Roles may be "known" or "unknown." "Known" roles will have their email address supplied in the template which will get copied to envelopes created from it. This is used when a certain party will always be the same, e.g. a leasing agent counter-signing a lease. "Unknown" roles are dynamic, and will be filled in later when the envelope is created.
- `id` (string): Used only by the Web SDK during builder processes. Not stored in the backend.
- `name_locked` (boolean, required): If set, the recipient will not be allowed to change their legal name.
- `order` (integer, required): The order indicates the order in which recipients are listed in a single "level" of the workflow. Note that recipients at the same level may act in parallel despite this value. However, it can often be useful to visually arrange recipients to match related business processes so this field allows for that.
- `required` (boolean): False makes the role optional. A send from the template that leaves it out (no recipient for the role) drops the role and its fields. Defaults to true.
- `sequence` (integer, required): The sequence number indicates the order in which Roles act. Multiple roles may have the same sequence number, in which case they may act in parallel. (e.g. all Roles at sequence 2 will receive invites once all Recipients at sequence 1 have signed.).
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/roles/TEMPLATE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete a role. (/docs/reference/Rest-API/api-docs/roles/deleteTemplateRole)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/roles/{template_id}/{role_name}
`DELETE https://api.verdocs.com/v2/roles/{template_id}/{role_name}`
### Path parameters
- `template_id` (string, uuid, required): The template ID.
- `role_name` (string, required): The role name to delete.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/roles/TEMPLATE_ID/ROLE_NAME" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update a role (/docs/reference/Rest-API/api-docs/roles/updateTemplateRole)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/roles/{template_id}/{role_name}
`PATCH https://api.verdocs.com/v2/roles/{template_id}/{role_name}`
### Path parameters
- `template_id` (string, uuid, required): The template ID.
- `role_name` (string, required): The role name to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string): Rename the role. Note that role names must be unique within a template, so this may fail if the new name is already in use.
- `type` (string): Type of role. One of: `"signer"`, `"cc"`, `"approver"`.
- `full_name` (string): Default full name for the role.
- `email` (string): Default email address for the role.
- `phone` (string): Default (SMS-capable) phone number for the role.
- `message` (string): Optional message to include in email and SMS signing invitations.
- `sequence` (integer): Optional 1-based sequence number for the role. Default: `1`.
- `order` (integer): Optional 1-based order number for the role. Default: `1`.
- `delegator` (boolean): If true, the role may delegate their signing responsibility to another party.
- `kba_method` (string): Active PIN- or Identity-based KBA for the role. One of: `"pin"`, `"identity"`, `0`.
- `required` (boolean): False makes the role optional, so a send from the template may leave it out.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IRole`
A placeholder for an individual recipient, CC, or other party in a signing flow. Roles may be "known" or "unknown." "Known" roles will have their email address supplied in the template which will get copied to envelopes created from it. This is used when a certain party will always be the same, e.g. a leasing agent counter-signing a lease. "Unknown" roles are dynamic, and will be filled in later when the envelope is created.
- `id` (string): Used only by the Web SDK during builder processes. Not stored in the backend.
- `name_locked` (boolean, required): If set, the recipient will not be allowed to change their legal name.
- `order` (integer, required): The order indicates the order in which recipients are listed in a single "level" of the workflow. Note that recipients at the same level may act in parallel despite this value. However, it can often be useful to visually arrange recipients to match related business processes so this field allows for that.
- `required` (boolean): False makes the role optional. A send from the template that leaves it out (no recipient for the role) drops the role and its fields. Defaults to true.
- `sequence` (integer, required): The sequence number indicates the order in which Roles act. Multiple roles may have the same sequence number, in which case they may act in parallel. (e.g. all Roles at sequence 2 will receive invites once all Recipients at sequence 1 have signed.).
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/roles/TEMPLATE_ID/ROLE_NAME" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# End the caller's current login session (/docs/reference/Rest-API/api-docs/sessions/endCurrentSession)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/users/sessions/current
`DELETE https://api.verdocs.com/v2/users/sessions/current`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IEndSessionResponse`
The result of ending the caller's current session.
- `ended` (boolean, required): False if there was no login session to end.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/users/sessions/current" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get the caller's active login sessions (/docs/reference/Rest-API/api-docs/sessions/getSessions)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/users/sessions
`GET https://api.verdocs.com/v2/users/sessions`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IUserLoginSession[]`
- `browser` (string, required): We don't store the full User-Agent (to prevent its reuse in replay attacks) but we do track the browser name, platform, and desktop/mobile.
- `ip_address` (string, required): Partially-masked IP address the session was created from e.g. '73.***.***.14'. NOTE: Per our Privacy Policy and EULA we do track and store full IP addresses internally. Document signing sessions do not have the same expectation of privacy that other Web-based operations often do. We mask them here in this record because these sessions may or may not be signing documents so a full IP is not needed.
- `location` (string, required): We don't track fine-grained location data but we do track approximate location eg. City/State/Country.
- `source` (string, required): Typically a TSignInProvider, but typed as a string to allow patterns e.g. 'oauth2:CLIENTID'.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/users/sessions" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Revoke all of the caller's sessions except the current one (/docs/reference/Rest-API/api-docs/sessions/revokeOtherSessions)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/users/sessions
`DELETE https://api.verdocs.com/v2/users/sessions`
### Responses
#### 200: Success
Content type `application/json`.
- `revoked` (integer, int32): The number of sessions revoked.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/users/sessions" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Revoke one of the caller's login sessions (/docs/reference/Rest-API/api-docs/sessions/revokeSession)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/users/sessions/{session_id}
`DELETE https://api.verdocs.com/v2/users/sessions/{session_id}`
### Path parameters
- `session_id` (string, required): The ID of the session to revoke. May not be the caller's current session.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/users/sessions/SESSION_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create Initial Block (/docs/reference/Rest-API/api-docs/signatures-and-initials/createInitials)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/profiles/initials
`POST https://api.verdocs.com/v2/profiles/initials`
### Request body
Content type `application/json`, required. Body Parameters.
- `initial` (string, required): Blob containing initials image to store.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IInitial`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/profiles/initials" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create Signature Block (/docs/reference/Rest-API/api-docs/signatures-and-initials/createSignature)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/profiles/signatures
`POST https://api.verdocs.com/v2/profiles/signatures`
### Request body
Content type `application/json`, required. Body Parameters.
- `signature` (string, required): Blob containing signature image to store.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ISignature`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/profiles/signatures" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Attach a document to a template (/docs/reference/Rest-API/api-docs/template-documents/createTemplateDocument)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/template-documents
`POST https://api.verdocs.com/v2/template-documents`
### Request body
Content type `application/json`, required. Body Parameters.
- `file` (string, binary, required): Document file to attach. The file name will automatically be used as the document name.
- `template_id` (string, uuid, required): Template ID to attach the document to.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplateDocument`
A file attached to the template for display/signing.
- `page_numbers` (integer): @deprecated. Use pages instead.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/template-documents" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete a template document (/docs/reference/Rest-API/api-docs/template-documents/deleteTemplateDocument)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/template-documents/{document_id}
`DELETE https://api.verdocs.com/v2/template-documents/{document_id}`
### Path parameters
- `document_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplate`
A reusable template for creating signable instruments. Templates are used to create Envelopes which contain Documents to sign.
- `counter` (integer, required): Number of times the template has been used.
- `created_at` (string, required): Creation date/time.
- `data` (string, required): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Templates back to internal systems/applications.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Templates start with the organization's default and keep it if the default changes.
- `description` (string): Optional description for the template.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): The unique ID of the template.
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `is_personal` (boolean, required): If true, the template is only visible to the creator. If false, the template will also be visible to the user's organization, if any. @deprecated. See "visibility".
- `is_public` (boolean, required): If true, the template is visible publicly. Note that this does not necessarily mean it is also visible to the user's organization. It may be desirable to create documents that are public but that do not appear in the organization's shared templates list. To achieve this, set both.
- `is_sendable` (boolean, required): If true, the template is considered "sendable" (it has at least one signer, and every signer has at least one field.).
- `last_used_at` (string, required): Last-used date/time (when the template was used to create a document).
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `organization_id` (string, required): Organization the template lives in.
- `profile_id` (string, required): The template's owner/creator.
- `sender` (string, required): Who will "own" envelopes created from this template. Note that while either option is technically allowed for all visibility settings, "template_owner" only has an effect if visibility is "shared" or "public".
- `star_counter` (integer, required): Number of times the template has been "starred".
- `template_documents` (string): @deprecated. Use documents instead.
- `updated_at` (string, required): Last-update date/time.
- `visibility` (string): If set, the visibility level for the template.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/template-documents/DOCUMENT_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get template document (/docs/reference/Rest-API/api-docs/template-documents/getTemplateDocument)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/template-documents/{id}
`GET https://api.verdocs.com/v2/template-documents/{id}`
### Path parameters
- `id` (string, uuid, required): The ID of the document to retrieve.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplateDocument`
A file attached to the template for display/signing.
- `page_numbers` (integer): @deprecated. Use pages instead.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/template-documents/ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get template document page display URI (/docs/reference/Rest-API/api-docs/template-documents/getTemplateDocumentPageDisplayUri)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/template-documents/page-image/{document_id}/{variant}/{page}
`GET https://api.verdocs.com/v2/template-documents/page-image/{document_id}/{variant}/{page}`
### Path parameters
- `document_id` (string, uuid, required): The ID of the document to retrieve.
- `variant` (string, required): The variant of the document to retrieve. One of: `"original"`, `"tagged"`.
- `page` (integer, required): The page number to retrieve.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/template-documents/page-image/DOCUMENT_ID/VARIANT/PAGE" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get template document preview link (/docs/reference/Rest-API/api-docs/template-documents/getTemplateDocumentPreviewLink)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/template-documents/{document_id}
`GET https://api.verdocs.com/v2/template-documents/{document_id}`
### Path parameters
- `document_id` (string, uuid, required): The ID of the document to retrieve.
### Query parameters
- `type` (string, required): Generate a preview link. One of: `"preview"`.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/template-documents/DOCUMENT_ID?param=value" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Download template document thumbnail (/docs/reference/Rest-API/api-docs/template-documents/getTemplateDocumentThumbnail)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/templates/{template_id}/documents/{document_id}
`GET https://api.verdocs.com/v2/templates/{template_id}/documents/{document_id}`
### Path parameters
- `template_id` (string, uuid, required): The template ID.
- `document_id` (string, uuid, required): The document ID to retrieve.
### Query parameters
- `thumbnail` (boolean, required): Return the thumbnail image bytes. Default: `"true"`.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string, binary`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/templates/TEMPLATE_ID/documents/DOCUMENT_ID?param=value" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update a template document (/docs/reference/Rest-API/api-docs/template-documents/updateTemplateDocument)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/template-documents/{document_id}
`PATCH https://api.verdocs.com/v2/template-documents/{document_id}`
### Path parameters
- `document_id` (string, uuid, required): The ID of the document to update.
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string): New name for the document.
- `order` (integer): New 1-based position for the document. A position past the end moves it last.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplate`
A reusable template for creating signable instruments. Templates are used to create Envelopes which contain Documents to sign.
- `counter` (integer, required): Number of times the template has been used.
- `created_at` (string, required): Creation date/time.
- `data` (string, required): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Templates back to internal systems/applications.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Templates start with the organization's default and keep it if the default changes.
- `description` (string): Optional description for the template.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): The unique ID of the template.
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `is_personal` (boolean, required): If true, the template is only visible to the creator. If false, the template will also be visible to the user's organization, if any. @deprecated. See "visibility".
- `is_public` (boolean, required): If true, the template is visible publicly. Note that this does not necessarily mean it is also visible to the user's organization. It may be desirable to create documents that are public but that do not appear in the organization's shared templates list. To achieve this, set both.
- `is_sendable` (boolean, required): If true, the template is considered "sendable" (it has at least one signer, and every signer has at least one field.).
- `last_used_at` (string, required): Last-used date/time (when the template was used to create a document).
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `organization_id` (string, required): Organization the template lives in.
- `profile_id` (string, required): The template's owner/creator.
- `sender` (string, required): Who will "own" envelopes created from this template. Note that while either option is technically allowed for all visibility settings, "template_owner" only has an effect if visibility is "shared" or "public".
- `star_counter` (integer, required): Number of times the template has been "starred".
- `template_documents` (string): @deprecated. Use documents instead.
- `updated_at` (string, required): Last-update date/time.
- `visibility` (string): If set, the visibility level for the template.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/template-documents/DOCUMENT_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create a template (/docs/reference/Rest-API/api-docs/templates/createTemplate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/templates
`POST https://api.verdocs.com/v2/templates`
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string, required): Template name.
- `description` (string): Optional description.
- `visibility` (TTemplateVisibility): Visibility setting. One of: `"private"`, `"shared"`, `"public"`.
- `is_personal` (boolean): Deprecated. If true, the template is personal and can only be seen by the caller. (Use "visibility" for new calls.).
- `is_public` (boolean): Deprecated. If true, the template is public and can be seen by anybody. (Use "visibility" for new calls.).
- `sender` (TTemplateSender): Who may send envelopes using this template. One of: `"envelope_creator"`, `"template_owner"`.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Defaults to the organization's current default, which the template keeps if the default changes.
- `initial_reminder` (number): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `followup_reminders` (number): Delay (in seconds) before the subsequent reminders are sent (min: 12hrs). Set to 0 or null to disable.
- `max_reminder_days` (number): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `documents` (object[]): Optional list of documents to attach to the template.
- `roles` (IRole[]): Optional list of roles to create. Note that if roles are not included in the request, fields will be ignored.
- `id` (string): Used only by the Web SDK during builder processes. Not stored in the backend.
- `name_locked` (boolean, required): If set, the recipient will not be allowed to change their legal name.
- `order` (integer, required): The order indicates the order in which recipients are listed in a single "level" of the workflow. Note that recipients at the same level may act in parallel despite this value. However, it can often be useful to visually arrange recipients to match related business processes so this field allows for that.
- `required` (boolean): False makes the role optional. A send from the template that leaves it out (no recipient for the role) drops the role and its fields. Defaults to true.
- `sequence` (integer, required): The sequence number indicates the order in which Roles act. Multiple roles may have the same sequence number, in which case they may act in parallel. (e.g. all Roles at sequence 2 will receive invites once all Recipients at sequence 1 have signed.).
- `fields` (array): Optional list of fields to create. Note that if fields that do not match a role will be ignored.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplate`
A reusable template for creating signable instruments. Templates are used to create Envelopes which contain Documents to sign.
- `counter` (integer, required): Number of times the template has been used.
- `created_at` (string, required): Creation date/time.
- `data` (string, required): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Templates back to internal systems/applications.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Templates start with the organization's default and keep it if the default changes.
- `description` (string): Optional description for the template.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): The unique ID of the template.
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `is_personal` (boolean, required): If true, the template is only visible to the creator. If false, the template will also be visible to the user's organization, if any. @deprecated. See "visibility".
- `is_public` (boolean, required): If true, the template is visible publicly. Note that this does not necessarily mean it is also visible to the user's organization. It may be desirable to create documents that are public but that do not appear in the organization's shared templates list. To achieve this, set both.
- `is_sendable` (boolean, required): If true, the template is considered "sendable" (it has at least one signer, and every signer has at least one field.).
- `last_used_at` (string, required): Last-used date/time (when the template was used to create a document).
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `organization_id` (string, required): Organization the template lives in.
- `profile_id` (string, required): The template's owner/creator.
- `sender` (string, required): Who will "own" envelopes created from this template. Note that while either option is technically allowed for all visibility settings, "template_owner" only has an effect if visibility is "shared" or "public".
- `star_counter` (integer, required): Number of times the template has been "starred".
- `template_documents` (string): @deprecated. Use documents instead.
- `updated_at` (string, required): Last-update date/time.
- `visibility` (string): If set, the visibility level for the template.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/templates" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Suggest field cleanup for a template (/docs/reference/Rest-API/api-docs/templates/createTemplateAnalysis)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/templates/{template_id}/analyses
`POST https://api.verdocs.com/v2/templates/{template_id}/analyses`
### Path parameters
- `template_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplateAnalysis`
A model's suggested cleanup of a template's fields.
- `completed_at` (string, required): When the analysis finished.
- `created_at` (string, required): When the analysis was requested.
- `effort` (string, required): The effort level it ran at.
- `error` (string, required): What went wrong, when any page failed.
- `id` (string, required): The analysis ID.
- `model` (string, required): The Bedrock model that ran it.
- `organization_id` (string, required): The organization that owns the template.
- `pages_done` (integer, required): Pages finished so far, including any that failed.
- `pages_total` (integer, required): Pages to analyze: those with fields, or every page when the template has none.
- `profile_id` (string, required): Who asked for the analysis.
- `result` (string): The suggestions per page, once complete. Only getTemplateAnalysis includes them.
- `status` (string, required): Poll until this is "complete" or "failed".
- `template_id` (string, required): The template analyzed.
- `updated_at` (string, required): When the analysis last changed.
- `usage` (string, required): Token totals across every page.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/templates/TEMPLATE_ID/analyses" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Create a template from an asset in Sharepoint (/docs/reference/Rest-API/api-docs/templates/createTemplateFromSharepoint)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/templates/from-sharepoint
`POST https://api.verdocs.com/v2/templates/from-sharepoint`
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string, required): Name for the new template.
- `siteId` (string, required): Name for the new template.
- `itemId` (string, required): Name for the new template.
- `oboToken` (string, required): On-Behalf-Of token for calls to Sharepoint. Should be generated as a short-expiration token with at least Read privileges to the siteId/itemId. This token will be discarded after being used.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplate`
A reusable template for creating signable instruments. Templates are used to create Envelopes which contain Documents to sign.
- `counter` (integer, required): Number of times the template has been used.
- `created_at` (string, required): Creation date/time.
- `data` (string, required): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Templates back to internal systems/applications.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Templates start with the organization's default and keep it if the default changes.
- `description` (string): Optional description for the template.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): The unique ID of the template.
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `is_personal` (boolean, required): If true, the template is only visible to the creator. If false, the template will also be visible to the user's organization, if any. @deprecated. See "visibility".
- `is_public` (boolean, required): If true, the template is visible publicly. Note that this does not necessarily mean it is also visible to the user's organization. It may be desirable to create documents that are public but that do not appear in the organization's shared templates list. To achieve this, set both.
- `is_sendable` (boolean, required): If true, the template is considered "sendable" (it has at least one signer, and every signer has at least one field.).
- `last_used_at` (string, required): Last-used date/time (when the template was used to create a document).
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `organization_id` (string, required): Organization the template lives in.
- `profile_id` (string, required): The template's owner/creator.
- `sender` (string, required): Who will "own" envelopes created from this template. Note that while either option is technically allowed for all visibility settings, "template_owner" only has an effect if visibility is "shared" or "public".
- `star_counter` (integer, required): Number of times the template has been "starred".
- `template_documents` (string): @deprecated. Use documents instead.
- `updated_at` (string, required): Last-update date/time.
- `visibility` (string): If set, the visibility level for the template.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/templates/from-sharepoint" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Delete a template (/docs/reference/Rest-API/api-docs/templates/deleteTemplate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## DELETE /v2/templates/{template_id}
`DELETE https://api.verdocs.com/v2/templates/{template_id}`
### Path parameters
- `template_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X DELETE "https://api.verdocs.com/v2/templates/TEMPLATE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Perform an operation on a template (/docs/reference/Rest-API/api-docs/templates/duplicateTemplate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PUT /v2/templates/{template_id}
`PUT https://api.verdocs.com/v2/templates/{template_id}`
### Path parameters
- `template_id` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `action` (string, required): Action to perform. One of: `"duplicate"`.
- `name` (string): If duplicating the template, a name for the new copy.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplate`
A reusable template for creating signable instruments. Templates are used to create Envelopes which contain Documents to sign.
- `counter` (integer, required): Number of times the template has been used.
- `created_at` (string, required): Creation date/time.
- `data` (string, required): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Templates back to internal systems/applications.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Templates start with the organization's default and keep it if the default changes.
- `description` (string): Optional description for the template.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): The unique ID of the template.
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `is_personal` (boolean, required): If true, the template is only visible to the creator. If false, the template will also be visible to the user's organization, if any. @deprecated. See "visibility".
- `is_public` (boolean, required): If true, the template is visible publicly. Note that this does not necessarily mean it is also visible to the user's organization. It may be desirable to create documents that are public but that do not appear in the organization's shared templates list. To achieve this, set both.
- `is_sendable` (boolean, required): If true, the template is considered "sendable" (it has at least one signer, and every signer has at least one field.).
- `last_used_at` (string, required): Last-used date/time (when the template was used to create a document).
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `organization_id` (string, required): Organization the template lives in.
- `profile_id` (string, required): The template's owner/creator.
- `sender` (string, required): Who will "own" envelopes created from this template. Note that while either option is technically allowed for all visibility settings, "template_owner" only has an effect if visibility is "shared" or "public".
- `star_counter` (integer, required): Number of times the template has been "starred".
- `template_documents` (string): @deprecated. Use documents instead.
- `updated_at` (string, required): Last-update date/time.
- `visibility` (string): If set, the visibility level for the template.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PUT "https://api.verdocs.com/v2/templates/TEMPLATE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get a template. (/docs/reference/Rest-API/api-docs/templates/getTemplate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/templates/{template_id}
`GET https://api.verdocs.com/v2/templates/{template_id}`
### Path parameters
- `template_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplate`
A reusable template for creating signable instruments. Templates are used to create Envelopes which contain Documents to sign.
- `counter` (integer, required): Number of times the template has been used.
- `created_at` (string, required): Creation date/time.
- `data` (string, required): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Templates back to internal systems/applications.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Templates start with the organization's default and keep it if the default changes.
- `description` (string): Optional description for the template.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): The unique ID of the template.
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `is_personal` (boolean, required): If true, the template is only visible to the creator. If false, the template will also be visible to the user's organization, if any. @deprecated. See "visibility".
- `is_public` (boolean, required): If true, the template is visible publicly. Note that this does not necessarily mean it is also visible to the user's organization. It may be desirable to create documents that are public but that do not appear in the organization's shared templates list. To achieve this, set both.
- `is_sendable` (boolean, required): If true, the template is considered "sendable" (it has at least one signer, and every signer has at least one field.).
- `last_used_at` (string, required): Last-used date/time (when the template was used to create a document).
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `organization_id` (string, required): Organization the template lives in.
- `profile_id` (string, required): The template's owner/creator.
- `sender` (string, required): Who will "own" envelopes created from this template. Note that while either option is technically allowed for all visibility settings, "template_owner" only has an effect if visibility is "shared" or "public".
- `star_counter` (integer, required): Number of times the template has been "starred".
- `template_documents` (string): @deprecated. Use documents instead.
- `updated_at` (string, required): Last-update date/time.
- `visibility` (string): If set, the visibility level for the template.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/templates/TEMPLATE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# List a template's analyses (/docs/reference/Rest-API/api-docs/templates/getTemplateAnalyses)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/templates/{template_id}/analyses
`GET https://api.verdocs.com/v2/templates/{template_id}/analyses`
### Path parameters
- `template_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplateAnalysis[]`
- `completed_at` (string, required): When the analysis finished.
- `created_at` (string, required): When the analysis was requested.
- `effort` (string, required): The effort level it ran at.
- `error` (string, required): What went wrong, when any page failed.
- `id` (string, required): The analysis ID.
- `model` (string, required): The Bedrock model that ran it.
- `organization_id` (string, required): The organization that owns the template.
- `pages_done` (integer, required): Pages finished so far, including any that failed.
- `pages_total` (integer, required): Pages to analyze: those with fields, or every page when the template has none.
- `profile_id` (string, required): Who asked for the analysis.
- `result` (string): The suggestions per page, once complete. Only getTemplateAnalysis includes them.
- `status` (string, required): Poll until this is "complete" or "failed".
- `template_id` (string, required): The template analyzed.
- `updated_at` (string, required): When the analysis last changed.
- `usage` (string, required): Token totals across every page.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/templates/TEMPLATE_ID/analyses" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get a template analysis (/docs/reference/Rest-API/api-docs/templates/getTemplateAnalysis)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/templates/{template_id}/analyses/{analysis_id}
`GET https://api.verdocs.com/v2/templates/{template_id}/analyses/{analysis_id}`
### Path parameters
- `template_id` (string, required)
- `analysis_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplateAnalysis`
A model's suggested cleanup of a template's fields.
- `completed_at` (string, required): When the analysis finished.
- `created_at` (string, required): When the analysis was requested.
- `effort` (string, required): The effort level it ran at.
- `error` (string, required): What went wrong, when any page failed.
- `id` (string, required): The analysis ID.
- `model` (string, required): The Bedrock model that ran it.
- `organization_id` (string, required): The organization that owns the template.
- `pages_done` (integer, required): Pages finished so far, including any that failed.
- `pages_total` (integer, required): Pages to analyze: those with fields, or every page when the template has none.
- `profile_id` (string, required): Who asked for the analysis.
- `result` (string): The suggestions per page, once complete. Only getTemplateAnalysis includes them.
- `status` (string, required): Poll until this is "complete" or "failed".
- `template_id` (string, required): The template analyzed.
- `updated_at` (string, required): When the analysis last changed.
- `usage` (string, required): Token totals across every page.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/templates/TEMPLATE_ID/analyses/ANALYSIS_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get a template's data contract (/docs/reference/Rest-API/api-docs/templates/getTemplateDataContract)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/templates/{template_id}/data-contract
`GET https://api.verdocs.com/v2/templates/{template_id}/data-contract`
### Path parameters
- `template_id` (string, required)
### Responses
#### 200: Success
Content type `application/json`.
Type: `IDataContract`
- `contract_hash` (string, required): Changes only when the keys, their types, whether they're needed, or their options change.
- `json_schema` (string, required): A JSON Schema for the prefill_data this template accepts.
- `keys` (string, required): Every data key the template's fields use, sorted by key.
- `template_id` (string, required): The template this contract describes.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/templates/TEMPLATE_ID/data-contract" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get Templates (/docs/reference/Rest-API/api-docs/templates/getTemplates)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/templates
`GET https://api.verdocs.com/v2/templates`
### Query parameters
- `q` (string): Find templates whose names/descriptions contain the specified query string.
- `is_starred` (boolean): If true, returns only templates with at least one "star".
- `is_creator` (boolean): If true, returns only templates that the caller created.
- `visibility` (string): Return only templates with the specified visibility. One of: `"private_shared"`, `"private"`, `"shared"`, `"public"`.
- `sort_by` (string): Return results sorted by this criteria. One of: `"created_at"`, `"updated_at"`, `"name"`, `"last_used_at"`, `"counter"`, `"star_counter"`.
- `ascending` (boolean): Set true/false to override the sort direction. Note that the default depends on `sort_by`. Date-based sorts default to descending, while name defaults to ascending.
- `rows` (integer): Limit the number of rows returned (max 100). Default: `10`.
- `page` (integer): Specify which page of results to return. Default: `0`.
### Responses
#### 200: Success
Content type `application/json`.
- `count` (integer, int32): The total number of records matching the query, helpful for pagination.
- `rows` (integer, int32): The number of rows returned in this response page.
- `page` (integer, int32): The page number of this response.
- `templates` (ITemplate[]): List of templates found.
- `counter` (integer, required): Number of times the template has been used.
- `created_at` (string, required): Creation date/time.
- `data` (string, required): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Templates back to internal systems/applications.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Templates start with the organization's default and keep it if the default changes.
- `description` (string): Optional description for the template.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): The unique ID of the template.
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `is_personal` (boolean, required): If true, the template is only visible to the creator. If false, the template will also be visible to the user's organization, if any. @deprecated. See "visibility".
- `is_public` (boolean, required): If true, the template is visible publicly. Note that this does not necessarily mean it is also visible to the user's organization. It may be desirable to create documents that are public but that do not appear in the organization's shared templates list. To achieve this, set both.
- `is_sendable` (boolean, required): If true, the template is considered "sendable" (it has at least one signer, and every signer has at least one field.).
- `last_used_at` (string, required): Last-used date/time (when the template was used to create a document).
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `organization_id` (string, required): Organization the template lives in.
- `profile_id` (string, required): The template's owner/creator.
- `sender` (string, required): Who will "own" envelopes created from this template. Note that while either option is technically allowed for all visibility settings, "template_owner" only has an effect if visibility is "shared" or "public".
- `star_counter` (integer, required): Number of times the template has been "starred".
- `template_documents` (string): @deprecated. Use documents instead.
- `updated_at` (string, required): Last-update date/time.
- `visibility` (string): If set, the visibility level for the template.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/templates?param=value" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Send template feedback (/docs/reference/Rest-API/api-docs/templates/sendTemplateFeedback)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/templates/{template_id}/feedback
`POST https://api.verdocs.com/v2/templates/{template_id}/feedback`
### Path parameters
- `template_id` (string, uuid, required): The template ID the feedback refers to.
### Request body
Content type `application/json`, required. Body Parameters.
- `comments` (string, required): Feedback body, max 4000 chars.
- `source` (string): The part of the app the feedback came from, e.g. "field-suggestions". Max 64 characters.
- `page` (integer): The page the sender was viewing (1-based).
- `page_count` (integer): Total pages in the template's documents.
- `scroll_percent` (number): How far down the document the sender had scrolled, from 0 to 100.
- `viewport` (string): Browser viewport size, e.g. "1440x900".
- `screen` (string): Screen size, e.g. "2560x1440".
- `zoom` (number): Zoom level of the document view, e.g. 1.25.
- `language` (string): Browser language, e.g. "en-US".
- `url` (string): URL of the page the feedback came from.
### Responses
#### 200: Success
Content type `application/json`.
Type: `string`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/templates/TEMPLATE_ID/feedback" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Toggle template star (/docs/reference/Rest-API/api-docs/templates/toggleTemplateStar)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/templates/{template_id}/stars/toggle
`POST https://api.verdocs.com/v2/templates/{template_id}/stars/toggle`
### Path parameters
- `template_id` (string, uuid, required): The template to star or unstar.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplate`
A reusable template for creating signable instruments. Templates are used to create Envelopes which contain Documents to sign.
- `counter` (integer, required): Number of times the template has been used.
- `created_at` (string, required): Creation date/time.
- `data` (string, required): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Templates back to internal systems/applications.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Templates start with the organization's default and keep it if the default changes.
- `description` (string): Optional description for the template.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): The unique ID of the template.
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `is_personal` (boolean, required): If true, the template is only visible to the creator. If false, the template will also be visible to the user's organization, if any. @deprecated. See "visibility".
- `is_public` (boolean, required): If true, the template is visible publicly. Note that this does not necessarily mean it is also visible to the user's organization. It may be desirable to create documents that are public but that do not appear in the organization's shared templates list. To achieve this, set both.
- `is_sendable` (boolean, required): If true, the template is considered "sendable" (it has at least one signer, and every signer has at least one field.).
- `last_used_at` (string, required): Last-used date/time (when the template was used to create a document).
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `organization_id` (string, required): Organization the template lives in.
- `profile_id` (string, required): The template's owner/creator.
- `sender` (string, required): Who will "own" envelopes created from this template. Note that while either option is technically allowed for all visibility settings, "template_owner" only has an effect if visibility is "shared" or "public".
- `star_counter` (integer, required): Number of times the template has been "starred".
- `template_documents` (string): @deprecated. Use documents instead.
- `updated_at` (string, required): Last-update date/time.
- `visibility` (string): If set, the visibility level for the template.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/templates/TEMPLATE_ID/stars/toggle" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update a template (/docs/reference/Rest-API/api-docs/templates/updateTemplate)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## PATCH /v2/templates/{template_id}
`PATCH https://api.verdocs.com/v2/templates/{template_id}`
### Path parameters
- `template_id` (string, required)
### Request body
Content type `application/json`, required. Body Parameters.
- `name` (string): Template name.
- `description` (string): Optional description.
- `visibility` (TTemplateVisibility): Visibility setting. One of: `"private"`, `"shared"`, `"public"`.
- `is_personal` (boolean): Deprecated. If true, the template is personal and can only be seen by the caller. (Use "visibility" for new calls.).
- `is_public` (boolean): Deprecated. If true, the template is public and can be seen by anybody. (Use "visibility" for new calls.).
- `sender` (TTemplateSender): Who may send envelopes using this template. One of: `"envelope_creator"`, `"template_owner"`.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Null switches it to the organization's current default.
- `initial_reminder` (number): Delay in ms before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `followup_reminders` (number): Delay in ms before the subsequent reminders are sent (min: 12hrs). Set to 0 or null to disable.
- `max_reminder_days` (number): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
### Responses
#### 200: Success
Content type `application/json`.
Type: `ITemplate`
A reusable template for creating signable instruments. Templates are used to create Envelopes which contain Documents to sign.
- `counter` (integer, required): Number of times the template has been used.
- `created_at` (string, required): Creation date/time.
- `data` (string, required): Storage for arbitrary data that may be used e.g. to track source database/record IDs to relate Templates back to internal systems/applications.
- `data_catalog_id` (string): The data catalog its fields' data keys come from. Templates start with the organization's default and keep it if the default changes.
- `description` (string): Optional description for the template.
- `followup_reminders` (string, required): Delay (in seconds) before subsequent remidners are sent (min: 12hrs). Set to 0 or null to disable.
- `id` (string, required): The unique ID of the template.
- `initial_reminder` (string, required): Delay (in seconds) before the first reminder is sent (min: 4hrs). Set to 0 or null to disable.
- `is_personal` (boolean, required): If true, the template is only visible to the creator. If false, the template will also be visible to the user's organization, if any. @deprecated. See "visibility".
- `is_public` (boolean, required): If true, the template is visible publicly. Note that this does not necessarily mean it is also visible to the user's organization. It may be desirable to create documents that are public but that do not appear in the organization's shared templates list. To achieve this, set both.
- `is_sendable` (boolean, required): If true, the template is considered "sendable" (it has at least one signer, and every signer has at least one field.).
- `last_used_at` (string, required): Last-used date/time (when the template was used to create a document).
- `max_reminder_days` (integer, required): Maximum number of days (after envelope creation) for which reminders will be sent. Defaults to 14.
- `organization_id` (string, required): Organization the template lives in.
- `profile_id` (string, required): The template's owner/creator.
- `sender` (string, required): Who will "own" envelopes created from this template. Note that while either option is technically allowed for all visibility settings, "template_owner" only has an effect if visibility is "shared" or "public".
- `star_counter` (integer, required): Number of times the template has been "starred".
- `template_documents` (string): @deprecated. Use documents instead.
- `updated_at` (string, required): Last-update date/time.
- `visibility` (string): If set, the visibility level for the template.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/templates/TEMPLATE_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# List webhook deliveries (/docs/reference/Rest-API/api-docs/webhooks/getWebhookDeliveries)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/webhooks/deliveries
`GET https://api.verdocs.com/v2/webhooks/deliveries`
### Query parameters
- `event` (string): Only deliveries for this event.
- `envelope_id` (string): Only deliveries about this envelope.
- `status` (string): Only deliveries in this state. One of: `"delivered"`, `"failed"`, `"pending"`.
- `created_after` (string, date): Only deliveries created at or after this time.
- `created_before` (string, date): Only deliveries created before this time.
- `rows` (integer): Page size, up to 100. Default: `25`.
- `page` (integer): Page to retrieve (0-based). Default: `0`.
### Responses
#### 200: Success
Content type `application/json`.
- `count` (integer, int32): The total number of matching deliveries.
- `rows` (integer, int32): The page size used.
- `page` (integer, int32): The page returned.
- `deliveries` (IWebhookDelivery[]): The deliveries on this page.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/webhooks/deliveries?param=value" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get a webhook delivery (/docs/reference/Rest-API/api-docs/webhooks/getWebhookDelivery)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/webhooks/deliveries/{delivery_id}
`GET https://api.verdocs.com/v2/webhooks/deliveries/{delivery_id}`
### Path parameters
- `delivery_id` (string, uuid, required): The delivery to get.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IWebhookDeliveryDetail`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/webhooks/deliveries/DELIVERY_ID" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get webhook delivery counts (/docs/reference/Rest-API/api-docs/webhooks/getWebhookDeliveryStats)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/webhooks/deliveries/stats
`GET https://api.verdocs.com/v2/webhooks/deliveries/stats`
### Query parameters
- `days` (integer): How many days to include, up to 90. Default: `30`.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IWebhookDeliveryStats[]`
- `date` (string, required): In YYYY-MM-DD format.
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/webhooks/deliveries/stats?param=value" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Get organization webhooks config (/docs/reference/Rest-API/api-docs/webhooks/getWebhooks)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## GET /v2/webhooks
`GET https://api.verdocs.com/v2/webhooks`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IWebhook`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X GET "https://api.verdocs.com/v2/webhooks" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Resend a webhook delivery (/docs/reference/Rest-API/api-docs/webhooks/resendWebhookDelivery)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
## POST /v2/webhooks/deliveries/{delivery_id}/resend
`POST https://api.verdocs.com/v2/webhooks/deliveries/{delivery_id}/resend`
### Path parameters
- `delivery_id` (string, uuid, required): The delivery to send again.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IWebhookDelivery`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X POST "https://api.verdocs.com/v2/webhooks/deliveries/DELIVERY_ID/resend" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Rotate Webhook secret key (/docs/reference/Rest-API/api-docs/webhooks/rotateWebhookSecret)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Rotates (or first creates) the secret used to sign webhook deliveries. The response includes the new, unmasked
## PUT /v2/webhooks/rotate-secret
`PUT https://api.verdocs.com/v2/webhooks/rotate-secret`
### Responses
#### 200: Success
Content type `application/json`.
Type: `IWebhook`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PUT "https://api.verdocs.com/v2/webhooks/rotate-secret" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```
# Update organization webhooks config (/docs/reference/Rest-API/api-docs/webhooks/setWebhooks)
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Note that Webhooks cannot currently be deleted, but may be easily disabled by setting
## PATCH /v2/webhooks
`PATCH https://api.verdocs.com/v2/webhooks`
### Request body
Content type `application/json`, required. Body Parameters.
- `url` (string, required): URL to send Webhook events to. An empty or invalid URL will disable Webhook calls.
- `active` (boolean, required): Set to true to enable Webhooks calls.
- `auth_method` (string): Enable HMAC or Client Credentials authentication for Webhooks calls. One of: `"none"`, `"hmac"`, `"client_credentials"`.
- `token_endpoint` (string): Required if `auth_method` is set to `client_credentials`. Token endpoint to use for authenticating Webhooks calls.
- `client_id` (string): Required if `auth_method` is set to `client_credentials`. Client ID to use for authenticating Webhooks calls.
- `client_secret` (string): Required if `auth_method` is set to `client_credentials`. Client secret to use for authenticating Webhooks calls.
- `scope` (string): Optional scope to include in authentication calls if `auth_method` is set to `client_credentials`.
- `events` (object, required): Record map of events to enable/disable.
### Responses
#### 200: Success
Content type `application/json`.
Type: `IWebhook`
#### 400: Request Error
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 401: Access Denied
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 404: Not Found
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
#### 406: Invalid Parameter
Content type `application/json`.
- `status` (string, required): Always set to "ERROR". One of: `"ERROR"`.
- `error` (string, required): Description of the error that occurred.
### Example request
```bash
curl -X PATCH "https://api.verdocs.com/v2/webhooks" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json" \
-d '{"param": "value"}'
```