REST API reference

Build with the API.

Use HTTPS and bearer authentication from your server. Upload PDFs as multipart form data; send call-session requests as JSON. Responses describe the resource or result you created.

Download OpenAPI 3.1 Authentication & workload identity Email-security OpenAPI

Choose the matching region

Use the endpoint for the regional workspace where you created the key. Sandbox and production use the same host with separate credentials.

https://eu.mimeprotect.comEuropean Union storage

https://us.mimeprotect.comUnited States storage

https://fedramp.mimeprotect.comFedRAMP storage jurisdiction

How regional workspaces work →

POST/api/security/token

Exchange an OIDC workload assertion

Exchange one assertion from an approved OIDC issuer. Exact issuer, audience, subject and optional claims must match the trust. Each assertion is accepted once. Returned access tokens expire within five minutes. See the authentication guide for provider setup and permissions.

Request parameters

grant_typestring · required

Value for this request.Allowed values: urn:ietf:params:oauth:grant-type:token-exchange

subject_token_typestring · required

Value for this request.Allowed values: urn:ietf:params:oauth:token-type:jwt

subject_tokenstring · required

Fresh provider JWT; never log or expose this assertion.

trust_idstring · required

Value for this request.

scopestring · optional

Optional space-separated subset of the trust permissions.

Request

curl https://eu.mimeprotect.com/api/security/token \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
  --data-urlencode "trust_id=$MIMEPROTECT_TRUST_ID" \
  --data-urlencode "subject_token=$OIDC_ASSERTION"

Response codes

200

access_token, token_type, expires_in, issued_token_type and granted scope; never cache

400

Invalid assertion, replay, target or requested scope

421

Use the trust's regional endpoint

429

Rate limit reached; observe Retry-After

GET/api/security/usage

Read product allowances

Request

curl https://eu.mimeprotect.com/api/security/usage \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY"

Response codes

200

Environment, region and current entitlement grants

401

Missing or invalid API key

POST/api/security/documents

Issue a verifiable PDF

Requires document allowance. Adds a proof QR footer to each page and retains an exact-file signed record for 30 days. Production requires approved issuer identity. Input PDF must have at most 5 pages and 10 MB. Print/scan text comparison is a different verification scope.

Request parameters

documentfile · required

An unencrypted PDF up to 5 pages and 10 MB.

Request

curl -X POST https://eu.mimeprotect.com/api/security/documents \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY" \
  -F "document=@document.pdf"

Example response

{
  "id": "a4d18679-9a12-4c90-b768-b064ff44ce98",
  "mode": "sandbox",
  "region": "eu",
  "downloadUrl": "/api/security/files/a4d18679-9a12-4c90-b768-b064ff44ce98?mode=sandbox&region=eu",
  "verifyUrl": "/verify?proof=a4d18679-9a12-4c90-b768-b064ff44ce98&mode=sandbox&region=eu",
  "expiresAt": 1795478400000
}

Response codes

201

Document id, private downloadUrl, public verifyUrl, environment and expiry

402

Allowance exhausted

403

Issuer approval required

415

Unsupported input type

POST/api/security/verify-document

Check a document proof

Recipient checks can be made through the hosted verifier without an account. Server integrations use an API key. Exact-file results distinguish changed, unsigned, expired and unauthenticated records. Uploaded files are not retained by this endpoint.

Request parameters

documentfile · required

An unencrypted PDF up to 5 pages and 10 MB.

proofstring · optional

Proof id from the QR link, if known

modestring · optional

Optional proof lookup environment.Allowed values: sandboxlive

Request

curl -X POST https://eu.mimeprotect.com/api/security/verify-document \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY" \
  -F "document=@document.pdf"

Example response

{
  "status": "verified",
  "title": "Sandbox document matches",
  "detail": "The proof signature is valid and this file exactly matches the bytes registered at issuance.",
  "issuer": "Example organisation",
  "mode": "sandbox",
  "scope": "Exact file integrity."
}

Response codes

200

Verification outcome; inspect status and scope, not HTTP status alone

413

Upload exceeds limit

429

Rate limited

Read status and scope.

