Agreements API

High-level description

The agreement API creates a signing flow for one or more people. Kivra returns an agreement ID; your integration then checks its status and retrieves the signed covenant within the available period.

Sub-types

Agreements use the agreement API rather than a type value on the content endpoint. There are no content sub-types to select for this flow.

Common payload

The agreement payload includes the parties, signing period, and original PDF. The agreement PDF must not exceed 1 MB.

Option	Purpose
subject	Names the agreement
parties	Lists signers and delegates with SSN, name, email, and role
vat_number	Identifies the issuing company associated with the tenant’s agreement
expiration_days	Sets a signing period from 7 to 180 days
original	Supplies the Base64-encoded agreement PDF

{
  "subject": "Service agreement",
  "type": "agreement",
  "vat_number": "SE556840226601",
  "expiration_days": 30,
  "parties": [
    {
      "ssn": "YYYYMMDDNNNN",
      "name": "Example Signer",
      "email": "signer@example.com",
      "role": "signer"
    }
  ],
  "original": {
    "name": "service-agreement.pdf",
    "content_type": "application/pdf",
    "data": "BASE64_ENCODED_PDF"
  }
}

Other information

1. Create an agreement

Send the common payload with POST /v1/tenant/{tenantKey}/agreement to create an agreement and request signatures. The client is the authenticated caller, while the tenant identified by tenantKey is the sender and owner of the agreement.

2. Notify signing parties

Signers and delegates receive the request through signatures.kivra.com, not the ordinary Kivra inbox. The client or tenant must notify signing parties that the agreement is ready. When every party has signed, Kivra makes the covenant available for download.

3. Track and complete the agreement

Save the agreement ID returned by the create request. List agreements or get one agreement to inspect its current state. When it is completed, retrieve the covenant from /v1/tenant/{tenantKey}/agreement/{agreementKey}/covenant. Revoke an active agreement through the documented revoke operation when it must no longer be accessed or signed; a revoked agreement cannot be activated again.

For example, a completed agreement returned by the get-agreement operation looks like this:

{
  "subject": "Service agreement",
  "created_at": "2026-01-15T10:30:00Z",
  "expires_at": "2026-02-14T10:30:00Z",
  "state": "completed",
  "tenant_name": "Example Company AB",
  "tenant": "154442474745511bbaaa5b44b391eae0513e2c55a0",
  "type": "agreement",
  "signatures": [
    {
      "ssn": "YYYYMMDDNNNN",
      "real_name": "Example Signer",
      "created_at": "2026-01-16T09:15:00Z",
      "order_ref": "d4ace777-6b91-4172-903e-39371ede89f1"
    }
  ]
}

The covenant includes a watermarked document, signature metadata, and a PAdES digital signature. See Post an agreement for the complete flow.