Agrello for Developers

Build document signing workflows with Agrello API

Create documents, fill templates with data, invite signers, receive webhook events, and download signed outputs from your product or back-office system.

Book API demoOpen API docs
Auth & URLs

Everything needed before the first request

API base URLhttps://api.agrello.io/public
Token URLhttps://service.agrello.org/auth/oauth/token
Authentication

OAuth 2.0 Client Credentials. Send Authorization: Bearer $TOKEN.

Token lifetime

Access tokens expire after 24 hours. Handle 401 by requesting a new token.

API version

Use /v3 endpoints. Swagger also lists API v2 as deprecated.

OpenAPI JSONhttps://api.agrello.io/public/api-docs/v3
Happy path

A complete minimal flow, not just an endpoint list

A copyable path for a backend developer. Swagger remains the canonical reference; this explains the order of operations.

Minimal file-upload signing flowOAuth token → workspace → folder → container → output
# Get workspace
GET /v3/workspace

# Create or choose a folder
POST /v3/folders
{ "name": "API test documents" }

# Upload a PDF and publish it for signing
POST /v3/folders/{folderId}/containers
Content-Type: multipart/form-data

request={
  "name": "API test contract",
  "outputType": "PDF",
  "signers": ["signer@example.com"],
  "viewers": ["legal@example.com"],
  "variables": [],
  "immediatePublish": true,
  "metadata": { "external_id": "CRM-12345" }
}
file=@contract.pdf

# Monitor and download after signing
GET /v3/containers/{containerId}
GET /v3/containers/{containerId}/output
Core model

Learn the nouns first

Workspace

└── Folder

  ├── Template + variables

  └── Container

    ├── participants / invitations

    ├── signatures

    └── signed output

Folder

Organizes documents by team, customer, workflow, or project. Some API responses may still include legacy spaceId.

Template

Reusable source document with variables. Templates are not edited in place; create a new template for a new version.

Container

The document package sent for signing, including files, invitations, participants, signatures, metadata, and output.

Create documents

Choose the flow based on where the document is generated

Flow A: upload your own file

Your system generates the final file and Agrello handles signing.

GET/v3/workspace
POST/v3/folders
POST/v3/folders/{folderId}/containers
GET/v3/containers/{containerId}/output

Flow B: generate from template

Agrello template variables are filled from your product or back-office data.

POST/v3/folders/{folderId}/templates
GET/v3/templates/{templateId}
POST/v3/folders/{folderId}/containers
POST/v3/webhooks
Template variable exampleexact matching
{
  "templateId": "template-uuid",
  "variables": [
    { "name": "employee_name", "value": "Jane Smith" },
    { "name": "start_date", "value": "2026-06-01" },
    { "name": "employee_signature", "value": "jane@example.com" }
  ],
  "signers": []
}

Output type guide

  • PDF — simple signed PDF output.
  • ASICE — EU XAdES container format.
  • EDOC — Latvian electronic signature container.
  • ADOC_B — Lithuanian electronic signature container.
  • ZIP — packaged output when applicable.
Test multipart uploads with cURL, Postman, or code rather than Swagger UI.
Variable names must match exactly, including casing and whitespace.
Do not add a signer twice through a PDF signature variable and the signers array.
Containers do not support partial updates; collect all data before creation.
Webhooks & status

Know when the document is signed

Use webhooks for event-driven integrations and poll container details only when you need a fallback or reconciliation check.

Register webhookDOCUMENT_SIGNED
{
  "event": "DOCUMENT_SIGNED",
  "url": "https://your-app.com/webhooks/agrello/document-signed"
}
Example payloadsample
{
  "containerId": "container-uuid",
  "userId": "last-signer-uuid",
  "signerCount": 2
}
Completion check: compare collected signatures with expected signers when polling container details.
Documented webhook events: DOCUMENT_SIGNATURE_ADDED, DOCUMENT_SIGNED, REMINDER_CREATED.
Webhook retry behavior and request-signing guarantees should not be promised until documented.
No public sandbox URL is listed. Use a test workspace unless Agrello provisions a separate test setup.
Technical handoff

Bring your workflow. We’ll map it to the API.

Review credentials, templates, output format, signer roles, webhook handling, and the fastest route to a signed test document.

Book API demoOpen API docs