HTTP 200 means a result was returned. Only status=verified identifies a matching proof. Unknown, changed, expired and unsupported results must not be treated as verified. A sandbox match is a test result.

GET/api/security/files/{id}

Download your issued PDF

Parameters

iduuid · path · required

The resource identifier returned when you created it.

Request

curl https://eu.mimeprotect.com/api/security/files/a4d18679-9a12-4c90-b768-b064ff44ce98 \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY" \
  --output issued-document.pdf

Response codes

200

PDF, scoped to your organisation and environment

404

Not owned, missing or retention expired

POST/api/security/envelopes

Create a signing invitation

Returns a private signing link for one recipient. Deliver the link through your existing workflow or request delivery=email. Inspect delivery and deliveryMessage; failed delivery does not cancel the created envelope. Sandbox never sends email. Completion consumes one document unit. Personal free access has no business API access.

Parameters

Idempotency-Keystring · header · optional

Use a unique random key per signing request. Retry unchanged document bytes and signing details with the same key for up to 24 hours to recover the same agreement and private link. Reuse with different details returns 409. Retries do not resend email; inspect delivery and deliveryMessage. Scoped to organisation, environment, region and sender (service credentials share a scope, allowing key rotation).

Request parameters

documentfile · required

An unencrypted PDF up to 5 pages and 10 MB.

titlestring · required

The agreement name shown to the recipient.Maximum 150 characters.

recipientstring · required

Email address for the signing invitation.

productstring · required

The signing allowance to use for this request.Allowed values: esign-platformesign-users

deliverystring · optional

Choose link to send the returned URL yourself, or email to request an invitation.Allowed values: linkemail

fieldsstring · optional

JSON array of signing fields: id, type (signature/name/date), 1-based page, x, y, width, height. Coordinates are fractions of the displayed page from its top-left. At least one signature field is required when fields are supplied.

Request

curl -X POST https://eu.mimeprotect.com/api/security/envelopes \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY" \
  -H "Idempotency-Key: $SIGNING_REQUEST_ID" \
  -F "document=@document.pdf" \
  -F 'title=Investment agreement' \
  -F 'recipient=alex@example.com' \
  -F 'product=esign-platform' \
  -F 'fields=[{"id":"signature-1","type":"signature","page":1,"x":0.1,"y":0.7,"width":0.35,"height":0.08}]'

Example response

{
  "id": "a4d18679-9a12-4c90-b768-b064ff44ce98",
  "url": "https://eu.mimeprotect.com/sign/a4d18679-9a12-4c90-b768-b064ff44ce98?token=PRIVATE_SIGNING_TOKEN&org=EXAMPLE_ORG_ID&mode=sandbox&region=eu",
  "expiresAt": 1793491200000,
  "delivery": "link",
  "deliveryMessage": "Sandbox created a test link. No email was sent."
}

Response codes

201

Envelope id, private signing URL and 7-day invitation expiry

402

Allowance required

403

Business API entitlement required

409

Idempotency key reused with different details, or reservation expired during processing

Keep the private signing URL confidential. Poll the signing request to track completion, then retrieve the completed PDF and evidence. Inspect delivery before deciding whether to share the link yourself.

GET/api/security/envelopes/{id}

Read a signing request

Poll this resource to track signing. A completed request includes completedDocumentUrl and evidenceUrl. Use the same organisation, region and environment key as the request. Timestamps are Unix milliseconds.

Parameters

iduuid · path · required

The resource identifier returned when you created it.

Request

curl https://eu.mimeprotect.com/api/security/envelopes/a4d18679-9a12-4c90-b768-b064ff44ce98 \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY"

Example response

{
  "id": "a4d18679-9a12-4c90-b768-b064ff44ce98",
  "title": "Investment agreement",
  "recipient": "alex@example.com",
  "status": "completed",
  "product": "esign-platform",
  "mode": "sandbox",
  "region": "eu",
  "createdAt": 1792886400000,
  "expiresAt": 1793491200000,
  "completedAt": 1792886460000,
  "completedDocumentUrl": "/api/security/files/a4d18679-9a12-4c90-b768-b064ff44ce98?mode=sandbox&region=eu",
  "evidenceUrl": "/api/security/envelopes/a4d18679-9a12-4c90-b768-b064ff44ce98/evidence?mode=sandbox&region=eu"
}

