API Documentation

WeGoSign API Documentation

Integrate document signing into your applications with our powerful REST API. Send documents for signature, track progress, and automate your workflows.

Webhooks

Receive real-time event notifications

Getting Started

Everything you need to integrate WeGoSign into your application

Introduction

The WeGoSign API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Secure

All API requests are made over HTTPS with SHA-256 hashed API keys

Fast

Average response time under 200ms for most operations

RESTful

Standard REST conventions with predictable resource URLs

Idempotent

Safe to retry requests without creating duplicates

Base URL

https://app.wegosign.com/api/v1

Quickstart

Send your first document for signature in just a few steps:

Get your API key

Navigate to your organization settings in the dashboard and create a new API key.

API keys start with wgs_live_ for production or wgs_test_ for testing.

Create a template

Upload a PDF and define signature fields via the dashboard or API.

curl -X POST https://app.wegosign.com/api/v1/templates \
  -H "Authorization: Bearer wgs_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Contract",
    "description": "Standard employment agreement",
    "document": {
      "data": "base64_encoded_pdf_content",
      "filename": "contract.pdf"
    }
  }'

Send for signature

Create an envelope with your template and specify the signers.

curl -X POST https://app.wegosign.com/api/v1/envelopes \
  -H "Authorization: Bearer wgs_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "template_id_from_step_2",
    "title": "Employment Contract - John Doe",
    "message": "Please review and sign the attached contract.",
    "signers": [
      {
        "name": "John Doe",
        "email": "john@example.com",
        "role": "signer"
      }
    ]
  }'

Done!

The signer receives an email with a link to sign the document. You can track progress via the API or webhooks.

Authentication

The WeGoSign API uses API keys to authenticate requests. You can create and manage API keys from your organization settings in the dashboard.

API Key Format

wgs_live_*

Production keys for live transactions

wgs_test_*

Test keys for development and testing

Making Authenticated Requests

Include your API key in the Authorization header using the Bearer scheme:

Example Request

curl https://app.wegosign.com/api/v1/templates \
  -H "Authorization: Bearer wgs_live_your_api_key"

Keep your API keys secure

Never expose API keys in client-side code or public repositories. Store them securely in environment variables.

API Reference

Complete reference for all API endpoints

Templates

Templates are reusable document definitions with pre-configured signature fields. Upload a PDF, define where signatures should go, and reuse it for multiple envelopes.

GET

/api/v1/templates

List Templates

Retrieves all templates for your organization.

Query Parameters

include_archived

boolean(default: false)

Include archived templates in the response

Response

{
  "data": [
    {
      "id": "tpl_abc123",
      "name": "Employment Contract",
      "description": "Standard employment agreement",
      "pageCount": 3,
      "fieldCount": 5,
      "roles": ["employee", "employer"],
      "isArchived": false,
      "createdAt": 1704543600000,
      "updatedAt": 1704543600000
    }
  ]
}

POST

/api/v1/templates

Create Template

Creates a new template by uploading a PDF document.

Request Body

Template creation payload with base64-encoded PDF

Request

{
  "name": "Employment Contract",
  "description": "Standard employment agreement",
  "document": {
    "data": "base64_encoded_pdf_content",
    "filename": "contract.pdf"
  }
}

Response

Returns the created template with its ID. Use the dashboard to add signature fields.

Response

{
  "data": {
    "id": "tpl_abc123",
    "name": "Employment Contract",
    "description": "Standard employment agreement",
    "documentName": "contract.pdf",
    "createdAt": 1704543600000
  }
}

Envelopes

Envelopes represent documents sent for signature. Create an envelope from a template, specify signers, and track the signing progress.

Envelope Status Lifecycle

draft

sent

viewed

completed

GET

/api/v1/envelopes

List Envelopes

Retrieves all envelopes for your organization with optional filtering.

Query Parameters

status

string

Filter by status: draft, sent, viewed, signed, completed, declined, cancelled, expired

limit

number(default: 50)

Number of results per page

Response

