API Reference

Reference for every public eContract REST endpoint, with the credential and scope each needs, request and response schemas and code samples.

The eContract REST API takes and returns JSON over HTTPS. Each page of this reference documents one operation, generated from the public OpenAPI document, with code samples in cURL, JavaScript, Python, Go, PHP, Java and C#.

Base URL

https://api.econtract.online/api/v1

The public PDF verification endpoint is the one exception: POST https://api.econtract.online/verify-pdf (multipart, no credential).

Authentication

Send one credential in the Authorization header: an API key (cl_live_…) or an OAuth 2.1 access token (eco_at_…). See Authentication and OAuth 2.1.

curl https://api.econtract.online/api/v1/contracts \
  -H "Authorization: Bearer cl_live_your_key_here"

Each operation in the OpenAPI document says who may call it:

`x-econtract-auth`	Meaning
`machine`	Works with API keys and OAuth tokens that carry the scope in `x-econtract-scope` (and with a signed-in user)
`user-session`	Only for people signed in to the web app. API keys and OAuth tokens get `403` (`MACHINE_NOT_ALLOWED`, `SCOPE_REQUIRED` or `HUMAN_ACTION_REQUIRED`)
`public`	No credential needed

Signing and declining are never open to API keys or OAuth tokens: they need a signed-in user or a signer's personal signing link. A machine credential can prepare, send and track a contract, never sign it.

Requests and responses

Write requests send Content-Type: application/json; file uploads use multipart/form-data, and POST /contracts/send also takes base64 files in JSON.
Send an Idempotency-Key header on contract writes so a retry never runs twice. See Idempotency.
Errors share one envelope with a stable code and a requestId:

{
  "statusCode": 409,
  "error": "Conflict",
  "code": "DOCUMENT_NOT_SIGNED",
  "message": "The contract is not completed yet (status: in_signing)",
  "requestId": "0b6f3a52-6c2e-4f7a-9a51-3d4c1f0e2b7d"
}

All codes and what to retry: Errors.

Rate limits

Per API key or OAuth grant: 60 requests a minute, 1,000 an hour and 10,000 a day. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit the API answers 429 RATE_LIMITED with Retry-After. See Limits and pricing.

OpenAPI document

JSON, served by the API: https://api.econtract.online/api/v1/openapi.json
YAML, used by this portal: econtract-api.yaml

Import either into Postman, Insomnia or an OpenAPI client generator. There are no official SDKs yet; a generated client works with every operation above.