Custom Templates

Create and manage custom templates defined in YAML, including publishing new template versions

List Custom Templates

GET

https://api.commonpaper.com

/v1/custom_templates

This endpoint returns a list of the custom templates in your organization, ordered by name. Each template's current_definition is the YAML of its current version, which new agreements are created from. See Custom Templates for the YAML reference.

Custom templates must be enabled for your organization; these endpoints return 404 otherwise.

List Custom Templates › query Parameters

page[number]

integer

Page number to retrieve. Defaults to 1.

Default: 1

page[size]

integer

Number of records per page. Defaults to 15.

Default: 15

List Custom Templates › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

List Custom Templates › Responses

GET/v1/custom_templates

curl https://api.commonpaper.com/v1/custom_templates \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "CUSTOM_TEMPLATE_UUID",
      "type": "custom_template",
      "attributes": {
        "name": "Consulting Agreement",
        "organization_id": "ORGANIZATION_UUID",
        "created_at": "2026-01-15T10:00:00.000Z",
        "updated_at": "2026-06-01T08:45:00.000Z",
        "current_definition": "title: Consulting Agreement\nsections:\n  - heading: Services\n    fields:\n      service_description:\n        label: Description of services\n        input: textarea\n",
        "custom_term_id": null,
        "current_version_number": 1
      }
    }
  ]
}

json

application/json

Create Custom Template

POST

https://api.commonpaper.com

/v1/custom_templates

This endpoint creates a new custom template from a YAML definition. The definition is saved as the template's first version and becomes the one new agreements use. Provide user_email or user_id to record which user in your organization created it. Pass custom_term_id to attach custom terms from your organization, so agreements created from the template include them.

See Custom Templates for the full YAML reference.

Custom templates must be enabled for your organization; these endpoints return 404 otherwise.

Create Custom Template › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Create Custom Template › Request Body

Provide user_email or user_id to record the creator; one of the two is required.

custom-template-create-schema

name

string · required

A name for the custom template.

definition

string · required

The YAML definition of the template's title, sections, and fields. Saved as the template's first version. See Custom Templates for the full YAML reference.

user_email

string · email

Email of the user in your organization recorded as the version's creator. Provide user_email or user_id.

user_id

string · uuid

ID of the user in your organization recorded as the version's creator. Provide user_email or user_id.

custom_term_id

string · uuid

ID of custom terms in your organization to attach to the template. Agreements created from the template include those terms.

Create Custom Template › Responses

Created

POST/v1/custom_templates

curl https://api.commonpaper.com/v1/custom_templates \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Consulting Agreement",
  "definition": "title: Consulting Agreement\nsections:\n  - heading: Services\n    fields:\n      service_description:\n        label: Description of services\n        input: textarea\n  - heading: Payment\n    fields:\n      payment_terms:\n        label: Payment terms\n        input: text\n        default: Net 30\n",
  "user_email": "ben@example.com",
  "user_id": "00000000-0000-0000-0000-000000000000",
  "custom_term_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "name": "Consulting Agreement",
  "definition": "title: Consulting Agreement\nsections:\n  - heading: Services\n    fields:\n      service_description:\n        label: Description of services\n        input: textarea\n  - heading: Payment\n    fields:\n      payment_terms:\n        label: Payment terms\n        input: text\n        default: Net 30\n",
  "user_email": "ben@example.com",
  "user_id": "00000000-0000-0000-0000-000000000000",
  "custom_term_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "data": {
    "id": "CUSTOM_TEMPLATE_UUID",
    "type": "custom_template",
    "attributes": {
      "name": "Consulting Agreement",
      "organization_id": "ORGANIZATION_UUID",
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z",
      "current_definition": "title: Consulting Agreement\nsections:\n  - heading: Services\n    fields:\n      service_description:\n        label: Description of services\n        input: textarea\n",
      "custom_term_id": null,
      "current_version_number": 1
    }
  }
}

json

application/json

Get Custom Template

GET

https://api.commonpaper.com

/v1/custom_templates/{id}

This endpoint returns the details of a specific custom template by its UUID, including the YAML of its current version as current_definition.

Custom templates must be enabled for your organization; these endpoints return 404 otherwise.

Get Custom Template › path Parameters

id

string · uuid · required

The UUID of the custom template.

Get Custom Template › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Custom Template › Responses

Update Custom Template

PATCH

https://api.commonpaper.com

/v1/custom_templates/{id}

This endpoint renames a custom template and changes its linked custom terms. The template's YAML changes by publishing a new version with POST /v1/custom_templates/{id}/versions.

Custom templates must be enabled for your organization; these endpoints return 404 otherwise.