{
  "data": [
    {
      "id": "env_xyz789",
      "title": "Employment Contract - John Doe",
      "status": "sent",
      "templateName": "Employment Contract",
      "signers": [
        {
          "id": "sgn_abc123",
          "name": "John Doe",
          "email": "john@example.com",
          "role": "employee",
          "status": "pending"
        }
      ],
      "createdAt": 1704543600000,
      "completedAt": null,
      "expiresAt": 1705148400000
    }
  ]
}

POST

/api/v1/envelopes

Create & Send Envelope

Creates a new envelope from a template and immediately sends it to all signers.

Request Body

Envelope creation payload

Request

{
  "templateId": "tpl_abc123",
  "title": "Employment Contract - John Doe",
  "message": "Please review and sign the attached contract.",
  "expiresInHours": 168,
  "signers": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "role": "employee",
      "signingOrder": 1,
      "redirectUrl": "https://yourapp.com/signed"
    },
    {
      "name": "Jane Smith",
      "email": "jane@company.com",
      "role": "employer",
      "signingOrder": 2
    }
  ]
}

Response

Returns the envelope ID and signing URLs for each signer.

Response

{
  "data": {
    "id": "env_xyz789",
    "signers": [
      {
        "id": "sgn_abc123",
        "email": "john@example.com",
        "signingUrl": "https://app.wegosign.com/sign/abc123..."
      },
      {
        "id": "sgn_def456",
        "email": "jane@company.com",
        "signingUrl": "https://app.wegosign.com/sign/def456..."
      }
    ]
  }
}

GET

/api/v1/envelopes/:id

Get Envelope

Retrieves detailed information about a specific envelope.

Path Parameters

id

required

string

The envelope ID

Response

{
  "data": {
    "id": "env_xyz789",
    "title": "Employment Contract - John Doe",
    "status": "completed",
    "createdAt": 1704543600000,
    "sentAt": 1704543610000,
    "completedAt": 1704630000000,
    "expiresAt": 1705148400000
  }
}

DELETE

/api/v1/envelopes/:id

Cancel Envelope

Cancels an envelope. Only envelopes in 'sent' status can be cancelled.

Path Parameters

id

required

string

The envelope ID

Response

{
  "data": {
    "id": "env_xyz789",
    "status": "cancelled"
  }
}

POST

/api/v1/envelopes/:id/remind

Send Reminder

Sends a reminder email to signers who haven't completed signing.

Path Parameters

id

required

string

The envelope ID

Request Body

Optional parameters for the reminder

Request

{
  "signerId": "sgn_abc123",
  "message": "Friendly reminder to sign the document."
}

Response

{
  "data": {
    "success": true,
    "remindedCount": 1
  }
}

GET

/api/v1/envelopes/:id/audit-log

Get Audit Log

Retrieves the complete audit trail for an envelope showing all actions.

Query Parameters

limit

number(default: 100)

Number of records to return

Path Parameters

id

required

string

The envelope ID

Response

{
  "data": [
    {
      "id": "log_1",
      "action": "envelope_created",
      "actionDescription": "Envelope created",
      "actorType": "api",
      "actorEmail": "admin@company.com",
      "ipAddress": "192.168.1.1",
      "timestamp": 1704543600000
    },
    {
      "id": "log_2",
      "action": "document_viewed",
      "actionDescription": "Document viewed by signer",
      "actorType": "signer",
      "actorEmail": "john@example.com",
      "ipAddress": "203.0.113.50",
      "timestamp": 1704550000000
    }
  ]
}

Signers

Signers are the recipients of an envelope who need to sign the document. Track individual signer progress and status.

GET

/api/v1/envelopes/:id/signers

Get Envelope Signers

Retrieves all signers for an envelope with their current status.

Path Parameters

id

required

string

The envelope ID

Response

{
  "data": [
    {
      "id": "sgn_abc123",
      "email": "john@example.com",
      "name": "John Doe",
      "role": "employee",
      "signingOrder": 1,
      "status": "signed",
      "viewedAt": 1704550000000,
      "signedAt": 1704560000000,
      "declinedAt": null,
      "declineReason": null,
      "reminderSentAt": null
    }
  ]
}

