Agents API

Base URL: https://api.doctransit.com/v1
OpenAPI: GET /v1/openapi.json

Endpoints

Method	Path	Description
GET	/me	Key, scopes, plan, signing_mandate, flags
GET	/flags	Deploy-time feature flags
GET	/mandates	Signing mandates granted to this key
GET	/mandates/:id	Mandate detail
GET/POST	/contacts	List or invite Agent Contacts
GET	/contacts/:id	Contact detail
POST	/contacts/:id/accept	Accept an inbound invite
POST	/contacts/:id/revoke	Revoke a contact (both sides)
GET	/offers	Inbound and outbound offers
GET	/offers/:id	Offer detail
POST	/documents/:id/offers	propose_contract to an active contact
POST	/offers/:id/ack	Acknowledge an inbound offer
POST	/offers/:id/accept	Accept (L2 signs, L1 escalates)
POST	/offers/:id/decline	Decline
POST	/offers/:id/escalate	Force L1 confirm
POST	/documents/:id/sign	L2 sign_as_principal (in-policy auto-sign + notify)
POST	/documents/:id/sign-requests	L1 request_sign (principal must confirm)
GET	/documents/:id/sign-requests	List sign requests for this key
GET	/sign-requests/:id	Sign request status
GET	/templates	List templates
GET	/templates/:id	Template detail
POST	/documents	Create (optional send: true)
GET	/documents	List
GET	/documents/:id	Status + sign links
POST	/documents/:id/signers	Add signers (draft only)
POST	/documents/:id/send	Send (confirm: true)
GET	/documents/:id/download	Signed PDF URL
GET/POST	/webhooks	Manage webhooks
DELETE	/webhooks/:id	Delete webhook
POST	/assets	Upload a Drive file (zip, office, images, pdf)
GET	/drive	List Drive items
POST	/transfers	Create a package from drive_file_ids
GET	/transfers	List sent or received packages
GET	/transfers/:id	Package detail
POST	/transfers/:id/offer	Offer (confirm: true) and mint claim links
POST	/transfers/claim	Claim with this API key ({ token })
POST	/transfers/accept	Accept-to-unlock ({ token })
POST	/public/transfers/:token/accept	Guest accept, no account
POST	/transfers/:id/downloads	Mint download URLs (sender or bound recipient)
POST	/transfers/:id/cancel	Cancel and revoke claim links
GET	/public/transfers/:token	Guest claim metadata (no file URLs)
POST	/public/transfers/:token/downloads	Guest download mint after release
POST	/public/transfers/:token/bind	Bind a matching logged-in session

Create + send example

curl -s https://api.doctransit.com/v1/documents \
  -H "Authorization: Bearer $DOCTRANSIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_ID",
    "name": "NDA — Acme",
    "signers": [{"name":"Ada","email":"ada@example.com"}],
    "send": true
  }'

Responses include document_id, status, signers[].sign_url, and next_actions.

Signing mandates

How L1, L2, widgets, flags, and apply work: Signing with an agent.

GET /me includes signing_mandate when this key has an active open mandate. GET /mandates lists mandates granted to this key (not every key on the account).

Grant and revoke happen in the app: Developer → Signing Mandates. The grant clickwrap + email OTP is the intent event. documents:sign is attached to the key only after grant, and removed when the last active mandate for that key is revoked.

curl -s https://api.doctransit.com/v1/mandates \
  -H "Authorization: Bearer $DOCTRANSIT_API_KEY"

L1 request_sign

Propose a signature on a sent document where the principal is a signer. Returns confirm_url. The stored appearance is applied only after the principal confirms.

curl -s https://api.doctransit.com/v1/documents/$DOC_ID/sign-requests \
  -H "Authorization: Bearer $DOCTRANSIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"NDA matches standing policy"}'

L2 sign_as_principal

Apply the stored appearance now on a sent, in-scope document. Emails the principal. Daily cap: 25. L1 keys get confirmation_required.

curl -s https://api.doctransit.com/v1/documents/$DOC_ID/sign \
  -H "Authorization: Bearer $DOCTRANSIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"in-policy NDA"}'

GET /documents/:id also works for inbound documents where the principal is a signer.

The offer/accept message set is specified as DASP.

Feature flags

See Signing with an agent — Feature flags. GET /v1/flags and GET /v1/me return the snapshot. Bulk override: DOCTRANSIT_FF={"l2_signing":true,"agent_editor":false}. Per-flag env wins over the JSON blob.

Agent Contacts and offers

Invite by email (POST /contacts). The counterparty accepts in Developer → Agent Contacts or POST /contacts/:id/accept. Status is invited → active → revoked. Optional inbox_url (https) receives offer events for that relationship, in addition to tenant webhooks (contact.invited, contact.accepted, offer.received, offer.accepted, offer.declined, offer.escalated).

curl -s https://api.doctransit.com/v1/contacts \
  -H "Authorization: Bearer $DOCTRANSIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"beau@example.com","name":"Beau"}'

POST /documents/:id/offers with contact_id proposes a sent document. The counterparty must already be a signer. accept uses their mandate: L2 calls sign_as_principal; L1 or human_signature_required: true creates a confirm link.

curl -s https://api.doctransit.com/v1/documents/$DOC_ID/offers \
  -H "Authorization: Bearer $DOCTRANSIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contact_id":"CONTACT_ID","terms":"Standard NDA"}'

Errors

{
  "error": {
    "code": "feature_disabled",
    "message": "l2_signing is not enabled on this deployment.",
    "docs_url": "https://docs.doctransit.com/agents/signing"
  }
}

Signing codes (confirmation_required, missing_appearance, unfilled_fields, …) are listed on Signing with an agent.