Custom Terms

Create and manage the custom standard terms attached to custom templates, including publishing new term versions

List Custom Terms

GET

https://api.commonpaper.com

/v1/custom_terms

This endpoint returns a list of the custom terms in your organization, ordered by name. The list includes ids and metadata only — the terms text is omitted because it can be very large. Use GET /v1/custom_terms/{id} to retrieve the full body of a specific term.

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

List Custom Terms › 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 Terms › 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 Terms › Responses

Create Custom Terms

POST

https://api.commonpaper.com

/v1/custom_terms

This endpoint creates new custom terms. Text terms take a JSON body whose markdown body is published as released version 1. File terms take a multipart/form-data request with term_type=file and a docx file part; the document is published as version 1 and converted to a pdf asynchronously, so poll the term's conversion_status until it is ready. Either shape is attributed to the user given by user_email or user_id.

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

Create Custom Terms › 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 Terms › Request Body

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

custom-term-create-schema

name

string · required

A name for the custom terms.

body

string · required

The terms text, in markdown. Published as released version 1.

term_type

string · enum

Use "text" with a JSON body. File terms are created with a multipart/form-data request instead; see the multipart request body.

Enum values:

text

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 Terms › Responses

Created

POST/v1/custom_terms

curl https://api.commonpaper.com/v1/custom_terms \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Acme Standard Terms",
  "body": "## 1. Services\n\nProvider will make the services available to Customer...",
  "term_type": "text",
  "user_email": "ben@example.com",
  "user_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "name": "Acme Standard Terms",
  "body": "## 1. Services\n\nProvider will make the services available to Customer...",
  "term_type": "text",
  "user_email": "ben@example.com",
  "user_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "data": {
    "id": "CUSTOM_TERM_UUID",
    "type": "custom_term",
    "attributes": {
      "name": "Acme Standard Terms",
      "term_type": "text",
      "organization_id": "ORGANIZATION_UUID",
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z",
      "current_version_number": 1,
      "body": "## 1. Services\n\nProvider will make the services available to Customer..."
    }
  }
}

json

application/json

Get Custom Terms

GET

https://api.commonpaper.com

/v1/custom_terms/{id}

This endpoint returns the details of specific custom terms by UUID, including the full terms text of the released version as body. File type terms return null for body and include conversion_status (processing, ready, or failed) for the released version's pdf conversion.

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

Get Custom Terms › path Parameters

id

string · uuid · required

The UUID of the custom terms.

Get Custom Terms › 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 Terms › Responses

Update Custom Terms

PATCH

https://api.commonpaper.com

/v1/custom_terms/{id}

This endpoint renames custom terms. Only the name can be changed here — versions are immutable, so the terms text changes by publishing a new version with POST /v1/custom_terms/{id}/versions. Body and term_type in the request are ignored.

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

Update Custom Terms › path Parameters

id

string · uuid · required

The UUID of the custom terms to update.

Update Custom Terms › 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 Terms › Request Body

custom-term-update-schema

name

string · required

The new name for the custom terms. Only the name can change here; the terms text changes by publishing a new version.

Update Custom Terms › Responses

PATCH/v1/custom_terms/{id}

curl https://api.commonpaper.com/v1/custom_terms/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "Acme Standard Terms (2026)"
}'

Example Request Body

{
  "name": "Acme Standard Terms (2026)"
}

json

Example Responses

{
  "data": {
    "id": "CUSTOM_TERM_UUID",
    "type": "custom_term",
    "attributes": {
      "name": "Acme Standard Terms (2026)",
      "term_type": "text",
      "organization_id": "ORGANIZATION_UUID",
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-06-01T08:45:00.000Z",
      "current_version_number": 3,
      "body": "## 1. Services\n\nProvider will make the services available to Customer..."
    }
  }
}

json

application/json

Create Custom Term Version

POST

https://api.commonpaper.com

/v1/custom_terms/{id}/versions

This endpoint publishes a new version of custom terms. For text terms the markdown body becomes the released version; for file terms send multipart/form-data with a docx file part, which becomes the released version and converts to a pdf asynchronously. Existing versions are immutable and stay unchanged. Provide user_email or user_id to record which user in your organization published it.

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

Create Custom Term Version › path Parameters

id

string · uuid · required

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

Create Custom Term 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 Term Version › Request Body

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

custom-term-version-create-schema

body

string · required

The terms text for the new version, in markdown.

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 Term Version › Responses

Created

POST/v1/custom_terms/{id}/versions

curl https://api.commonpaper.com/v1/custom_terms/:id/versions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "body": "## 1. Services\n\nProvider will make the services available to Customer...",
  "user_email": "ben@example.com",
  "user_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "body": "## 1. Services\n\nProvider will make the services available to Customer...",
  "user_email": "ben@example.com",
  "user_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "data": {
    "id": "CUSTOM_TERM_VERSION_UUID",
    "type": "custom_term_version",
    "attributes": {
      "custom_term_id": "CUSTOM_TERM_UUID",
      "body": "## 1. Services\n\nProvider will make the services available to Customer...",
      "version_number": 4,
      "released_at": "2026-06-01T08:45:00.000Z",
      "created_at": "2026-06-01T08:45:00.000Z"
    }
  }
}

json

application/json

Custom Templates Users