API Reference

Automate signature flows end to end: upload a document, create and send a flow, track it, and download the signed PDF plus its verification report.

Base URL https://cloud-signing.com — all paths below are relative. All requests and responses are JSON unless noted (uploads are multipart/form-data, downloads are PDF).

# 1) upload a document
curl -X POST https://cloud-signing.com/api/documents \
  -H "X-Api-Key: mpk_..." -F "file=@contract.pdf"

# 2) create + send a flow
curl -X POST https://cloud-signing.com/api/flows \
  -H "X-Api-Key: mpk_..." -H "Content-Type: application/json" \
  -d '{"title":"Contract","documentIds":["<docId>"],"mode":"Sequential",
       "participants":[{"kind":"ExternalEmail","email":"signer@example.com",
                        "order":0,"role":"Signer","method":"SelfSigned"}]}'
curl -X POST https://cloud-signing.com/api/flows/<flowId>/send -H "X-Api-Key: mpk_..."

# 3) poll + download the signed document
curl https://cloud-signing.com/api/flows/<flowId>/status -H "X-Api-Key: mpk_..."
curl -o signed.pdf https://cloud-signing.com/api/flows/<flowId>/documents/<docId>/content \
  -H "X-Api-Key: mpk_..."

Authentication

Two credentials, routed automatically by shape:

API key (recommended for integrations)	Issued at signup (`mpk_…`, shown once). Send as `X-Api-Key: mpk_…` or `Authorization: Bearer mpk_…`. Scoped to your organization.
JWT	`POST /api/auth/login` with email + password → short-lived token, sent as `Authorization: Bearer <jwt>`. Accounts with two-factor auth enabled receive an MFA challenge instead and complete it at `POST /api/auth/mfa/verify`.

Login and signup are rate-limited per IP (HTTP 429 with Retry-After). Keep API keys server-side; they carry your whole tenant.

Signup

Self-provision a tenant. The response contains your first API key (shown once).

Login (JWT)

Exchange email + password for a JWT. Most integrations skip this and send the API key directly.

POST/api/auth/mfa/verify

Completes an MFA login: short-lived token from `login` + a TOTP or recovery code → JWT.

Request body application/json · MfaVerifyRequest

`mfaToken`	string
`code`	string

200 LoginResponse

Documents

Upload PDF or Office files (Word/Excel/PowerPoint are converted to PDF) and download content.

GET/api/Documents

Lists documents of the current tenant.

200 DocumentResponse[]

POST/api/Documents

Uploads a PDF document.

Request body multipart/form-data · object

file string (binary)

200 DocumentResponse

GET/api/Documents/{id}

Gets document metadata.

Parameter	In	Type
`id`	path	string (uuid)	required

200 DocumentResponse

GET/api/Documents/{id}/content

Downloads the (original) document content.

Parameter	In	Type
`id`	path	string (uuid)	required

200 OK

Signature flows

Create flows, add participants, send invitations, track status, fetch signed documents and verification reports.

GET/api/Flows

Lists flows of the current tenant.

200 FlowResponse[]

POST/api/Flows

Creates a signature flow (Draft).

Request body application/json · CreateFlowRequest

`title`	string
`mode`	FlowMode (Sequential \| Parallel)
`documentIds`	string (uuid)[]
`participants`	ParticipantInput[]
`dueDate`	string (date-time)
`message`	string
`language`	string

200 FlowResponse

POST/api/Flows/bulk

Bulk send: one document to many recipients. Each recipient gets an independent single-signer flow with the same placement/fields, its own magic link, and an invitation email.

Request body application/json · BulkSendRequest

`title`	string
`documentId`	string (uuid)
`message`	string
`language`	string
`method`	SignatureMethod (SelfSigned \| Timestamp \| IdAustria \| ATrustSeal \| SwisscomAis \| QuoVadis \| OrgCertificate)
`signingEnvironmentId`	string (uuid)
`placements`	SignaturePlacement[]
`fields`	FieldPlacement[]
`recipients`	BulkRecipient[]

200 BulkSendResponse

GET/api/Flows/{id}

Gets a flow with participants.

Parameter	In	Type
`id`	path	string (uuid)	required

200 FlowResponse

DELETE/api/Flows/{id}

Deletes a flow and purges its signed documents (blobs) plus all child rows. Works for any status — deleting an in-progress flow invalidates its pending magic links (effectively cancelling it). Restricted to a tenant admin or the flow's creator. Supports GDPR erasure (Art. 17): removes participant emails, the signed PDFs (which carry the signatures + embedded biometric data), signing tasks and the flow's audit trail. The original uploaded document is intentionally kept — it can be shared by other flows (bulk send).

Parameter	In	Type
`id`	path	string (uuid)	required

200 OK

GET/api/Flows/{id}/audit

Returns the flow's audit trail (append-only), oldest first.

Parameter	In	Type
`id`	path	string (uuid)	required

200 AuditEventDto[]

GET/api/Flows/{id}/documents

Lists a flow's documents with their signed state.

Parameter	In	Type
`id`	path	string (uuid)	required

200 FlowDocumentInfo[]

GET/api/Flows/{id}/documents/{documentId}/content

Downloads a flow document — the signed revision if available, otherwise the original.

Parameter	In	Type
`id`	path	string (uuid)	required
`documentId`	path	string (uuid)	required

200 OK

POST/api/Flows/{id}/documents/{documentId}/email

Emails a flow document (signed revision if available) as a PDF attachment.

Parameter	In	Type
`id`	path	string (uuid)	required
`documentId`	path	string (uuid)	required

Request body application/json · EmailDocumentRequest

