API

REST API

The REST API lets your systems create and update contracts, entities, contacts and documents, with scopes per resource. Your own identifiers can be stored on each record to keep systems in sync.

How it works

The REST API under /api/v1 covers agreements, entities, contacts, documents, custom object records, users and groups. API clients are created in the Interoperability settings and authenticate with OAuth or an API key. For example, a purchase order raised in your ERP or a new hire in your HR system can call the API to create the matching contract with its fields already filled in.

Each client is given scopes per resource, such as agreements:read, entities:write or documents:write, or wildcards. Writes accept an idempotency key, so a retried call is not applied twice.

Records can be addressed by their Formality id or by your own identifier, written external:{system}:{id}, so your ERP or procurement tool does not need to store Formality ids. Combined with outgoing webhooks, this gives two-way sync.

What you get

  • Contracts, entities, contacts and documents
  • Read and write scopes per resource
  • Your external IDs on each record
  • Used with webhooks for two-way sync

Why teams use it

No double entry

Create contracts and suppliers from the tools where they start.

Least privilege

Give each integration only the scopes it needs.

Your identifiers kept

Address records with your ERP or portal IDs.

Safe retries

Idempotency keys stop a retried call from creating duplicates.

Traceable

Every call appears in the API call log.

More in Integrations & API

See all →

MCP server and API for AI agents

Connect Claude, ChatGPT or Copilot to your contracts, within your rules.

Learn more →

Outgoing webhooks

Formality notifies your systems when something changes.

Learn more →

Microsoft Teams

Notifications and reminders in Teams.

Learn more →

Slack

Notifications and reminders in Slack.

Learn more →