---
title: "Create a signature request"
method: POST
path: "/v4/signatures"
tags: ["Signatures V4"]
---

# Create a signature request

`POST /v4/signatures`

## Request

- Base URL: `https://developer.meetergo.com` (the document declares no server; this is the origin it was published from)
- URL: `https://developer.meetergo.com/v4/signatures`
- Auth: one of:
  - API key in header `x-meetergo-api-user-id`
  - HTTP bearer
  - HTTP bearer

Uploads a PDF, places signer-owned signature/text fields on it using normalized (0–1) coordinates, and returns one hosted signing link per signer. Requests support one to ten parallel signers. Every field must name its signer key when more than one signer is present. Completed artifacts are certificate-sealed after hardening is enabled. Each signer can receive the request by SMS or WhatsApp, or use the returned signing link.

## Request body

- CreateSignatureRequestDto
  - `name` string, required: Document / submission name.
  - `file` string, required: The source PDF, base64-encoded (max 20 MB decoded).
  - `fields` SignatureFieldDto[], required: Fields to place on the document. Areas use normalized (0–1) coordinates with a top-left origin and 1-indexed pages — the same model as DocuSeal.
    - `name` string, required: Field name.
    - `signerKey` string: Stable signer key that owns this field. Required when the request has multiple signers.
    - `type` 'signature' | 'initials' | 'text' | 'date' | 'number': Field type. Defaults to "signature".
    - `areas` SignatureAreaDto[], required: One or more placements of this field across the document pages.
      - `x` number, required: Left edge as a fraction of page width (0–1).
      - `y` number, required: Top edge as a fraction of page height (0–1), from the top.
      - `w` number, required: Width as a fraction of page width (0–1).
      - `h` number, required: Height as a fraction of page height (0–1).
      - `page` number, required: Page number, 1-indexed (page 1 is the first page).
  - `signers` SignerInputDto[], required: One to ten parallel signers.
    - `key` string: Stable key used to assign fields to this signer. Required for multi-signer requests.
    - `email` string, email: Signer email address.
    - `name` string: Signer display name.
    - `role` string: Role label, e.g. "First Party".
    - `deliveryChannel` 'link' | 'email' | 'sms' | 'whatsapp': How to deliver this signer invitation. Defaults to returning a copyable link.
    - `phone` string: Mobile number for SMS or WhatsApp delivery. National numbers use the company billing country.
  - `expiresAt` string: ISO-8601 timestamp after which signing links stop working.
  - `language` 'en' | 'de': Signing-page language. Supported: "en", "de". Defaults to English.
  - `completedRedirectUrl` string, uri: URL the signer is sent to after completing (DocuSeal `completed_redirect_url`).
  - `requireOtp` boolean: Require email OTP verification. This expresses the FES intent and requires the Suite plan or above.
  - `sendSignedCopyToSigners` boolean: Email every signer the finished document when the request completes. Defaults to true. Set false when you distribute the signed document yourself.
  - `automaticReminders` boolean: Send unfinished signers a reminder every three days, up to three reminders.
  - `whatsappTemplateName` string: Approved WhatsApp template name used by signers whose delivery channel is WhatsApp.
  - `whatsappTemplateLanguage` string: Language code of the selected WhatsApp template.

## Response `201`

Signature request created with its signer links.

- SignatureRequestResponseDto
  - `id` string, required: Signature request id.
  - `name` string, required: Document name.
  - `schemaVersion` number, required: Persisted envelope schema version.
  - `revision` number, required: Current request revision.
  - `status` 'pending' | 'in_progress' | 'finalizing' | 'finalization_failed' | 'completed' | 'cancelled', required: Overall status.
  - `signers` SignerResponseDto[], required: The signers and their signing links.
    - `id` string, required: Signer id.
    - `email` string, nullable: Signer email.
    - `name` string, nullable: Signer name.
    - `role` string, nullable: Role label.
    - `key` string, nullable: Stable field-assignment key.
    - `status` 'pending' | 'completed', required: Signer status.
    - `invitationDelivery` SignatureInvitationDeliveryResponseDto
      - `channel` 'email' | 'sms' | 'whatsapp', required
      - `phone` string: Normalized E.164 recipient number.
      - `status` 'pending' | 'sent' | 'failed', required
      - `templateName` string
      - `templateLanguage` string
      - `sentAt` string
      - `failureCode` string: Stable failure category when the latest attempt failed.
    - `signingUrl` string, nullable, required: The hosted signing link to send to this signer (the DocuSeal `embed_src` equivalent).
    - `openedAt` string, date-time, nullable: When the signer opened the link.
    - `completedAt` string, date-time, nullable: When the signer completed signing.
  - `signedDocumentUrl` string, nullable: Time-limited download URL for the signed (audit-paged, cryptographically signed) PDF. Present once status is "completed".
  - `completedAt` string, date-time, nullable: When all signers completed.
  - `expiresAt` string, date-time, nullable: When signing links expire (null = never).
  - `automaticReminders` boolean, required: Whether automatic reminders are enabled.
  - `createdAt` string, date-time, required: Creation time.

## Other responses

- `400`: The request did not validate. `message` lists the constraints that failed.
- `401`: Missing, malformed, or expired credentials.
- `403`: Requires an active API Platform subscription.
- `429`: Rate limited. Back off and retry.

---

[API](https://skmtc.dev/meetergo/apis/meetergo-platform-api.md) · [All operations](https://skmtc.dev/meetergo/apis/meetergo-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/meetergo/apis/meetergo-platform-api/revisions/b5d66cd8be67?raw)