Bulk Sends

Send documents to multiple recipients at once. Perfect for onboarding, mass communications, or any scenario requiring the same document sent to many people.

Pro Plan Required

POST

/api/v1/bulk-sends

Create Bulk Send

Creates and initiates a bulk send operation for multiple recipients.

Request Body

Bulk send creation payload

Request

{
  "templateId": "tpl_abc123",
  "titlePrefix": "Onboarding Document",
  "message": "Welcome! Please sign your onboarding documents.",
  "expiresInHours": 168,
  "recipients": [
    {
      "email": "john@example.com",
      "name": "John Doe",
      "role": "employee"
    },
    {
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "employee"
    }
  ]
}

Response

Bulk sends are processed asynchronously. Use the GET endpoint to check progress.

Response

{
  "data": {
    "id": "bulk_abc123",
    "totalRecipients": 2,
    "status": "pending",
    "message": "Bulk send started. Envelopes are being created in the background."
  }
}

GET

/api/v1/bulk-sends/:id

Get Bulk Send Status

Retrieves the status and results of a bulk send operation.

Path Parameters

id

required

string

The bulk send ID

Response

{
  "data": {
    "id": "bulk_abc123",
    "templateId": "tpl_abc123",
    "templateName": "Employment Contract",
    "status": "completed",
    "totalRecipients": 2,
    "processedCount": 2,
    "successCount": 2,
    "failureCount": 0,
    "errors": [],
    "createdAt": 1704543600000,
    "completedAt": 1704543700000,
    "envelopes": [
      {
        "id": "env_xyz789",
        "title": "Onboarding Document - John Doe",
        "status": "sent",
        "signers": [
          {
            "email": "john@example.com",
            "status": "sent"
          }
        ]
      }
    ]
  }
}

Webhooks

Receive real-time notifications when events occur in your account. Configure webhook endpoints to automate workflows and keep your systems in sync.

Pro Plan Required

POST

/api/v1/webhooks

Create Webhook

Creates a new webhook endpoint to receive event notifications.

Request Body

Webhook configuration

Request

{
  "url": "https://yourapp.com/webhooks/wegosign",
  "events": [
    "envelope.created",
    "envelope.sent",
    "envelope.completed",
    "signer.viewed",
    "signer.signed",
    "signer.declined"
  ],
  "description": "Main production webhook"
}

Response

The webhook secret is only shown once on creation. Store it securely for signature verification.

Response

{
  "data": {
    "id": "whk_abc123",
    "url": "https://yourapp.com/webhooks/wegosign",
    "events": ["envelope.created", "envelope.completed", "signer.signed"],
    "description": "Main production webhook",
    "secret": "whsec_abc123xyz789...",
    "isActive": true,
    "createdAt": 1704543600000
  }
}

GET

/api/v1/webhooks

List Webhooks

Retrieves all webhooks configured for your organization.

Response

{
  "data": [
    {
      "id": "whk_abc123",
      "url": "https://yourapp.com/webhooks/wegosign",
      "events": ["envelope.completed", "signer.signed"],
      "description": "Main production webhook",
      "isActive": true,
      "failureCount": 0,
      "lastDeliveredAt": 1704550000000,
      "createdAt": 1704543600000
    }
  ]
}

DELETE

/api/v1/webhooks/:id

Delete Webhook

Permanently deletes a webhook endpoint.

Path Parameters

id

required

string

The webhook ID

Response

{
  "data": {
    "id": "whk_abc123",
    "deleted": true
  }
}

Guides

In-depth guides for common use cases

Document Signing Flow

Understanding the complete lifecycle of a document from creation to completion.

Create Template

Upload a PDF and define signature fields via the dashboard or API. Templates are reusable and can be used for multiple envelopes.

Create & Send Envelope

Create an envelope from a template and specify signers. Each signer receives a unique, secure signing link via email.

Signer Views Document

When a signer clicks their link, they can view the document and see where they need to sign. This triggers the 'signer.viewed' webhook.

