Copy page

Documentation

Custom Templates

Custom templates let you define your own agreement Cover Page as a YAML document. The YAML describes the sections and fields of your agreement, and Common Paper renders it as a fillable form, a web agreement, a PDF, and a Word export. Custom templates must be enabled for your organization; the endpoints below return 404 otherwise.

Working with custom templates via the API

Endpoint	What it does
GET /v1/custom_templates	List your organization's custom templates.
POST /v1/custom_templates	Create a template from a YAML definition.
GET /v1/custom_templates/{id}	Get one template, including its current YAML as current_definition.
POST /v1/custom_templates/{id}/versions	Publish a new version from a YAML definition.
PATCH /v1/custom_templates/{id}	Rename a template.
DELETE /v1/custom_templates/{id}	Archive a template.

Creating a template and publishing a version both take a definition (the YAML) and a user_email or user_id identifying the user in your organization to record as the creator.

Code
curl -X POST "https://api.commonpaper.com/v1/custom_templates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Consulting Agreement",
    "user_email": "you@example.com",
    "definition": "title: Consulting Agreement\nsections:\n  - heading: Payment\n    fields:\n      payment_terms:\n        label: Payment terms\n        input: text\n        default: Net 30\n"
  }'

Every publish creates a new version and makes it current immediately. Agreements pin the version they were created from, so publishing never changes an agreement that is already in flight.

Creating agreements from a custom template

Pass the custom template's UUID as template_id to POST /v1/agreements, and put field values in agreement.custom_field_values, keyed by the field keys in the YAML definition. Template defaults fill any fields you omit. A required field with no default and no submitted value returns a 400 naming the field.

Code
curl -X POST "https://api.commonpaper.com/v1/agreements" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "CUSTOM_TEMPLATE_UUID",
    "owner_email": "you@example.com",
    "signer_email": "you@example.com",
    "agreement": {
      "recipient_name": "Art Vandelay",
      "recipient_email": "art@example.com",
      "custom_field_values": {
        "payment_terms": "Net 45",
        "start_date": "2026-01-01"
      }
    }
  }'

Fields with a mapping value, like address and rate inputs, take an object using the same component keys as their YAML defaults. Set draft to true to save without sending, the same as any other agreement.

Custom terms

Custom terms are the standard terms that follow the Cover Page. A template's terms are attached to it in the Common Paper app and carry over to agreements created through the API, but the terms themselves can be managed via the API:

Endpoint	What it does
GET /v1/custom_terms	List your organization's custom terms. Ids and metadata only; the terms text is omitted because it can be very large.
GET /v1/custom_terms/{id}	Get one term, including the full terms text of its released version as body.
POST /v1/custom_terms	Create text terms. The markdown body is published as released version 1.
POST /v1/custom_terms/{id}/versions	Publish a new version. The new body immediately becomes the released version; existing versions are immutable.
PATCH /v1/custom_terms/{id}	Rename terms. Only the name changes here; content changes go through publishing a version.

Creating terms and publishing versions take a user_email or user_id identifying the user in your organization to record as the creator. Only text terms can be created or versioned through the API; file type terms (uploaded Word documents) are managed in the Common Paper app.

Code
curl -s -X POST "https://api.commonpaper.com/v1/custom_terms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Standard Terms",
    "user_email": "you@example.com",
    "body": "## 1. Services\n\nProvider will make the services available to Customer..."
  }' | jq

The basic shape

A template has a title and a list of sections. Each section groups related fields.

Code
title: Consulting Agreement
sections:
  - heading: Services
    fields:
      services_description:
        label: Description of services
        input: textarea
  - heading: Payment
    fields:
      payment_terms:
        label: Payment terms
        input: text
        default: Net 30

Field keys (like services_description) are internal identifiers. They must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Each key must be unique across the whole template. These keys are also the keys you use in custom_field_values when creating agreements.

Top-level settings

All of these are optional except title.

Key	What it does
title	The display name of the agreement, shown as the heading on the agreement, PDF, and Word export. Required.
terms_label	Renames the "Cover Page" heading. Use this when your agreement calls its terms something else, like Key Terms, Order Form, or Statement of Work. In the Word export it also appears uppercased in the page header.
terms_sublabel	Smaller text under the terms label in the Word export, such as "The key legal terms of this Agreement are as follows:".
info_box	Explanatory text shown in a highlighted box above the Cover Page, like the framework explanation on Common Paper standard agreements.
terms_heading	A heading row rendered at the top of the terms table, such as "Key Terms".
terms_subheading	Smaller text under the terms heading.
signing_disclaimer	The sentence above the signature blocks. Defaults to "By signing this Cover Page, each party agrees to enter into the Agreement."
footer	Text shown at the bottom of every page in PDF and Word exports. Write {terms_version} anywhere in the text to insert the current custom terms version number, for example Acme Terms Version {terms_version}. Defaults to the custom terms name and version number.
parties	Renames the two parties. Takes sender: and recipient: keys, for example Vendor and Client. Defaults are Provider and Customer.