to string

200 OK

GET/api/Flows/{id}/documents/{documentId}/validate

Validates a flow document's signatures via the external miPDFvalidator and returns a <b>PDF verification report</b>. Two hops (validator's own API): the signed PDF → `/api/validate` (JSON report) → that report → `/api/report` (rendered PDF). The validator is not publicly reachable, so this is proxied.

Parameter	In	Type
`id`	path	string (uuid)	required
`documentId`	path	string (uuid)	required
`lang`	query	string

200 OK

POST/api/Flows/{id}/participants/{participantId}/link

Re-issues the magic link for a still-pending participant and returns the URL — for copying the invite into another channel (chat, in person on a shared device). The previously emailed link becomes invalid (tokens are stored hashed and cannot be recovered, so re-issuing is the only way to get a URL again). Restricted to a tenant admin or the flow's creator, on a sent flow.

Parameter	In	Type
`id`	path	string (uuid)	required
`participantId`	path	string (uuid)	required

200 ParticipantLinkResponse

POST/api/Flows/{id}/send

Sends the flow: issues magic-link tokens, marks it in-progress, and enqueues the signing job.

Parameter	In	Type
`id`	path	string (uuid)	required

200 SendFlowResponse

GET/api/Flows/{id}/status

Gets the flow status (lightweight).

Parameter	In	Type
`id`	path	string (uuid)	required

200 OK

Templates

Reusable flows: a stored document plus participant roles; instantiate with concrete recipients.

GET/api/Templates

200 TemplateListItemDto[]

POST/api/Templates

Request body application/json · UpsertTemplateRequest

`name`	string
`documentId`	string (uuid)
`mode`	FlowMode (Sequential \| Parallel)
`message`	string
`language`	string
`roles`	TemplateRoleDto[]

200 TemplateDto

GET/api/Templates/{id}

Parameter	In	Type
`id`	path	string (uuid)	required

200 TemplateDto

DELETE/api/Templates/{id}

Parameter	In	Type
`id`	path	string (uuid)	required

200 OK

Signing methods

Discover which signing methods/environments the organization can use.

GET/api/providers

200 ProviderResponse[]

GET/api/providers/environments

The org's enabled signing environments as selectable options — one per environment, so several environments of the same method (e.g. two named OrgCertificate certs) are distinct, name-labelled choices. This is what the flow-creation UI offers per signer; picking one pins the exact credentials to use.

200 SigningOptionDto[]

Verification

Anonymous first-party signature verification of any signed PDF.

POST/api/verify

Request body multipart/form-data · object

file string (binary)

200 VerificationResponse

Webhooks

Push instead of poll: enable the Webhook plugin under Administration → Plugins with your endpoint URL. On flow completion, miPDFsign Cloud POSTs once per signed document. Two delivery formats (selectable next to the URL):

PDF (binary) — default	The signed PDF itself (`Content-Type: application/pdf`), file name in `Content-Disposition`. Ideal for direct archiving.
JSON event	`{"event":"flow.document_completed","flowId":"…","documentId":"…","fileName":"…","occurredAt":"…"}` — no content; fetch the PDF via the API with your key. Ideal for Zapier and event pipelines.

Both formats carry the ids in the X-miPDFsign-Flow and X-miPDFsign-Document request headers.

Security: the URL is your only shared secret — use an unguessable endpoint (e.g. the random hook URLs Zapier/Make generate) and HTTPS. Failed deliveries are logged and retried on the next completion only, so keep the receiver highly available or poll as a fallback.

Recipes: Zapier & Make

No custom app needed — the generic webhook + HTTP modules of both platforms cover the full loop: trigger on completion → fetch the signed PDF → act (archive, notify, CRM update), and in the other direction create & send flows from any event.

Trigger: "flow completed" → your scenario

Make (recommended for archiving):

1	Add a Webhooks → Custom webhook module and copy its URL.
2	In miPDFsign Cloud: Administration → Plugins → Webhook — paste the URL, pick the format, enable, save. PDF (binary) delivers the file straight into Make: the next module (Google Drive / SharePoint / email…) can use the webhook's data as the file to store — done, two modules total.
3	With JSON event instead: add an HTTP → Make a request module — `GET /api/flows/{{flowId}}/documents/{{documentId}}/content` with header `X-Api-Key: mpk_…` — and feed its response into the storage module.

Zapier:

1	Trigger: Webhooks by Zapier → Catch Hook; copy the hook URL.
2	In miPDFsign Cloud: Administration → Plugins → Webhook — paste the URL and choose the JSON event format (Zapier parses JSON into fields automatically).
3	Action: Webhooks by Zapier → GET on `https://cloud-signing.com/api/flows/{{flowId}}/documents/{{documentId}}/content` with header `X-Api-Key: mpk_…`, then pass the file to any following action (Drive, Slack, email…).

Action: create & send a flow from Zapier/Make

Use the HTTP module with your API key and the three calls from Getting started:

1	`POST /api/documents` — multipart upload of the PDF/Office file (in Make: HTTP module, body type multipart/form-data, field `file`; in Zapier: Custom Request with the file from a previous step).
2	`POST /api/flows` — JSON body with title, `documentIds` and participants (see Signature flows).
3	`POST /api/flows/<flowId>/send` — invitations go out; the response also returns the magic links for custom delivery.

Typical scenarios: “New row in Google Sheets → send contract for signature”, “Deal won in CRM → send order form”, “Flow completed → archive signed PDF + verification report in SharePoint and notify the channel”.

`organizationName`	string
`adminEmail`	string
`adminDisplayName`	string
`password`	string