Signer Completes Signing

The signer fills in required fields and signs. They can draw, type, or upload a signature. This triggers 'signer.signed'.

Document Completed

When all signers complete, the envelope status changes to 'completed'. Download the signed PDF with embedded audit trail.

Signature Field Types

signature

Full signature - draw, type, or upload

initials

Quick initials field

date

Auto-filled date field

text

Free-form text input

checkbox

Checkbox for acknowledgments

Webhook Events

WeGoSign sends webhook notifications for the following events:

envelope.created

An envelope has been created

envelope.sent

An envelope has been sent to signers

envelope.completed

All signers have completed signing

envelope.cancelled

An envelope has been cancelled

envelope.expired

An envelope has expired without completion (coming soon)

signer.viewed

A signer has viewed the document

signer.signed

A signer has completed signing

signer.declined

A signer has declined to sign

Webhook Payload Structure

Example Webhook Payload

{
  "eventId": "evt_abc123xyz",
  "eventType": "envelope.completed",
  "timestamp": 1704543600000,
  "data": {
    "envelopeId": "env_xyz789",
    "title": "Employment Contract - John Doe",
    "status": "completed",
    "completedAt": 1704543600000,
    "signers": [
      {
        "id": "sgn_abc123",
        "email": "john@example.com",
        "name": "John Doe",
        "signedAt": 1704543600000
      }
    ]
  }
}

Verifying Webhook Signatures

Verify that webhooks are actually from WeGoSign by checking the signature header:

Signature Verification (Node.js)

1import crypto from 'crypto';
2
3function verifyWebhookSignature(payload, signature, timestamp, secret) {
4  // Signature format is "sha256=<hex>"
5  const signatureHex = signature.replace('sha256=', '');
6  
7  // Create message: timestamp.payload
8  const message = `${timestamp}.${payload}`;
9  
10  const expectedSignature = crypto
11    .createHmac('sha256', secret)
12    .update(message)
13    .digest('hex');
14
15  return crypto.timingSafeEqual(
16    Buffer.from(signatureHex),
17    Buffer.from(expectedSignature)
18  );
19}
20
21// In your webhook handler
22app.post('/webhooks/wegosign', (req, res) => {
23  const signature = req.headers['x-webhook-signature'];
24  const timestamp = req.headers['x-webhook-timestamp'];
25  const eventType = req.headers['x-webhook-event'];
26  
27  const isValid = verifyWebhookSignature(
28    JSON.stringify(req.body),
29    signature,
30    timestamp,
31    process.env.WEBHOOK_SECRET
32  );
33
34  if (!isValid) {
35    return res.status(401).send('Invalid signature');
36  }
37
38  console.log('Processing event:', eventType);
39  // Process the webhook...
40  res.status(200).send('OK');
41});

Error Handling

The API uses standard HTTP status codes and returns error details in a consistent format.

Error Response Format

Error Response

{
  "error": "validation_error",
  "message": "Invalid email format for signer",
  "details": {
    "field": "signers[0].email",
    "value": "invalid-email"
  }
}

HTTP Status Codes

200

Success - Request completed successfully

201

Created - Resource created successfully

400

Bad Request - Invalid request parameters

401

Unauthorized - Invalid or missing API key

403

Forbidden - Insufficient permissions

404

Not Found - Resource doesn't exist

429

Too Many Requests - Rate limit exceeded

500

Server Error - Something went wrong on our end

Rate Limits

API rate limits vary by plan and operation type. Rate limit information is included in response headers.

Rate Limit Headers

X-RateLimit-Limit

Maximum requests allowed in the window

X-RateLimit-Remaining

Requests remaining in current window

X-RateLimit-Reset

Unix timestamp when the limit resets

Retry-After

Seconds to wait before retrying (429 responses only)

Limits by Plan

Plan	Read Operations	Write Operations	Bulk Operations
Free	API access not available — upgrade to Pro
Pro	200/min	50/min	10/min
Enterprise	200/min	50/min	10/min

Ready to get started?

Create your free account and get API keys to start integrating document signing today.

Contact Support