Create a session

curl https://api.alentra.app/v1/sessions \
  -H "Authorization: Bearer $ALENTRA_API_KEY" \
  -H "Idempotency-Key: run_4815" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_customer_onboarding",
    "metadata": { "order_id": "order_4815", "customer_id": "cus_17" },
    "return_url": "https://shop.example.com/verified"
  }'

curl https://api.alentra.app/v1/sessions \
  -H "Authorization: Bearer $ALENTRA_API_KEY" \
  -H "Idempotency-Key: contract_4815" \
  -F 'workflow_id=wf_contract_signature' \
  -F 'metadata={"case_id":"case_4815"}' \
  -F '[email protected];type=application/pdf'

{
  "id": "sess_abc123",
  "status": "created",
  "workflow_id": "wf_customer_onboarding",
  "workflow_revision": 3,
  "url": "https://alentra.app/s/sess_abc123",
  "expires": "2026-06-07T12:34:56Z"
}

curl https://api.alentra.app/v1/sessions \
  -H "Authorization: Bearer $ALENTRA_API_KEY" \
  -H "Idempotency-Key: run_4815" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_customer_onboarding",
    "metadata": { "order_id": "order_4815", "customer_id": "cus_17" },
    "return_url": "https://shop.example.com/verified"
  }'

curl https://api.alentra.app/v1/sessions \
  -H "Authorization: Bearer $ALENTRA_API_KEY" \
  -H "Idempotency-Key: contract_4815" \
  -F 'workflow_id=wf_contract_signature' \
  -F 'metadata={"case_id":"case_4815"}' \
  -F '[email protected];type=application/pdf'

{
  "id": "sess_abc123",
  "status": "created",
  "workflow_id": "wf_customer_onboarding",
  "workflow_revision": 3,
  "url": "https://alentra.app/s/sess_abc123",
  "expires": "2026-06-07T12:34:56Z"
}

POST https://api.alentra.app/v1/sessions · Auth: Bearer API key

Creates one non-repeatable session from a published API-only workflow and returns its hosted URL. The workflow owns the primitive sequence and exact order; this endpoint accepts only the workflow id and run-specific input. Creating a session is free; billing occurs per verified step. A signed webhook must be configured for the business first.

Headers

string

required

Bearer YOUR_API_KEY

string

Optional. A repeat with the same key returns the original session instead of creating a duplicate. Reuse does not compare payloads; use a new key for each logical run.

Body

string

required

The id of a live workflow whose access mode is API only. Inline steps[] are rejected; edit and publish the workflow in the dashboard instead.

object

Up to 50 string-valued keys (key up to 40 characters, value up to 500). Use this for caller-owned correlation context such as order_id or case_id. It is returned in signed webhooks and authenticated session reads, and never shown to the signer.

string

An https URL. Renders a “Return to {host}” button on the hosted page after completion; it never causes an automatic redirect.

integer

Session TTL in seconds (60–86400). Defaults to the standard cap.

There is no recipient_email field. Dashboard invitation delivery does not identify the signer, and the signer independently chooses at completion whether to send their result to a verified email address. Treat metadata as retained operational data—not a secret store—and do not include credentials, payment data, or unnecessary PII.

Signing documents

If the published workflow contains sign, use multipart/form-data. Send workflow_id as a form field and each document as one named file part. Alentra injects those document ids into this session’s immutable workflow snapshot, hashes the exact bytes, and presents those bytes to the signer. The reusable workflow stores no files.

Response

string

The session id, e.g. sess_abc123.

string

created.

string

The hosted page URL to hand the user.

string

ISO 8601 expiry timestamp.

string

The workflow used for this run.

integer

The immutable published revision snapshotted by the session.

curl https://api.alentra.app/v1/sessions \
  -H "Authorization: Bearer $ALENTRA_API_KEY" \
  -H "Idempotency-Key: run_4815" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_customer_onboarding",
    "metadata": { "order_id": "order_4815", "customer_id": "cus_17" },
    "return_url": "https://shop.example.com/verified"
  }'

curl https://api.alentra.app/v1/sessions \
  -H "Authorization: Bearer $ALENTRA_API_KEY" \
  -H "Idempotency-Key: contract_4815" \
  -F 'workflow_id=wf_contract_signature' \
  -F 'metadata={"case_id":"case_4815"}' \
  -F '[email protected];type=application/pdf'

{
  "id": "sess_abc123",
  "status": "created",
  "workflow_id": "wf_customer_onboarding",
  "workflow_revision": 3,
  "url": "https://alentra.app/s/sess_abc123",
  "expires": "2026-06-07T12:34:56Z"
}

Errors

400 missing workflow id / inline steps / invalid metadata or files · 401 bad key or archived/frozen business · 402 insufficient balance · 409 workflow not live or wrong launch mode · 422 no webhook configured. See Errors.

Overview

Sessions

Audits

Discovery

Webhooks

Headers

Body

Signing documents

Response

Errors

​Headers

​Body

​Signing documents

​Response

​Errors

Headers

Body

Signing documents

Response

Errors