Build on a platform that takes security as seriously as you do.
The merlon REST API lets you create documents, provision secure vaults, orchestrate approval workflows, and stream tamper-evident audit events straight into your own systems — with the same encryption, residency controls, and least-privilege access model that back the product.
# Create your first document curl https://api.merlon.ch/v1/documents \ -H "Authorization: Bearer sk_live_••••" \ -H "Content-Type: application/json" \ -d '{ "title": "MSA — Acme", "vault_id": "vault_9f2" }' # → 201 Created { "id": "doc_3kf9c1", "status": "draft" }
One API, two regions, zero surprises
Everything you can do in the merlon web app is available over a predictable, resource-oriented REST API. Responses are JSON, authentication is a single bearer token, and every mutating call can be made idempotent. Pick the regional base URL that matches your data-residency obligations and you are ready to build.
- Base URL
https://api.merlon.ch/v1— routes to your account's default region.- Protocol
- HTTPS only, TLS 1.2+. Plain-HTTP requests are rejected before they reach the application.
- Format
- JSON request and response bodies (UTF-8). Timestamps are RFC 3339 / ISO 8601 in UTC.
- Authentication
- Bearer token in the
Authorizationheader, or OAuth2 for user-context apps. - Versioning
- The major version is pinned in the path (
/v1). Breaking changes ship under a new major version.
From zero to your first document in three steps
The whole flow takes about five minutes. Grab a key, prove who you are with a bearer token, and post your first document. Every snippet below is copy-paste ready.
Get an API key
Create a key from Settings → API keys in the dashboard. Keys are scoped to a single environment — test keys hit the sandbox, live keys hit production. Store the secret in your secrets manager; merlon shows the full value only once, at creation.
# Keep your secret key server-side only — never ship it to a browser. export MERLON_API_KEY="sk_live_51Kf9c1Za8Xq2Wn4dPmR0" export MERLON_BASE="https://api.merlon.ch/v1"
Authenticate with a bearer token
Send your key in the Authorization header on every request. A quick call to GET /v1/whoami confirms the key is valid and tells you which account, region, and scopes it maps to.
curl "$MERLON_BASE/whoami" \ -H "Authorization: Bearer $MERLON_API_KEY"
{
"account_id": "acct_7Qd2",
"region": "eu",
"environment": "live",
"scopes": ["documents:write", "vaults:read", "audit:read"],
"rate_limit": 600
}
Make your first request — POST /v1/documents
Create a document inside a vault. Pass an Idempotency-Key so a retried request never creates a duplicate. The API returns the new resource with a server-assigned id and a draft status you can advance through the workflow later.
curl -X POST "$MERLON_BASE/documents" \ -H "Authorization: Bearer $MERLON_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 3f0c-b12a-7d91" \ -d '{ "title": "Master Services Agreement — Acme", "vault_id": "vault_9f2c", "metadata": { "counterparty": "Acme Holdings", "retention": "7y" } }'
{
"id": "doc_3kf9c1Za",
"object": "document",
"title": "Master Services Agreement — Acme",
"vault_id": "vault_9f2c",
"status": "draft",
"created_at": "2026-07-27T09:41:08Z",
"region": "eu"
}
Everything you need to integrate deeply
The API is built for real production integrations — not just reads. Write paths are safe to retry, events are delivered reliably, and the tooling around the API is first-class.
REST API
Predictable, resource-oriented endpoints with standard HTTP verbs and status codes.
Webhooks
Signed, retried event delivery for document, signature, workflow and audit events.
SDKs
Idiomatic client libraries for Node, Python, Go and PHP, with typed models.
Postman collection
Import a ready-made collection with every endpoint and example pre-filled.
Sandbox
A fully isolated test environment with seed data — no real documents at risk.
Idempotency
Send an Idempotency-Key on writes so retries never double-create.
Pick your language and go
Official libraries wrap authentication, retries, pagination and typed models so you can call the API in a single line. Install, set your key, create a document.
// npm install @merlon/sdk import Merlon from "@merlon/sdk"; const merlon = new Merlon(process.env.MERLON_API_KEY); const doc = await merlon.documents.create({ title: "MSA — Acme", vault_id: "vault_9f2c", }); console.log(doc.id); // → doc_3kf9c1Za
# pip install merlon import merlon client = merlon.Client(api_key=os.environ["MERLON_API_KEY"]) doc = client.documents.create( title="MSA — Acme", vault_id="vault_9f2c", ) print(doc.id) # → doc_3kf9c1Za
// go get github.com/merlon/merlon-go client := merlon.New(os.Getenv("MERLON_API_KEY")) doc, err := client.Documents.Create(ctx, &merlon.DocumentParams{ Title: "MSA — Acme", VaultID: "vault_9f2c", }) if err != nil { log.Fatal(err) } fmt.Println(doc.ID) // → doc_3kf9c1Za
// composer require merlon/merlon-php $merlon = new \Merlon\Client(getenv("MERLON_API_KEY")); $doc = $merlon->documents->create([ "title" => "MSA — Acme", "vault_id" => "vault_9f2c", ]); echo $doc->id; // → doc_3kf9c1Za
SDKs are available for the languages and runtimes shown above. See the API reference for full details.
React to events the moment they happen
Signed, retried, ordered
Register an HTTPS endpoint and merlon POSTs a JSON payload whenever a document is signed, a workflow advances, or an audit event is written. Each delivery carries an X-Merlon-Signature HMAC header so you can verify authenticity, and failed deliveries retry with exponential backoff for up to 24 hours.
HMAC signatures
Verify every payload with your signing secret.
Automatic retries
Backoff up to 24h until you return 2xx.
Event log
Replay any delivery from the dashboard.
Filtered subscriptions
Subscribe only to the event types you need.
POST /your-endpoint
X-Merlon-Signature: t=1753..,v1=8a2f..
{
"id": "evt_5Rk21m",
"type": "signature.completed",
"created_at": "2026-07-27T09:44:12Z",
"data": {
"document_id": "doc_3kf9c1Za",
"signer": "gc@acme.com",
"ip_verified": true,
"vault_id": "vault_9f2c"
}
}
Predictable limits, honest errors
The API tells you exactly where you stand. Rate-limit headers ship on every response, and errors use standard HTTP status codes with a machine-readable body.
- Default limit
- 600 requests per minute per API key, burstable to 1,000.
- Headers
X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset.- Over limit
- HTTP
429with aRetry-Afterheader in seconds. - Error shape
- A JSON body with
type,messageandrequest_id.
{
"error": {
"type": "validation_error",
"message": "vault_id is required",
"param": "vault_id",
"request_id": "req_9c1Za8Xq"
}
}
Full error-code table lives in the API reference → Errors.
Call the region where your data lives
Data residency is enforced at the edge. Use the base URL that matches your account's region so requests never leave the intended jurisdiction.
United States
- Endpoint
api.us.merlon.ch/v1- Residency
- US-east data centre
- Compliance
- SOC 2 Type II · HIPAA-ready · US DPF
Switzerland / EU
- Endpoint
api.eu.merlon.ch/v1- Residency
- Swiss data centre (Zürich)
- Compliance
- nFADP · GDPR · ISO 27001
Keep building
Test against a full, isolated environment
The sandbox mirrors production behaviour with realistic seed data — vaults, documents, and webhook events — but nothing you do there touches real customer data. It's the safe place to build and demo before you flip a key to live.
Common questions
Idempotency-Key header on any POST and merlon guarantees the operation runs at most once, even if the network drops mid-request. Retries return the original response.api.us or api.eu) and residency is enforced at the edge. See Compliance & Regions.