Example:

Code
title: Independent Contractor Agreement
terms_label: Framework Terms
info_box: The Framework Terms have 2 parts...
signing_disclaimer: By signing below, both parties accept these Framework Terms.
parties:
  sender: Company
  recipient: Contractor
sections:
  ...

Sections

Each entry in sections: is one row of the Cover Page, with the heading on the left and its fields on the right.

Key	What it does
heading	The section name shown on the left.
subheading	Smaller text under the heading.
required: true	The section always appears on the agreement and cannot be excluded by the sender.
included: false	The section is excluded by default. Senders can include it per agreement with a checkbox when creating the agreement.
header	Makes the section a full-width header row instead of a fields row. Use it to divide the Cover Page, for example "Additions and Modifications". A header section has no fields.
import	Pulls in a ready-made section. See Imports below.
access	Who can edit the section's fields. See Access levels below.

Code
sections:
  - heading: Optional rider
    subheading: Only applies to enterprise deals
    included: false
    fields:
      rider_details:
        label: Rider details
        input: textarea
  - header: Additions and Modifications

Fields

Fields live in a fields: mapping inside a section. The mapping key is the field key; everything else is configuration.

Key	What it does
label	The name shown above the input and next to the value on the agreement.
input	The input type. See the table below. Required.
instructions	Guidance shown only on the form while filling it in. It does not appear on the finished agreement.
placeholder	Placeholder text inside the empty input.
required: true	The field always appears on the agreement, and a value must be entered before the agreement can be sent.
default	Prefills the field. Senders can change it when creating an agreement.
options	The choices for radio, select, multiselect, and rate inputs.
currency	The currency code for currency and rate inputs. Defaults to USD.
access	Who can edit the field. Overrides the section's access. See Access levels below.

Fields without a value are left off the finished agreement, unless they are required or fixed.

Access levels

By default only organization admins can edit field values when creating an agreement. Add access to a field or a whole section to open it up:

Value	Who can edit
admin	Organization admins only. This is the default.
standard	Standard members and admins.
recipient	The agreement recipient, plus standard members and admins.

A field-level access overrides its section's. Locked fields show read-only on the form and keep their template defaults.

Recipients are a special case. While negotiation is enabled they can propose changes to any field as before. access: recipient fields also appear as inputs directly on the recipient's view of the agreement so they can fill them in alongside the signature block. Marking one of these fields required: true means the recipient must fill it in before signing; it does not block the sender from sending.

Code
sections:
  - heading: Fees
    access: standard
    fields:
      fee:
        label: Monthly fee
        input: currency
      po_number:
        label: PO number
        input: text
        access: recipient

Input types

Input	Renders as
text	Single-line text box
textarea	Multi-line text box
markdown	Multi-line text box with formatting (bold, lists, links) preserved on the agreement
number	Number input
currency	Money input with a currency symbol. Set currency: EUR to change from USD.
rate	A money amount plus a per-unit select, shown on one line like "$500.00 per hour". options lists the units (hour, day, week). Defaults and submitted values use a mapping with amount: and per: keys.
date	Date picker
email	Email input
radio	One choice from options, all visible
select	One choice from options, in a dropdown
multiselect	Multiple choices from options, shown as checkboxes
states	Dropdown of US states
address	A full address block (country, street, city, state, ZIP). Defaults and submitted values use a mapping with those component keys.
attachment	Pick a PDF from your organization's attachment library. The file is referenced on the agreement and appended to the PDF.
fixed	Uneditable text set by default. Always appears on the agreement. Use it for standard language that senders should not change. The text renders as markdown. For multi-line markdown like bullet lists or tables, write the default as a block scalar (`default:

Rate example:

Code
fee:
  label: Rate
  input: rate
  options:
    - hour
    - day
  default:
    amount: 500
    per: hour

Address example:

Code
contractor_address:
  label: Contractor address
  input: address
  default:
    country: USA
    city: New York
    state: New York

Imports

Imports drop in a ready-made section with one line. Today there is one import available:

Code
sections:
  - import: governing_law

This renders a Governing Law & Chosen Courts section backed by the same pickers Common Paper standard agreements use. To preset answers, add a defaults: mapping, and to limit the pickers to specific jurisdictions, add options::

Code
sections:
  - import: governing_law
    options:
      - New York
      - Delaware
      - California
    defaults:
      governing_law_region: Delaware
      chosen_courts_region: Delaware

The state pickers list US states, and options restricts them to a subset. Organizations allowed to use additional courts get the same country selector as standard agreements: pick a country and the region control adapts (US states, Canadian provinces, or a free-text region elsewhere).

Versions

Every publish creates a new version and makes it current immediately. Agreements pin the version they were created from, so they always render exactly what the signer saw. The version history is also available in the template editor in the Common Paper app, where the YAML can be edited alongside a live form preview.