> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luminpdf.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Agreement
> Create a new AgreementGen document from a AgreementGen template.
This endpoint requires the following scope:
`agreements`
## OpenAPI
````yaml POST /agreements
openapi: 3.1.0
info:
version: 1.0.0
title: Lumin API Reference
description: >
The Lumin API Reference provides a comprehensive set of tools to integrate
document workflows — including editing, eSignatures, and automation — into
your applications.
Useful links:
- [Document Repository](https://github.com/luminpdf/luminsign-docs)
- [API
Definition](https://github.com/luminpdf/luminsign-docs/blob/main/openapi.yaml)
- [Authentication Guide](/tabs/guides/authentication/overview)
termsOfService: https://www.luminpdf.com/terms-of-use/
contact:
name: API Support
email: integration@luminpdf.com
url: https://help.luminpdf.com
servers:
- url: https://api.luminpdf.com/v1
description: Production server
security: []
tags:
- name: Signature Requests
description: Everything about Signature Requests
- name: Users
description: Everything about Users
- name: Templates
description: Everything about Templates
- name: Documents
description: Everything about Documents
- name: Workspaces
description: Everything about Workspaces
- name: Agreements
description: Everything about Agreements
paths:
/agreements:
post:
tags:
- Agreements
summary: Create Agreement
description: |
Create a new AgreementGen document from a AgreementGen template.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AgreementCreateRequest'
example:
method: template
agreement_name: NDA Agreement
agreement_data:
template_id: ag_12312321
fields:
Client.Name: Acme Corp
Document.EffectiveDate: '2025-08-01'
variables:
Client.Name: Acme Corp
Document.EffectiveDate: '2025-08-01'
collections:
Opportunity.LineItems:
- Product.Name: Annual enterprise license
Product.Quantity: '1'
Product.UnitPrice: $1,000.00
Product.Total: $1,000.00
- Product.Name: Premium support package
Product.Quantity: '1'
Product.UnitPrice: $500.00
Product.Total: $500.00
linked_objects:
- integration: salesforce
entity_type: opportunity
record_id: 0065g00000Vh123ABC
reference_url: https://your-crm-instance.example.com/record/001XXXXXXXXX
signer_roles:
- name: Tenant
preassigned_signer:
name: Alice Nguyen
email_address: alice.nguyen@example.com
- name: Landlord
preassigned_signer:
name: Brian Tran
email_address: brian.tran@example.com
responses:
'201':
description: Returns the Agreement summary object data
content:
application/json:
schema:
$ref: '#/components/schemas/AgreementSummary'
4XX:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKey: []
- BearerAuth:
- agreements
components:
schemas:
AgreementCreateRequest:
type: object
required:
- method
- agreement_data
properties:
method:
type: string
enum:
- template
description: Must be set to `template`.
agreement_name:
type: string
minLength: 1
maxLength: 255
description: >
Human-friendly title of the agreement (1-255 chars). Defaults to
input name or "New document" if not provided in the request body.
agreement_data:
$ref: '#/components/schemas/AgreementTemplateData'
AgreementSummary:
type: object
required:
- id
- name
- created_at
properties:
id:
type: string
description: The unique identifier for the agreement.
name:
type: string
description: The name of the agreement.
preview_url:
type: string
format: uri
description: The URL to preview the agreement in the browser.
created_at:
type: integer
format: unix-epoch
description: The time the agreement was created (Unix timestamp in milliseconds).
linked_objects:
type: array
description: CRM or external objects linked to the agreement.
items:
$ref: '#/components/schemas/LinkedObject'
Error:
type: object
required:
- error_code
- error_message
properties:
error_code:
type: string
description: The system error code.
error_message:
type: string
description: The human-readable error message.
AgreementTemplateData:
type: object
required:
- template_id
properties:
template_id:
type: string
description: >-
Unique identifier of the AG template. Obtainable from the template
list API.
variables:
type: object
description: >
Key-value map of Variables in the template. Pass values for the
variables to render them into the created document or leave values
blank to make them available for insertion later.
fields:
type: object
description: >
Key-value pairs for Form Fields defined in the template. Keys must
match field names. Values prefill the corresponding form fields in
the generated document. Currently supports: `text` and `checkbox`
fields.
collections:
type: object
description: >
Map of **collection name → array of record objects** used to expand
table-scoped row-loop markers in the template.
- Each key must match a collection name returned by [Get Template
Details](/tabs/api-reference/api/templates/get-template-details)
under `collections[].name`.
- Each value is an ordered array of flat record objects; each record
is a key–value map where keys match the collection's variable names
and values are strings.
- Records are rendered in array order.
- Maximum 100 items per collection, and up to 50 collections per
request.
Applies to AgreementGen templates only. Ignored silently when the
resolved template `type` is not `lumin`.
additionalProperties:
type: array
items:
type: object
additionalProperties:
type: string
linked_objects:
type: array
description: CRM or external objects linked to the Agreement.
items:
$ref: '#/components/schemas/LinkedObject'
signer_roles:
type: array
description: >
Describes the signer roles defined in the template. Role name must
match the values defined in the template. These values are prefilled
when sending the agreement for signature from the AgreementGen
editor.
items:
type: object
properties:
name:
type: string
description: >-
A label for the role (e.g., "Tenant", "Manager"). Must match a
role defined in the template.
preassigned_signer:
type: object
description: >-
Signer preassigned to this role. These values are prefilled
when sending the agreement for signature.
properties:
name:
type: string
description: Name of the preassigned signer.
email_address:
type: string
format: email
description: Email address of the preassigned signer.
LinkedObject:
type: object
properties:
integration:
type: string
description: >
The external system or integration where the linked object lives.
Example: salesforce, hubspot.
entity_type:
type: string
description: >
The type of the linked object in that provider's data model.
Example: opportunity, contact, deal.
record_id:
type: string
description: >
The unique identifier of the linked object in the provider system.
Example: 0065g00000Vh123ABC (Salesforce record ID).
reference_url:
type: string
format: uri
description: The reference URL of the linked object in the provider system.
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-API-Key
description: >
Provide your API key in the `X-API-Key` header, e.g., `X-API-Key:
YOUR_API_KEY`.
BearerAuth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.luminpdf.com/oauth2/auth
tokenUrl: https://auth.luminpdf.com/oauth2/token
scopes:
openid: >-
Retrieve basic identity details (username, email, profile
picture).
offline_access: Request a refresh token for long-lived access. Private apps only.
profile.read: View basic user profile information.
workspaces: View and manage Workspaces and Spaces.
workspaces.read: View information about the authenticated user's Workspace.
templates: View and manage templates in a Workspace.
pdf:files: Create, edit, and delete PDF files in a Workspace.
pdf:files.read: Retrieve PDF documents stored in a Workspace.
sign:requests: Create, update, or view signature requests.
sign:requests.read: Retrieve signature requests.
agreements: Create, update, or delete AgreementGen documents.
description: >
OAuth 2.0 authorization code flow. Provide your access token in the
`Authorization` header, e.g., `Authorization: Bearer `. See the
[OAuth 2.0 guide](/tabs/guides/authentication/oauth2) for details.
````