Agreement and Workflow API

Agreement and workflow API

These APIs support application-style agreement preparation and signing. They use user authentication and operation-specific permissions; they are not interchangeable with the scoped document integration CRUD API. Prefix the paths below with /api/v1/agreements.

Agreement endpoints

Method	Suffix	Purpose
GET	/	List accessible agreements
POST	/upload	Create an uploaded draft
POST	/scratch	Create a Markdown draft
GET	/{id}	Read an agreement
PATCH	/{id}/draft	Update an editable draft
POST	/{id}/activate	Activate an eligible draft
GET	/{id}/history	Read agreement audit history
POST	/{id}/sign-session	Create an authorized signing session
GET	/{id}/file	Download available document bytes
POST / GET	/{id}/versions	Create / list versions
POST	/{id}/clone	Create a separate copy
POST	/{id}/archive, /{id}/unarchive	Change archived visibility
DELETE	/{id}	Delete under service state rules
PATCH	/{id}/metadata	Update tags and metadata
GET / PUT	/{id}/fields	Read / save fields and recipients

Upload input includes title, fileName, fileSize, and mimeType, with the appropriate fileBase64 or markdownContent and optional description, tags, and metadata. Scratch input requires title and nonempty markdownContent. Limits are described in Agreement Management.

Save fields

PUT /api/v1/agreements/{id}/fields accepts arrays of recipients and document fields. This example deliberately uses a fictional email and a local recipient identifier, not a live signing link:

{
  "recipients": [
    {"id":"recipient-1","name":"Example Signer","email":"signer@example.com","role":"signer","color":"#2563EB"}
  ],
  "fields": [
    {"id":"signature-1","type":"SIGNATURE","pageNumber":1,"x":10,"y":70,"width":30,"height":10,"label":"Signature","recipientId":"recipient-1","isRequired":true}
  ]
}

Coordinates are percentages. Every field must refer to an included recipient, and field identifiers must be unique. See Document Editor and Fields.

Workflow endpoints

Method	Suffix	Body
POST	/{id}/review/submit	Optional reviewerId, reviewerEmail, notes; provide an appropriate reviewer
POST	/{id}/review/retract	Retract an eligible outstanding review
POST	/{id}/review/approve	decision: "APPROVE", optional comments
POST	/{id}/review/reject	decision: "REJECT", optional comments
POST	/{id}/send	signingOrder, recipients, optional expiresAt, message
POST	/{id}/cancel	Required reason, at most 1,000 characters
POST	/{id}/remind	Optional recipientId, note
GET	/{id}/notifications	Recorded notification history

The send body supports PARALLEL or SEQUENTIAL. Recipients have name, email, role, and routingOrder with optional id and color. Preserve the relevant configured recipient IDs so field assignments stay aligned. Expiry is an ISO 8601 date-time or null. Sending can deliver real invitations.

{
  "signingOrder": "SEQUENTIAL",
  "recipients": [
    {"id":"recipient-1","name":"Example Signer","email":"signer@example.com","role":"signer","routingOrder":1}
  ],
  "message": "Please review the example agreement."
}

Agreement endpoints commonly return an application success/data envelope, unlike the direct document DTO. Check the actual response for the route you use. Workflow state, reviewer assignment, recipient mapping, and authorization are enforced by the relevant services; arbitrary endpoint order cannot bypass the workflow.

Signer endpoints

The recipient base is /api/v1/sign/{token}. Treat {token} as a private capability; it must never appear in public logs or documentation screenshots.

Method	Suffix	Purpose
GET	empty suffix	Read the authorized signing task
POST	/consent	consentGiven: true, optional disclosure version
POST	/view	Record authorized document viewing
POST	/otp/send	Request an email verification code
POST	/otp/verify	otpCode, six digits
POST	/complete	Submit field answers and signing consent
POST	/decline	Required reason, at most 500 characters
GET	/file	Authorized document file
GET	/download	Available final download under portal rules

Completion accepts fieldsData keyed by field ID and an optional signatureData object containing type (DRAWN, TYPED, UPLOADED), data, and consentGiven: true. Additional properties support font, timestamp, guest status, and OTP as required by the flow. Required field values and recipient identity checks still apply.

For ordinary recipients, use the web portal described in Sign an Agreement rather than constructing requests manually.