Pass custom_term_id to attach custom terms from your organization, or an empty string to unlink them. An id for terms outside your organization returns 422. Changing the terms publishes a new template version recording the terms the template now references; pass user_id to record who made the change. Renaming alone does not create a version.

Update Custom Template › path Parameters

id

string · uuid · required

The UUID of the custom template to update.

Update Custom Template › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Update Custom Template › Request Body

Provide name to rename the template, custom_term_id to change its linked terms, or both.

custom-template-update-schema

name

string

The new name for the custom template.

custom_term_id

string

ID of custom terms in your organization to attach to the template, so agreements created from the template include those terms. Pass an empty string to unlink the terms, which is why this field is not constrained to the uuid format. Changing the terms publishes a new template version recording the change.

user_id

string · uuid

ID of the user in your organization to record as the publisher when a terms change publishes a new version. Optional; an id that does not identify a user in your organization returns 422.

Update Custom Template › Responses

PATCH/v1/custom_templates/{id}

curl https://api.commonpaper.com/v1/custom_templates/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Consulting Agreement (2026)",
  "custom_term_id": "custom_term_id",
  "user_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "name": "Consulting Agreement (2026)",
  "custom_term_id": "custom_term_id",
  "user_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "data": {
    "id": "CUSTOM_TEMPLATE_UUID",
    "type": "custom_template",
    "attributes": {
      "name": "Consulting Agreement (2026)",
      "organization_id": "ORGANIZATION_UUID",
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-06-01T08:45:00.000Z",
      "current_definition": "title: Consulting Agreement\nsections:\n  - heading: Services\n    fields:\n      service_description:\n        label: Description of services\n        input: textarea\n",
      "custom_term_id": null,
      "current_version_number": 1
    }
  }
}

json

application/json

Archive Custom Template

DELETE

https://api.commonpaper.com

/v1/custom_templates/{id}

This endpoint archives a custom template so it no longer appears in your templates list and can no longer be used to create agreements. Agreements already created from the template are unaffected.

Custom templates must be enabled for your organization; these endpoints return 404 otherwise.

Archive Custom Template › path Parameters

id

string · uuid · required

The UUID of the custom template to archive.

Archive Custom Template › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Archive Custom Template › Responses

No Content. The custom template was archived successfully.

No data returned

Create Custom Template Version

POST

https://api.commonpaper.com

/v1/custom_templates/{id}/versions

This endpoint publishes a new version of a custom template from a YAML definition. The new version immediately becomes the one new agreements use. Agreements already created from the template keep the version they were made with, so publishing never changes an agreement that is in flight. Provide user_email or user_id to record which user in your organization published it.

Each version records the custom terms the template referenced when it was published, as custom_term_id. Publishing a definition identical to the current version with the same linked terms is a no-op: no version is created and the current one is returned with a 200 instead of a 201.

See Custom Templates for the full YAML reference.

Custom templates must be enabled for your organization; these endpoints return 404 otherwise.

Create Custom Template Version › path Parameters

id

string · uuid · required

The UUID of the custom template to publish a new version for.

Create Custom Template Version › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Create Custom Template Version › Request Body

Provide user_email or user_id to record the creator; one of the two is required.

custom-template-version-create-schema

definition

string · required

The YAML definition for the new version. See Custom Templates for the full YAML reference.

user_email

string · email

Email of the user in your organization recorded as the version's creator. Provide user_email or user_id.

user_id

string · uuid

ID of the user in your organization recorded as the version's creator. Provide user_email or user_id.

Create Custom Template Version › Responses

OK. Returned instead of 201 when the definition and linked terms match the current version; the body is the current version and nothing new is created.

POST/v1/custom_templates/{id}/versions

curl https://api.commonpaper.com/v1/custom_templates/:id/versions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "definition": "title: Consulting Agreement\nsections:\n  - heading: Services\n    fields:\n      service_description:\n        label: Description of services\n        input: textarea\n",
  "user_email": "ben@example.com",
  "user_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "definition": "title: Consulting Agreement\nsections:\n  - heading: Services\n    fields:\n      service_description:\n        label: Description of services\n        input: textarea\n",
  "user_email": "ben@example.com",
  "user_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "data": {
    "id": "CUSTOM_FORM_VERSION_UUID",
    "type": "custom_form_version",
    "attributes": {
      "custom_template_id": "CUSTOM_TEMPLATE_UUID",
      "custom_term_id": "CUSTOM_TERM_UUID",
      "version_number": 2,
      "definition": "title: Consulting Agreement\nsections:\n  - heading: Services\n    fields:\n      service_description:\n        label: Description of services\n        input: textarea\n",
      "released_at": "2026-06-01T08:45:00.000Z",
      "created_at": "2026-06-01T08:45:00.000Z"
    }
  }
}

json

application/json

Templates Custom Terms