Response codes

200

Signing status, title, recipient, expiry and completed resource URLs

404

Request missing, not accessible or expired

GET/api/security/envelopes/{id}/source

Download the source agreement

Retrieve the original agreement using esignature:read permission in the matching organisation, region and environment.

Parameters

iduuid · path · required

The resource identifier returned when you created it.

Request

curl https://eu.mimeprotect.com/api/security/envelopes/a4d18679-9a12-4c90-b768-b064ff44ce98/source \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY"

Response codes

200

Source PDF

404

Request missing, not accessible or expired

GET/api/security/envelopes/{id}/evidence

Download signing evidence

Retrieve the completion record after signing. Archive it with the completed PDF before retention expires.

Parameters

iduuid · path · required

The resource identifier returned when you created it.

Request

curl https://eu.mimeprotect.com/api/security/envelopes/a4d18679-9a12-4c90-b768-b064ff44ce98/evidence \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY"

Response codes

200

Signing evidence as a JSON attachment

404

Request or evidence missing, not accessible or expired

409

Signing has not completed

POST/api/security/call-sessions

Create a call or SMS verification session

Returns the initial one-time code. Session expires after 5 minutes. Production requires sender approval. Creation reserves capacity; only completed confirmation consumes the verification unit.

Request parameters

senderstring · required

E.164 phone number or 2–11 character alphanumeric SMS sender ID

purposestring · required

Value for this request.Maximum 150 characters.

Request

curl -X POST https://eu.mimeprotect.com/api/security/call-sessions \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sender":"+442079460000","purpose":"Scheduled account review"}'

Example response

{
  "id": "a4d18679-9a12-4c90-b768-b064ff44ce98",
  "code": "EU-M7KP-92XR-4T6D",
  "sender": "+442079460000",
  "purpose": "Scheduled account review",
  "mode": "sandbox",
  "expiresAt": 1792886700000
}

Response codes

201

Session id, initial code, sender, purpose, environment and expiry

402

Allowance exhausted

POST/api/security/call-challenge

Read the current agent-side return challenge

Request parameters

idstring · required

The session identifier from creation.

Request

curl -X POST https://eu.mimeprotect.com/api/security/call-challenge \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"a4d18679-9a12-4c90-b768-b064ff44ce98"}'

Response codes

200

Code, authoritative server time, expiry, organisation and purpose; never cache

409

Waiting for customer or already confirmed

410

Session expired

POST/api/security/call-confirm

Confirm a return code once

Current 30-second epoch only. Five failed agent attempts lock confirmation. A completed session cannot be confirmed again.

Request parameters

idstring · required

The session identifier from creation.

codestring · required

The current six-digit return code read back by the customer.

Request

curl -X POST https://eu.mimeprotect.com/api/security/call-confirm \
  -H "Authorization: Bearer $MIMEPROTECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"a4d18679-9a12-4c90-b768-b064ff44ce98","code":"123456"}'

Response codes

200

Session state confirmed; one unit consumed

403

Wrong or rotated challenge

409

Session already consumed

429

Attempt limit reached

Errors, retries and resource state

Keep the returned resource ID with your own record. For signing requests, set SIGNING_REQUEST_ID to a random UUID, retain it and send it as the Idempotency-Key header. Retry unchanged details with the same key for up to 24 hours to recover the same agreement. Other creation endpoints do not yet support this header; inspect their state before creating again.

401

Missing, invalid or expired key. Check the key and region.

402

No remaining eligible allowance. Check Billing before retrying.

403

The operation requires a permission, issuer approval or sender approval.

409

The current resource state prevents this operation.

413

The upload exceeds the supported limit.

421

The key and endpoint region do not match.

429

A request or attempt limit was reached. Avoid immediate repeated retries.

5xx

Temporary failure. Retry reads with backoff; inspect creation state before creating again.

Get help with your integration →