WeGoSignWeGoSign
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.

Quickstart

Send your first document in 5 minutes

Authentication

Learn how to authenticate API requests

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://wegosign.com/api/v1

Quickstart

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

1

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.

2

Create a template

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

curl -X POST https://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"
    }
  }'
3

Send for signature

Create an envelope with your template and specify the signers.

curl -X POST https://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"
      }
    ]
  }'
4

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://wegosign.com/api/v1/templates \
  -H "Authorization: Bearer wgs_live_<YOUR_API_KEY>"

Alternative: X-API-Key Header

If your platform strips Authorization headers (common with some serverless environments), you can use theX-API-Key header as a fallback:

X-API-Key: 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

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. Optionally include fields with conditional logic.

Request Body

Template creation payload with base64-encoded PDF and optional fields

Request
{
  "name": "Employment Contract",
  "description": "Standard employment agreement",
  "document": {
    "data": "base64_encoded_pdf_content",
    "filename": "contract.pdf"
  },
  "fields": [
    {
      "id": "field_1",
      "type": "signature",
      "role": "employee",
      "page": 1,
      "x": 100,
      "y": 500,
      "width": 200,
      "height": 50,
      "required": true,
      "label": "Employee Signature"
    },
    {
      "id": "field_2",
      "type": "dropdown",
      "role": "employee",
      "page": 1,
      "x": 100,
      "y": 300,
      "width": 150,
      "height": 30,
      "required": true,
      "label": "Department",
      "options": [
        { "label": "Engineering", "value": "eng" },
        { "label": "Sales", "value": "sales" }
      ]
    }
  ]
}

Response

Returns the created template with field count and roles.

Response
{
  "data": {
    "id": "tpl_abc123",
    "name": "Employment Contract",
    "description": "Standard employment agreement",
    "documentName": "contract.pdf",
    "fieldCount": 2,
    "roles": ["employee"],
    "createdAt": 1704543600000
  }
}
GET
/api/v1/templates/:id

Get Template

Retrieves a template with fields, roles, placeholder keys, archive status, and document URL.

Path Parameters

id
required
string

Template ID

Response

Response
{
  "data": {
    "id": "tpl_abc123",
    "name": "Employment Contract",
    "description": "Standard employment agreement",
    "pageCount": 3,
    "fields": [],
    "roles": ["employee"],
    "placeholderKeys": [],
    "isArchived": false,
    "documentUrl": "https://...",
    "createdAt": 1704543600000,
    "updatedAt": 1704543600000
  }
}
PUT
/api/v1/templates/:id

Update Template

Updates template metadata.

Path Parameters

id
required
string

Template ID

Request Body

Template metadata fields

Request
{
  "name": "Employment Contract v2",
  "description": "Updated employment agreement"
}

Response

Response
{
  "data": {
    "id": "tpl_abc123",
    "name": "Employment Contract v2",
    "description": "Updated employment agreement",
    "updatedAt": 1704543600000
  }
}
DELETE
/api/v1/templates/:id

Archive Template

Archives a template so it no longer appears in default template lists.

Path Parameters

id
required
string

Template ID

Response

Response
{
  "data": {
    "id": "tpl_abc123",
    "archived": true
  }
}
PATCH
/api/v1/templates/:id/fields

Update Template Fields

Updates all fields for a template. Supports all field types and conditional logic.

Request Body

Array of fields with positions, types, and optional conditions

Request
{
  "fields": [
    {
      "id": "field_1",
      "type": "dropdown",
      "role": "signer",
      "page": 1,
      "x": 100,
      "y": 200,
      "width": 150,
      "height": 30,
      "required": true,
      "label": "Select Option",
      "options": [
        { "label": "Option A", "value": "a" },
        { "label": "Option B", "value": "b" }
      ]
    },
    {
      "id": "field_2",
      "type": "text",
      "role": "signer",
      "page": 1,
      "x": 100,
      "y": 250,
      "width": 200,
      "height": 30,
      "required": false,
      "label": "Additional Details",
      "conditions": [
        {
          "sourceFieldId": "field_1",
          "operator": "equals",
          "value": "b"
        }
      ],
      "conditionAction": "show",
      "conditionLogic": "all"
    }
  ]
}

Response

Returns the updated field count and roles.

Response
{
  "data": {
    "id": "tpl_abc123",
    "fieldCount": 2,
    "roles": ["signer"],
    "updatedAt": 1704543600000
  }
}
GET
/api/v1/templates/:id/fields

Get Template Fields

Retrieves all fields for a template including their conditions.

Response

Returns all fields, roles, and placeholder keys for the template.

Response
{
  "data": {
    "templateId": "tpl_abc123",
    "fields": [
      {
        "id": "field_1",
        "type": "dropdown",
        "role": "signer",
        "page": 1,
        "x": 100,
        "y": 200,
        "width": 150,
        "height": 30,
        "required": true,
        "label": "Select Option",
        "options": [
          { "label": "Option A", "value": "a" },
          { "label": "Option B", "value": "b" }
        ]
      }
    ],
    "roles": ["signer"],
    "placeholderKeys": []
  }
}

Packages

Packages bundle multiple templates into a single multi-document signing workflow. Create packages, map package-level roles to template roles, and send them through the envelopes API.

GET
/api/v1/packages

List Packages

Retrieves all template packages for your organization.

Query Parameters

include_archived
boolean(default: false)

Include archived packages in the response

Response

Response
{
  "data": [
    {
      "id": "pkg_abc123",
      "name": "New Hire Package",
      "description": "All onboarding documents",
      "status": "active",
      "templates": [
        {
          "templateId": "tpl_contract",
          "order": 0,
          "name": "Employment Contract",
          "pageCount": 3,
          "fieldCount": 8,
          "roles": ["employee", "employer"]
        }
      ],
      "roleMappings": [],
      "stats": {
        "documentCount": 2,
        "totalFields": 14,
        "totalPages": 7,
        "roleCount": 2
      },
      "createdAt": 1704543600000,
      "updatedAt": 1704543600000
    }
  ]
}
POST
/api/v1/packages

Create Package

Creates a package from one or more templates. Role mappings are auto-generated when omitted.

Request Body

Package creation payload

Request
{
  "name": "New Hire Package",
  "description": "All onboarding documents",
  "templateIds": ["tpl_contract", "tpl_w4"],
  "roleMappings": [
    {
      "packageRoleId": "role_1",
      "packageRoleName": "Employee",
      "color": "#3b82f6",
      "templateRoles": [
        { "templateId": "tpl_contract", "roleId": "employee" },
        { "templateId": "tpl_w4", "roleId": "employee" }
      ]
    }
  ]
}

Response

Returns the created package with template details and aggregate stats.

Response
{
  "data": {
    "id": "pkg_abc123",
    "name": "New Hire Package",
    "description": "All onboarding documents",
    "status": "active",
    "templates": [
      {
        "templateId": "tpl_contract",
        "order": 0,
        "name": "Employment Contract",
        "pageCount": 3,
        "fieldCount": 8,
        "roles": ["employee", "employer"]
      }
    ],
    "roleMappings": [],
    "stats": {
      "documentCount": 2,
      "totalFields": 14,
      "totalPages": 7,
      "roleCount": 2
    },
    "createdAt": 1704543600000,
    "updatedAt": 1704543600000
  }
}
GET
/api/v1/packages/:id

Get Package

Retrieves a specific package by ID.

Path Parameters

id
required
string

The package ID

Response

Returns package metadata, template details, role mappings, and stats.

Response
{
  "data": {
    "id": "pkg_abc123",
    "name": "New Hire Package",
    "description": "All onboarding documents",
    "status": "active",
    "templates": [],
    "roleMappings": [],
    "stats": {
      "documentCount": 2,
      "totalFields": 14,
      "totalPages": 7,
      "roleCount": 2
    },
    "createdAt": 1704543600000,
    "updatedAt": 1704543600000
  }
}
PUT
/api/v1/packages/:id

Update Package

Updates package metadata, template order, or role mappings.

Path Parameters

id
required
string

The package ID

Request Body

Fields to update

Request
{
  "name": "Updated New Hire Package",
  "templateIds": ["tpl_contract", "tpl_w4", "tpl_handbook"]
}

Response

Response
{
  "data": {
    "id": "pkg_abc123",
    "name": "Updated New Hire Package",
    "status": "active",
    "templates": [],
    "roleMappings": [],
    "stats": {
      "documentCount": 3,
      "totalFields": 20,
      "totalPages": 12,
      "roleCount": 2
    },
    "createdAt": 1704543600000,
    "updatedAt": 1704550000000
  }
}
DELETE
/api/v1/packages/:id

Archive Package

Archives a package so it no longer appears in default package lists.

Path Parameters

id
required
string

The package ID

Response

Response
{
  "data": {
    "id": "pkg_abc123",
    "archived": true
  }
}

Envelopes

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

Envelope Status Lifecycle

draft
sent
viewed
completed

Multiple Signers & Signing Order

Sequential Signing

Signers sign one after another. Use different signingOrder values (1, 2, 3...). Signer 2 can only sign after Signer 1 completes.

Parallel Signing

All signers can sign simultaneously. Use the same signingOrder value for all signers (e.g., all set to 1).

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

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 or package with one or more signers. Supports sequential or parallel signing.

Query Parameters

templateId
string

Template ID to send. Provide exactly one of templateId or packageId.

packageId
string

Package ID for a multi-document signing workflow. Provide exactly one of templateId or packageId.

signers
required
array

Array of signers. Each signer needs name, email. Optional: role, signingOrder (for sequential signing), redirectUrl.

signers[].signingOrder
number(default: 1)

Order in which signers sign. Same number = parallel signing. Different numbers = sequential (1 signs first, then 2, etc.).

scheduledAt
string (ISO 8601)

Schedule envelope to be sent at a future time. Must be 5 min to 30 days in the future. Omit to send immediately.

Request Body

Envelope creation payload with multiple signers

Request
{
  "templateId": "tpl_abc123",
  "title": "Employment Contract - John Doe",
  "message": "Please review and sign the attached contract.",
  "expiresInHours": 168,
  "scheduledAt": "2026-01-15T09:00:00Z",
  "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
    },
    {
      "name": "Legal Team",
      "email": "legal@company.com",
      "role": "approver",
      "signingOrder": 3
    }
  ]
}

Response

Returns envelope ID and unique signing URLs for each signer. Status is 'scheduled' if scheduledAt provided, otherwise 'sent'.

Response
{
  "data": {
    "id": "env_xyz789",
    "status": "scheduled",
    "scheduledAt": "2026-01-15T09:00:00.000Z",
    "signers": [
      {
        "id": "sgn_abc123",
        "email": "john@example.com",
        "signingUrl": "https://wegosign.com/sign/abc123..."
      },
      {
        "id": "sgn_def456",
        "email": "jane@company.com",
        "signingUrl": "https://wegosign.com/sign/def456..."
      },
      {
        "id": "sgn_ghi789",
        "email": "legal@company.com",
        "signingUrl": "https://wegosign.com/sign/ghi789..."
      }
    ]
  }
}
GET
/api/v1/envelopes/:id

Get Envelope

Retrieves detailed information about a specific envelope.

Path Parameters

id
required
string

The envelope ID

Response

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

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

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

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
    }
  ]
}
GET
/api/v1/envelopes/:id/download

Download Signed Document

Retrieves download URLs for the signed PDF document and certificate. Only available for completed envelopes.

Query Parameters

type
string(default: all)

What to download: 'document', 'certificate', or 'all'

Path Parameters

id
required
string

The envelope ID

Response

Download URLs expire after 1 hour. Request new URLs if they have expired.

Response
{
  "data": {
    "id": "env_xyz789",
    "title": "Employment Contract - John Doe",
    "status": "completed",
    "completedAt": 1704630000000,
    "documentUrl": "https://storage.convex.cloud/...",
    "certificateUrl": "https://storage.convex.cloud/...",
    "expiresIn": "1 hour"
  }
}

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

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. Supports column mapping for placeholders and prefilled fields, scheduled sends, and error reporting.

Growth Plan & Above
POST
/api/v1/bulk-sends

Create Bulk Send

Creates and initiates a bulk send operation for multiple recipients. Supports column mappings for document placeholders and prefilled signer fields, as well as scheduled sends.

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",
      "additionalData": {
        "company": "Acme Inc",
        "start_date": "2024-02-01",
        "employee_id": "EMP-001"
      }
    },
    {
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "employee",
      "additionalData": {
        "company": "Acme Inc",
        "start_date": "2024-02-15",
        "employee_id": "EMP-002"
      }
    }
  ],
  "columnMappings": {
    "placeholders": {
      "company": "company_name",
      "start_date": "employment_start_date"
    },
    "signerFields": {
      "employee_id": "field_employee_id"
    }
  },
  "scheduledAt": 1704600000000
}

Response

Bulk sends are processed asynchronously. If scheduledAt is provided, status will be 'scheduled' and processing will begin at that time. Column mappings allow mapping recipient additionalData to document placeholders or prefillable signer fields.

Response
{
  "data": {
    "id": "bulk_abc123",
    "totalRecipients": 2,
    "status": "scheduled",
    "scheduledAt": 1704600000000,
    "message": "Bulk send scheduled for 2024-01-07T08:00:00.000Z"
  }
}
GET
/api/v1/bulk-sends/:id

Get Bulk Send Status

Retrieves the status and results of a bulk send operation, including all created envelopes.

Path Parameters

id
required
string

The bulk send ID

Response

Response
{
  "data": {
    "id": "bulk_abc123",
    "templateId": "tpl_abc123",
    "templateName": "Employment Contract",
    "status": "completed",
    "totalRecipients": 2,
    "processedCount": 2,
    "successCount": 2,
    "failureCount": 0,
    "errors": [],
    "columnMappings": {
      "placeholders": { "company": "company_name" },
      "signerFields": { "employee_id": "field_employee_id" }
    },
    "scheduledAt": null,
    "createdAt": 1704543600000,
    "completedAt": 1704543700000,
    "envelopes": [
      {
        "id": "env_xyz789",
        "title": "Onboarding Document - John Doe",
        "status": "sent",
        "placeholderValues": [
          { "key": "company_name", "value": "Acme Inc" }
        ],
        "signers": [
          {
            "email": "john@example.com",
            "status": "sent",
            "prefilledFields": { "field_employee_id": "EMP-001" }
          }
        ]
      }
    ]
  }
}
GET
/api/v1/bulk-sends/:id/errors

Get Error Report

Retrieves a detailed error report for a bulk send. Useful for identifying which recipients failed and why. Supports JSON and CSV formats.

Path Parameters

id
required
string

The bulk send ID

format
string

Response format: 'json' (default) or 'csv'

Response

Use ?format=csv to download errors as a CSV file for easy analysis in spreadsheets.

Response
{
  "data": {
    "bulkSendId": "bulk_abc123",
    "templateId": "tpl_abc123",
    "titlePrefix": "Onboarding Document",
    "status": "completed",
    "summary": {
      "totalRecipients": 10,
      "successCount": 8,
      "failureCount": 2
    },
    "createdAt": 1704543600000,
    "completedAt": 1704543700000,
    "errors": [
      {
        "row": 5,
        "email": "invalid@example",
        "errorType": "invalid_data",
        "errorMessage": "Invalid email format"
      },
      {
        "row": 8,
        "email": "quota@example.com",
        "errorType": "quota_exceeded",
        "errorMessage": "Monthly envelope limit reached"
      }
    ]
  }
}
DELETE
/api/v1/bulk-sends/:id

Cancel Bulk Send

Cancels a bulk send operation and all its associated pending envelopes. Scheduled bulk sends can also be cancelled before they start processing.

Path Parameters

id
required
string

The bulk send ID

Response

Returns the number of envelopes that were cancelled. Completed bulk sends cannot be cancelled.

Response
{
  "data": {
    "id": "bulk_abc123",
    "cancelled": true,
    "cancelledEnvelopes": 5
  }
}

Bulk Send Webhook Events

Subscribe to these webhook events to track bulk send progress:

  • bulk_send.started - Fired when bulk send processing begins
  • bulk_send.completed - Fired when all envelopes have been processed
  • bulk_send.failed - Fired when bulk send fails (all recipients failed)

Invoices

Create, send, and manage client invoices programmatically. Track payments, record partial payments, and receive webhook notifications for the full invoice lifecycle.

Pro Plan & Above

Invoice Lifecycle

draftsentviewedpaid

Invoices can also transition to overdue (past due date), partially_paid (partial payment recorded), or void (cancelled).

GET
/api/v1/invoices

List Invoices

Retrieves all invoices for your organization, optionally filtered by status.

Query Parameters

status
string

Filter by status: draft, sent, viewed, overdue, paid, partially_paid, void

limit
number

Maximum results to return (default: 50, max: 100)

Response

Response
{
  "data": [
    {
      "id": "inv_abc123",
      "invoiceNumber": "INV-0001",
      "clientName": "John Smith",
      "clientEmail": "john@example.com",
      "clientCompany": "Acme Corp",
      "title": "Consulting Services - March 2026",
      "currency": "NGN",
      "totalKobo": 5000000,
      "status": "sent",
      "invoiceDate": 1711929600000,
      "dueDate": 1714521600000,
      "sentAt": 1711929600000,
      "viewCount": 3,
      "createdAt": 1711929600000
    }
  ]
}
POST
/api/v1/invoices

Create Invoice

Creates a new draft invoice. The invoice must be sent separately using the Send endpoint.

Request Body

Invoice details. All amounts are in kobo (smallest currency unit).

Request
{
  "clientName": "John Smith",
  "clientEmail": "john@example.com",
  "clientCompany": "Acme Corp",
  "title": "Consulting Services - March 2026",
  "currency": "NGN",
  "lineItems": [
    {
      "description": "Strategy consulting (10 hours)",
      "quantity": 10,
      "unitPriceKobo": 500000,
      "totalKobo": 5000000
    },
    {
      "description": "Document review",
      "quantity": 1,
      "unitPriceKobo": 200000,
      "totalKobo": 200000
    }
  ],
  "subtotalKobo": 5200000,
  "taxRate": 7.5,
  "taxAmountKobo": 390000,
  "totalKobo": 5590000,
  "invoiceDate": 1711929600000,
  "dueDate": 1714521600000,
  "notes": "Payment due within 30 days."
}

Response

Response
{
  "data": {
    "id": "inv_abc123",
    "invoiceNumber": "INV-0001",
    "status": "draft",
    "totalKobo": 5590000,
    "viewToken": "a1b2c3d4...",
    "createdAt": 1711929600000
  }
}
GET
/api/v1/invoices/:id

Get Invoice

Retrieves a specific invoice with full details including payment history.

Path Parameters

id
required
string

The invoice ID

Response

Response
{
  "data": {
    "id": "inv_abc123",
    "invoiceNumber": "INV-0001",
    "clientName": "John Smith",
    "clientEmail": "john@example.com",
    "title": "Consulting Services",
    "currency": "NGN",
    "lineItems": [...],
    "subtotalKobo": 5200000,
    "taxRate": 7.5,
    "taxAmountKobo": 390000,
    "totalKobo": 5590000,
    "paidAmountKobo": 2000000,
    "status": "partially_paid",
    "payments": [
      {
        "amountKobo": 2000000,
        "paymentDate": 1712534400000,
        "paymentMethod": "bank_transfer",
        "reference": "TXN-12345"
      }
    ],
    "viewCount": 5,
    "lastViewedAt": 1712620800000,
    "sentAt": 1711929600000,
    "dueDate": 1714521600000
  }
}
PATCH
/api/v1/invoices/:id

Update Invoice

Updates a draft invoice. Only invoices in draft status can be modified.

Path Parameters

id
required
string

The invoice ID

Request Body

Fields to update (all optional)

Request
{
  "title": "Updated Title",
  "dueDate": 1714521600000,
  "notes": "Updated payment terms."
}

Response

Response
{
  "data": {
    "id": "inv_abc123",
    "status": "draft",
    "title": "Updated Title",
    "updatedAt": 1712534400000
  }
}
POST
/api/v1/invoices/:id/send

Send Invoice

Sends a draft invoice to the client via email. The invoice status changes to 'sent' and a public view link is generated.

Path Parameters

id
required
string

The invoice ID

Response

Triggers invoice.sent webhook. The client receives an email with a link to view and download the invoice.

Response
{
  "data": {
    "success": true
  }
}
POST
/api/v1/invoices/:id/payments

Record Payment

Records a payment against an invoice. Supports partial payments — the invoice status automatically updates to 'partially_paid' or 'paid' based on the total amount received.

Path Parameters

id
required
string

The invoice ID

Request Body

Payment details

Request
{
  "amountKobo": 2000000,
  "paymentDate": "2026-04-10T00:00:00.000Z",
  "paymentMethod": "bank_transfer",
  "reference": "TXN-12345",
  "note": "First installment"
}

Response

Triggers invoice.payment_recorded webhook on every payment. When fully paid, also triggers invoice.paid webhook and sends a receipt email to the client.

Response
{
  "data": {
    "success": true,
    "status": "partially_paid"
  }
}
POST
/api/v1/invoices/:id/void

Void Invoice

Voids an invoice, making it permanently inactive. Cannot void invoices that are already paid or voided.

Path Parameters

id
required
string

The invoice ID

Response

Triggers invoice.voided webhook.

Response
{
  "data": {
    "success": true
  }
}

Generic Business Apps

Use one API surface for available business apps that share the generic record engine, including Business Intake, Hiring Packets, and Renewals & Compliance.

Apps Platform
GET
/api/v1/apps/:appSlug/records

List App Records

Lists records for an available generic business app.

Query Parameters

status
string

Optional record status filter

limit
number

Maximum records to return

Path Parameters

appSlug
required
string

Available app slug, such as business-intake, hiring-packets, or renewals-compliance

Response

Response
{
  "data": [
    {
      "record": {
        "id": "rec_abc123",
        "appSlug": "business-intake",
        "recordType": "vendor_onboarding",
        "title": "Acme Catering",
        "status": "pending_review"
      }
    }
  ]
}
POST
/api/v1/apps/:appSlug/records

Create App Record

Creates a generic app record using the app's default record type unless recordType is provided.

Path Parameters

appSlug
required
string

Available app slug

Request Body

Generic app record fields

Request
{
  "title": "Acme Catering",
  "recordType": "vendor_onboarding",
  "status": "pending_review",
  "metadata": {
    "contactEmail": "sam@example.com"
  }
}

Response

Response
{
  "data": {
    "id": "rec_abc123"
  }
}
GET
/api/v1/apps/:appSlug/records/:id

Get App Record

Returns one generic app record by ID.

Path Parameters

appSlug
required
string

Available app slug

id
required
string

Generic app record ID

Response

Response
{
  "data": {
    "record": {
      "id": "rec_abc123",
      "appSlug": "business-intake",
      "recordType": "vendor_onboarding",
      "title": "Acme Catering",
      "status": "pending_review"
    }
  }
}
PATCH
/api/v1/apps/:appSlug/records/:id

Update App Record

Updates a generic app record status, title, metadata, or related party fields.

Path Parameters

appSlug
required
string

Available app slug

id
required
string

Generic app record ID

Request Body

Partial record update

Request
{
  "status": "approved",
  "metadata": {
    "reviewedBy": "finance"
  }
}

Response

Response
{
  "data": {
    "success": true
  }
}
GET
/api/v1/apps/:appSlug/records/:id/documents

List App Record Documents

Lists documents attached to a generic app record. The API resolves the record and uses its actual record type.

Path Parameters

appSlug
required
string

Available app slug

id
required
string

Generic app record ID

Response

Response
{
  "data": [
    {
      "id": "doc_abc123",
      "entityType": "vendor_onboarding",
      "fileName": "acme-w9.pdf",
      "status": "pending_review"
    }
  ]
}
POST
/api/v1/apps/:appSlug/records/:id/documents

Attach App Record Document

Uploads a base64-encoded document to a generic app record.

Path Parameters

appSlug
required
string

Available app slug

id
required
string

Generic app record ID

Request Body

Document upload payload

Request
{
  "requirementKey": "tax_form",
  "label": "Signed W-9",
  "document": {
    "filename": "acme-w9.pdf",
    "contentType": "application/pdf",
    "data": "base64..."
  }
}

Response

Response
{
  "data": {
    "id": "doc_abc123"
  }
}
GET
/api/v1/apps/:appSlug/records/:id/approvals

List App Record Approvals

Lists approval requests for a generic app record.

Path Parameters

appSlug
required
string

Available app slug

id
required
string

Generic app record ID

Response

Response
{
  "data": [
    {
      "id": "appr_abc123",
      "entityType": "vendor_onboarding",
      "status": "pending"
    }
  ]
}
POST
/api/v1/apps/:appSlug/records/:id/approvals

Request App Record Approval

Creates an internal approval request for a generic app record.

Path Parameters

appSlug
required
string

Available app slug

id
required
string

Generic app record ID

Request Body

Approval request payload

Request
{
  "title": "Finance approval",
  "mode": "sequential",
  "approvers": [
    { "approverEmail": "finance@example.com", "stepNumber": 1 }
  ]
}

Response

Response
{
  "data": {
    "id": "appr_abc123"
  }
}
GET
/api/v1/apps/:appSlug/records/:id/portal-links

List App Record Portal Links

Lists public intake portal links for a generic app record.

Path Parameters

appSlug
required
string

Available app slug

id
required
string

Generic app record ID

Response

Response
{
  "data": [
    {
      "id": "portal_abc123",
      "status": "active",
      "recipientEmail": "sam@example.com"
    }
  ]
}
POST
/api/v1/apps/:appSlug/records/:id/portal-links

Create App Record Portal Link

Creates a public intake portal link for a generic app record.

Path Parameters

appSlug
required
string

Available app slug

id
required
string

Generic app record ID

Request Body

Portal link payload

Request
{
  "recipientName": "Sam Lee",
  "recipientEmail": "sam@example.com",
  "notificationChannels": ["email"]
}

Response

Response
{
  "data": {
    "id": "portal_abc123",
    "url": "https://wegosign.com/intake/token"
  }
}
DELETE
/api/v1/apps/:appSlug/records/:id/portal-links/:portalLinkId

Revoke App Record Portal Link

Revokes a public intake portal link for a generic app record.

Path Parameters

appSlug
required
string

Available app slug

id
required
string

Generic app record ID

portalLinkId
required
string

Portal link ID

Response

Response
{
  "data": {
    "status": "revoked"
  }
}

Business Intake

Create intake records for clients, vendors, partners, suppliers, consultants, agencies, contractors, and other business relationships with type-specific documents, approvals, tasks, team assignments, portal links, and encrypted vault fields.

Apps Platform
GET
/api/v1/business-intake

List Business Intakes

Lists Business Intake records with checklist readiness, task counts, approval count, team count, portal count, and vault summary counts.

Query Parameters

status
string

Filter by status, for example pending_review or approved

limit
number

Maximum records to return (max: 200)

Response

Response
{
  "data": [
    {
      "record": {
        "id": "rec_abc123",
        "title": "Acme Catering",
        "status": "pending_review",
        "metadata": { "intakeType": "vendor" },
        "relatedParty": {
          "name": "Sam Lee",
          "email": "sam@example.com",
          "company": "Acme Catering"
        }
      },
      "checklistSummary": {
        "requiredCount": 4,
        "approvedRequired": 3,
        "missingRequired": 1,
        "completionPercent": 75
      },
      "pendingApprovalCount": 1,
      "vaultItemCount": 2
    }
  ]
}
POST
/api/v1/business-intake

Create Business Intake

Creates a Business Intake record. Set intakeType to client, vendor, partner, supplier, consultant, agency, contractor, or other.

Request Body

Business intake fields

Request
{
  "title": "Acme Catering",
  "intakeType": "vendor",
  "contactName": "Sam Lee",
  "contactEmail": "sam@example.com",
  "companyName": "Acme Catering",
  "serviceCategory": "Catering",
  "taxClassification": "LLC",
  "paymentTerms": "Net 30",
  "riskLevel": "standard",
  "targetStartDate": "2026-05-15"
}

Response

Response
{
  "data": {
    "id": "rec_abc123"
  }
}
GET
/api/v1/business-intake/:intakeId

Get Business Intake

Returns the intake record, required document checklist, documents, tasks, approvals, team members, portal links, vault summaries, action register entries, and audit activity.

Path Parameters

intakeId
required
string

Business Intake record ID

Response

Response
{
  "data": {
    "record": { "id": "rec_abc123", "title": "Acme Catering", "status": "pending_review" },
    "checklistSummary": { "completionPercent": 75 },
    "checklist": [...],
    "documents": [...],
    "actions": [...],
    "approvals": [...],
    "members": [...],
    "vaultItems": [
      { "fieldKey": "bank_account", "label": "Bank account", "redactedPreview": "****1234" }
    ]
  }
}
POST
/api/v1/business-intake/:intakeId/documents

Attach Business Intake Document

Uploads a base64-encoded document to an intake checklist item.

Path Parameters

intakeId
required
string

Business Intake record ID

Request Body

Document upload payload

Request
{
  "requirementKey": "tax_form",
  "status": "pending_review",
  "accessLevel": "finance",
  "isSensitive": true,
  "document": {
    "filename": "acme-w9.pdf",
    "contentType": "application/pdf",
    "data": "base64..."
  }
}

Response

Response
{
  "data": {
    "id": "doc_abc123"
  }
}
POST
/api/v1/business-intake/:intakeId/tasks

Create Business Intake Task

Creates an intake follow-up, onboarding, review, or setup task.

Request Body

Task payload

Request
{
  "title": "Verify payment details",
  "description": "Confirm remittance details with finance",
  "dueDate": 1778803200000
}

Response

Response
{
  "data": {
    "id": "appr_abc123"
  }
}
POST
/api/v1/business-intake/:intakeId/approvals

Request Business Intake Approval

Creates an internal approval request for intake review.

Request Body

Approval request

Request
{
  "title": "Finance approval",
  "mode": "sequential",
  "approvers": [
    { "approverEmail": "finance@example.com", "stepNumber": 1 }
  ]
}

Response

Response
{
  "data": {
    "id": "appr_abc123"
  }
}
POST
/api/v1/business-intake/:intakeId/team

Assign Business Intake Team Member

Assigns an existing workspace member to the intake record.

Request Body

Team assignment

Request
{
  "userId": "user_abc123",
  "role": "contributor"
}

Response

Response
{
  "data": {
    "id": "member_abc123"
  }
}
POST
/api/v1/business-intake/:intakeId/portal-links

Create Business Intake Portal Link

Creates a public intake link for document collection and optional email/SMS notification.

Request Body

Portal link payload

Request
{
  "recipientName": "Sam Lee",
  "recipientEmail": "sam@example.com",
  "recipientPhone": "+15551234567",
  "notificationChannels": ["email", "sms"]
}

Response

Response
{
  "data": {
    "id": "portal_abc123"
  }
}
POST
/api/v1/business-intake/:intakeId/vault

Set Business Intake Vault Field

Creates or updates an encrypted intake vault field. The API returns the vault item ID, not the plaintext value.

Request Body

Encrypted field payload

Request
{
  "fieldKey": "bank_account",
  "label": "Bank account",
  "value": "1234567890",
  "accessLevel": "finance"
}

Response

Response
{
  "data": {
    "id": "vault_abc123"
  }
}

Hiring Packets

Create hiring packet records, collect offer letters and agreements, track policy acknowledgments, manage onboarding tasks, assign team members, create external portal links, request approvals, and store restricted values in the encrypted vault.

Apps Platform
GET
/api/v1/hiring-packets

List Hiring Packets

Lists Hiring Packet records with checklist readiness, approval count, open task count, team count, and vault summary counts.

Query Parameters

status
string

Filter by status, for example offer_sent or cleared_to_start

limit
number

Maximum records to return (max: 200)

Response

Response
{
  "data": [
    {
      "packet": { "id": "rec_abc123", "title": "Avery Johnson", "status": "offer_sent" },
      "checklistSummary": { "requiredCount": 3, "approvedRequired": 1, "completionPercent": 33 },
      "openTaskCount": 2,
      "teamMemberCount": 1,
      "vaultItemCount": 0
    }
  ]
}
POST
/api/v1/hiring-packets

Create Hiring Packet

Creates a Hiring Packet record with candidate, role, worker type, start date, manager, and compensation metadata.

Request Body

Hiring packet fields

Request
{
  "candidateName": "Avery Johnson",
  "candidateEmail": "avery@example.com",
  "candidatePhone": "+2348012345678",
  "smsAlerts": true,
  "roleTitle": "Operations Manager",
  "department": "Operations",
  "workerType": "employee",
  "startDate": "2026-05-15"
}

Response

Response
{
  "data": {
    "id": "rec_abc123"
  }
}
POST
/api/v1/hiring-packets/:packetId/tasks

Create Hiring Packet Task

Creates an onboarding task and emits generic app action events plus Hiring Packet task events.

Request Body

Task fields

Request
{
  "title": "Provision laptop",
  "dueDate": 1770000000000
}

Response

Response
{
  "data": {
    "id": "action_abc123"
  }
}
POST
/api/v1/hiring-packets/:packetId/portal-links

Create Hiring Packet Portal Link

Creates a public intake link for the candidate or contractor to submit details and checklist documents.

Request Body

Portal link fields

Request
{
  "recipientName": "Avery Johnson",
  "recipientEmail": "avery@example.com",
  "notificationChannels": ["sms"],
  "label": "Candidate document collection"
}

Response

Response
{
  "data": {
    "id": "link_abc123",
    "url": "https://wegosign.com/intake/token"
  }
}

Renewals & Compliance

Track contracts, permits, insurance certificates, training credentials, policy acknowledgments, regulatory filings, custom compliance items, required evidence, approvals, tasks, teams, portal submissions, and encrypted vault fields.

Apps Platform
GET
/api/v1/renewals-compliance

List Compliance Items

Lists Renewals & Compliance records with checklist readiness, approval count, open task count, team count, and vault summary counts.

Query Parameters

status
string

Filter by status, for example pending_documents, compliant, expiring_soon, or expired

limit
number

Maximum records to return (max: 200)

Response

Response
{
  "data": [
    {
      "item": { "id": "rec_abc123", "title": "General Liability COI", "status": "expiring_soon" },
      "checklistSummary": { "requiredCount": 3, "approvedRequired": 2, "completionPercent": 67 },
      "openTaskCount": 1,
      "teamMemberCount": 1,
      "vaultItemCount": 0
    }
  ]
}
POST
/api/v1/renewals-compliance

Create Compliance Item

Creates a configurable renewal or compliance item. The tracking type determines the default document and evidence checklist.

Request Body

Compliance item fields

Request
{
  "title": "General Liability COI",
  "trackingType": "insurance_coi",
  "relatedPartyName": "Northstar Logistics",
  "issuingAuthority": "Carrier Mutual",
  "expirationDate": "2026-08-01",
  "renewalDueDate": "2026-07-15",
  "policyNumber": "COI-2026-1001"
}

Response

Response
{
  "data": {
    "id": "rec_abc123"
  }
}
POST
/api/v1/renewals-compliance/:itemId/documents

Attach Compliance Evidence

Attaches a base64-encoded required document or supporting evidence file to a compliance item.

Request Body

Document upload fields

Request
{
  "requirementKey": "certificate_of_insurance",
  "label": "Current COI",
  "document": {
    "filename": "coi.pdf",
    "contentType": "application/pdf",
    "data": "base64..."
  }
}

Response

Response
{
  "data": {
    "id": "doc_abc123"
  }
}
POST
/api/v1/renewals-compliance/:itemId/tasks

Create Compliance Task

Creates a renewal reminder, follow-up, filing, inspection, or review task.

Request Body

Task fields

Request
{
  "title": "Request renewed COI",
  "dueDate": 1784073600000
}

Response

Response
{
  "data": {
    "id": "action_abc123"
  }
}

Webhooks

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

Growth Plan & Above
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",
    "document.downloaded"
  ],
  "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

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
    }
  ]
}
GET
/api/v1/webhooks/:id

Get Webhook

Retrieves a specific webhook by its ID.

Path Parameters

id
required
string

The webhook ID

Response

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

Response
{
  "data": {
    "id": "whk_abc123",
    "deleted": true
  }
}
Model Context Protocol (MCP)

Connect WeGoSign to AI assistants and agent clients through the hosted MCP endpoint or local stdio server

Overview

WeGoSign exposes the same REST API workflows through MCP tools, resources, and prompts. Hosted MCP clients can connect to /api/mcp with a WeGoSign API key, and local clients can run the standalone MCP server package.

Signing Workflows

Send template or package envelopes, track signers, remind, cancel, and download

Template Packages

List, create, update, archive, and send multi-document packages

Business Automation

Manage webhooks, invoices, bulk sends, and SSO status from agent clients

Hosted MCP server info
{
  "endpoint": "https://wegosign.com/api/mcp",
  "transport": "Streamable HTTP",
  "authentication": "Authorization: Bearer wgs_live_...",
  "toolCount": 30,
  "resourceCount": 7,
  "promptCount": 4
}

MCP Tools

MCP tools map to authenticated /api/v1 operations. The send-envelope tool accepts exactly one oftemplateId or packageId.

CategoryTools
Envelopeslist-envelopes, get-envelope, send-envelope, cancel-envelope, send-reminder, download-envelope, get-envelope-audit-log, get-envelope-signers
Templateslist-templates, get-template, get-template-fields, create-template, update-template, archive-template, update-template-fields
Template Packageslist-packages, get-package, create-package, update-package, archive-package
Bulk Sendscreate-bulk-send, get-bulk-send, get-bulk-send-errors
Invoiceslist-invoices, create-invoice, get-invoice, send-invoice, record-payment, void-invoice
Event Ledgerlist-event-ledger-events, get-event-ledger-event, create-event-ledger-event, update-event-ledger-event, create-event-ledger-sponsor, create-event-ledger-expense, import-meetumo-event-ledger
Generic Business Appslist-business-records, get-business-record, create-business-record, update-business-record-status, list-business-record-documents, attach-business-record-document, list-business-record-approvals, request-business-record-approval, create-business-record-portal-link
Business Intakelist-business-intakes, get-business-intake, create-business-intake, update-business-intake-status, attach-business-intake-document, review-business-intake-document, create-business-intake-task, update-business-intake-task, request-business-intake-approval, assign-business-intake-team-member, create-business-intake-portal-link, set-business-intake-vault-field
Hiring Packetslist-hiring-packets, get-hiring-packet, create-hiring-packet, update-hiring-packet-status, attach-hiring-packet-document, review-hiring-packet-document, create-hiring-packet-task, update-hiring-packet-task, request-hiring-packet-approval, assign-hiring-packet-team-member, create-hiring-packet-portal-link, set-hiring-packet-vault-field
Renewals & Compliancelist-renewal-compliance-items, get-renewal-compliance-item, create-renewal-compliance-item, update-renewal-compliance-status, attach-renewal-compliance-document, review-renewal-compliance-document, create-renewal-compliance-task, update-renewal-compliance-task, request-renewal-compliance-approval, assign-renewal-compliance-team-member, create-renewal-compliance-portal-link, set-renewal-compliance-vault-field
Webhooks & SSOlist-webhooks, get-webhook, create-webhook, delete-webhook, get-sso-config

Resources & Prompts

Resources

wegosign://organization/stats, wegosign://templates,wegosign://packages, wegosign://webhooks,wegosign://sso/config, wegosign://envelopes/{envelopeId}/audit,wegosign://invoices, wegosign://event-ledger,wegosign://business-intake,wegosign://hiring-packets, and wegosign://renewals-compliance.

Prompts

send-for-signature, send-package-for-signature,check-pending, and weekly-report.

Guides

Best practices and implementation guides

Document Signing Flow

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

1

Create Template

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

2

Create & Send Envelope

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

3

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.

4

Signer Completes Signing

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

5

Document Completed

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

Basic Field Types

signature

Full signature - draw, type, or upload

initials

Quick initials field

sender_signature

Sender pre-signs before sending

date

Auto-filled date field

text

Free-form text input

checkbox

Checkbox for acknowledgments

Advanced Field Types

email

Email address with validation

phone

Phone number with country code

number

Numeric input with min/max validation

dropdown

Single-select dropdown menu

radio_group

Radio buttons - select one option

multi_select

Checkboxes - select multiple options

date_picker

Calendar date picker for custom dates

Conditional Field Logic

Show, hide, or require fields based on other field values. Configure conditions in the template editor.

Supported Operators:

• equals - Value matches exactly
• not_equals - Value does not match
• contains - Value contains text
• not_contains - Value does not contain text
• is_empty - Field is empty
• is_not_empty - Field has a value
• greater_than / less_than - Numeric comparison

Actions:

• Show - Display field when conditions are met
• Hide - Hide field when conditions are met
• Require - Make field required when conditions are met

Sequential Signing

Control the order in which signers must sign documents. Sequential signing ensures that signers can only access and sign the document when it's their turn.

How It Works

1. Assign a signingOrder number to each signer (1 = first)

2. Signers with lower numbers must complete before higher numbers can access the document

3. Signers attempting to access out of order receive a "not your turn" message

API Example

Sequential signing request
{
  "templateId": "template_abc123",
  "signers": [
    { "name": "Manager", "email": "manager@company.com", "signingOrder": 1 },
    { "name": "Director", "email": "director@company.com", "signingOrder": 2 },
    { "name": "CEO", "email": "ceo@company.com", "signingOrder": 3 }
  ]
}

Parallel Signing

For parallel signing where all signers can sign simultaneously, assign the samesigningOrder to all signers or omit it entirely.

Template Packages

Template packages allow you to bundle multiple templates together for complex multi-document signing workflows. Signers receive all documents in a single signing session.

Key Features

Multi-Document Bundles

Combine multiple templates into a single package

Unified Role Mapping

Map package roles to template-specific roles

Single Signing Session

Signers complete all documents in one session

Consistent Experience

Same signer sees their fields across all docs

Dashboard and API

Template packages can be managed in the dashboard or through the/api/v1/packages endpoints. MCP clients can use list-packages,create-package, andsend-envelope withpackageId to send a multi-document package.

Scheduled Sends

Schedule envelopes to be sent at a future date and time. Perfect for time-sensitive documents or coordinating across time zones.

API Example

Scheduled envelope request
{
  "templateId": "template_abc123",
  "signers": [
    { "name": "John Doe", "email": "john@example.com" }
  ],
  "scheduledAt": "2024-12-15T09:00:00Z"
}

Constraints

• Minimum: Must be at least 5 minutes in the future

• Maximum: Cannot be more than 30 days in the future

• Format: ISO 8601 timestamp (e.g., 2024-12-15T09:00:00Z)

Bulk Send Scheduling

Bulk sends also support scheduling. Include scheduledAtin your bulk send request to schedule mass document delivery.

CC Recipients

Add CC (carbon copy) recipients to receive copies of the envelope without needing to sign. They're notified when the envelope is sent and completed.

API Example

Envelope with CC recipients
{
  "templateId": "template_abc123",
  "signers": [
    { "name": "John Doe", "email": "john@example.com" }
  ],
  "ccRecipients": [
    { "name": "Legal Team", "email": "legal@company.com" },
    { "name": "HR Manager", "email": "hr@company.com" }
  ]
}

CC vs Signers

FeatureSignersCC Recipients
Can sign document✓—
Notified when sent✓✓
Notified when completed✓✓
Receives signed document✓✓

Password Protection

Add an extra layer of security by requiring signers to enter a password before viewing and signing documents. Available on all plans.

Key Features

Per-Signer Passwords

Each signer has their own unique password

Auto-Generated

8-character alphanumeric passwords by default

Multi-Channel Delivery

Deliver via Email, SMS, or WhatsApp

Lockout Protection

Account locked after 5 failed attempts

Security Flow

1. Sender enables password protection for a signer

2. Password is auto-generated (or custom-set) and delivered via chosen channel

3. Signer must enter correct password before viewing the document

4. After 5 failed attempts, access is locked until sender resends password

Dashboard Only

Password protection is currently configured through the dashboard when creating envelopes. API support for password-protected envelopes is planned for a future release.

Invoicing Guide

WeGoSign's invoicing API lets you create, send, and track client invoices programmatically. This guide walks through common invoicing workflows.

1. Create and Send an Invoice

Invoices are created in draft status. You must explicitly send them to deliver the email to the client.

// Step 1: Create a draft invoice
const invoice = await fetch("https://wegosign.com/api/v1/invoices", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    clientName: "John Smith",
    clientEmail: "john@example.com",
    title: "Consulting Services - April 2026",
    currency: "NGN",
    lineItems: [
      { description: "Strategy session (2hrs)", quantity: 2, unitPriceKobo: 500000, totalKobo: 1000000 }
    ],
    subtotalKobo: 1000000,
    totalKobo: 1000000,
    invoiceDate: Date.now(),
    dueDate: Date.now() + 30 * 24 * 60 * 60 * 1000
  })
});
const { data } = await invoice.json();

// Step 2: Send it
await fetch(`https://wegosign.com/api/v1/invoices/${data.id}/send`, {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});

2. Record Payments

Record partial or full payments. The invoice status updates automatically: partial payments set it to partially_paid, and when the total is reached it becomes paid.

// Record a partial payment
const result = await fetch(`https://wegosign.com/api/v1/invoices/${invoiceId}/payments`, {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amountKobo: 500000,
    paymentMethod: "bank_transfer",
    reference: "TXN-12345"
  })
});
// { "data": { "success": true, "status": "partially_paid" } }

// Record remaining payment
await fetch(`https://wegosign.com/api/v1/invoices/${invoiceId}/payments`, {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amountKobo: 500000,
    paymentMethod: "bank_transfer",
    reference: "TXN-12346"
  })
});
// { "data": { "success": true, "status": "paid" } }
// Client receives a receipt email automatically

3. Listen for Invoice Events

Subscribe to invoice webhook events to automate your billing workflow. The invoice.viewed event fires every time the client opens the invoice page — useful for tracking engagement.

// Create a webhook for invoice events
await fetch("https://wegosign.com/api/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://yourapp.com/webhooks/invoices",
    events: [
      "invoice.sent",
      "invoice.viewed",
      "invoice.payment_recorded",
      "invoice.paid",
      "invoice.overdue",
      "invoice.reminder_sent"
    ],
    description: "Invoice lifecycle tracking"
  })
});

// Example webhook payload for invoice.payment_recorded:
// {
//   "type": "invoice.payment_recorded",
//   "data": {
//     "invoice_id": "inv_abc123",
//     "invoice_number": "INV-0001",
//     "client_email": "john@example.com",
//     "amount_kobo": 500000,
//     "total_paid_kobo": 500000,
//     "total_kobo": 1000000,
//     "currency": "NGN",
//     "payment_method": "bank_transfer",
//     "status": "partially_paid"
//   }
// }

Invoice Webhook Events Reference

EventWhenFrequency
invoice.createdInvoice created as draftOnce
invoice.sentInvoice email sent to clientOnce
invoice.viewedClient opens the invoice pageEvery view
invoice.payment_recordedA payment is recordedEvery payment
invoice.paidInvoice fully paidOnce
invoice.overdueInvoice passes due dateOnce
invoice.reminder_sentOverdue reminder email sentEach reminder
invoice.voidedInvoice voided/cancelledOnce

Webhook Events

WeGoSign sends webhook notifications for the following events:

Envelope Events

envelope.created

An envelope has been created

envelope.sent

An envelope has been sent to signers

envelope.viewed

Any signer has viewed the document

envelope.signed

Any signer has completed their signature

envelope.completed

All signers have completed signing

envelope.declined

Any signer has declined to sign

envelope.cancelled

An envelope has been cancelled

envelope.expired

An envelope has expired without completion

Signer Events

signer.viewed

A specific signer has viewed the document

signer.signed

A specific signer has completed signing

signer.declined

A specific signer has declined to sign

Reminder Events

reminder.sent

A reminder email was sent to a signer (automatic or manual)

Document Events

document.downloaded

A signed document has been downloaded

Invoice Events

invoice.created

A new client invoice has been created

invoice.sent

An invoice has been sent to the client via email

invoice.viewed

The client opened the invoice page (fires on every view)

invoice.payment_recorded

A payment was recorded (including partial payments)

invoice.paid

An invoice has been fully paid

invoice.overdue

An invoice has passed its due date

invoice.reminder_sent

An overdue reminder email was sent to the client

invoice.voided

An invoice has been voided

Generic App Events

app.record.created

A business app record has been created

app.record.status_changed

A business app record status has changed

app.document.attached

A document was attached to a business app record

app.document.reviewed

A business app document was approved, rejected, expired, or sent for revision

app.approval.completed

A business app approval request was approved

app.approval.step_decided

A business app approval step was approved or rejected

app.portal.link_created

An external intake portal link was created for a business app record

app.portal.submitted

An external recipient submitted fields or documents through the intake portal

app.action.created

A business app action or task was created

app.action.completed

A business app action or task was completed

Business Intake Events

business_intake.record.created

A business intake record has been created

business_intake.record.status_changed

A business intake status has changed

business_intake.document.attached

A required intake document or evidence file was attached

business_intake.document.reviewed

A business intake document was approved, rejected, expired, or sent for revision

business_intake.task.completed

A business intake task was completed

business_intake.approval.completed

A business intake approval request was approved

business_intake.payment_details.updated

Encrypted payment details changed

business_intake.team.assigned

A team member was assigned to a business intake record

business_intake.vault.updated

An encrypted business intake vault field changed

business_intake.portal.submitted

A recipient submitted details or documents through an intake portal link

Hiring Packets Events

hiring_packets.packet.created

A hiring packet has been created

hiring_packets.packet.status_changed

A hiring packet status has changed

hiring_packets.document.attached

An offer letter, contractor agreement, policy acknowledgment, or onboarding file was attached

hiring_packets.task.created

An onboarding task was created for a hiring packet

hiring_packets.task.completed

An onboarding task was completed for a hiring packet

hiring_packets.team.assigned

A team member was assigned to a hiring packet

hiring_packets.approval.completed

A hiring packet approval request was approved

hiring_packets.vault.updated

An encrypted hiring packet vault field changed

hiring_packets.portal.submitted

A candidate or contractor submitted details or documents through an intake portal link

Renewals & Compliance Events

renewals_compliance.item.created

A renewal or compliance item has been created

renewals_compliance.item.status_changed

A compliance item status has changed

renewals_compliance.document.attached

A required compliance document or evidence file was attached

renewals_compliance.document.reviewed

A compliance document was approved, rejected, expired, or sent for revision

renewals_compliance.task.completed

A compliance task or renewal reminder was completed

renewals_compliance.approval.completed

A compliance approval request was approved

renewals_compliance.vault.updated

An encrypted compliance vault field changed

renewals_compliance.portal.submitted

An external party submitted details or evidence through an intake portal link

Bulk Send Events

bulk_send.started

A bulk send job has started processing

bulk_send.completed

A bulk send job has finished successfully

bulk_send.failed

A bulk send job has failed

Webhook Payload Structure

Example Webhook Payload (signer.signed event)
{
  "id": "evt_abc123xyz",
  "type": "signer.signed",
  "created": 1704543600000,
  "data": {
    "envelope": {
      "id": "env_xyz789",
      "title": "Employment Contract - John Doe",
      "status": "signed",
      "createdAt": 1704543600000,
      "completedAt": null
    },
    "signer": {
      "id": "sgn_abc123",
      "email": "john@example.com",
      "name": "John Doe",
      "role": "employee",
      "status": "signed",
      "viewedAt": 1704543500000,
      "signedAt": 1704543600000,
      "declinedAt": null,
      "declineReason": null,
      "completedFields": [
        {
          "fieldId": "field_signature_1",
          "value": "data:image/png;base64,iVBORw0KGgoAAA...",
          "completedAt": 1704543590000
        },
        {
          "fieldId": "field_email_1",
          "value": "john.doe@example.com",
          "completedAt": 1704543580000
        },
        {
          "fieldId": "field_dropdown_1",
          "value": "Full-Time",
          "completedAt": 1704543570000
        }
      ]
    },
    "timestamp": 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  // Access payload fields: id, type, created, data
39  const { id, type, created, data } = req.body;
40  console.log('Processing event:', type, 'Event ID:', id);
41
42  // Process the webhook based on event type...
43  res.status(200).send('OK');
44});

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

Ready to get started?

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

Contact Support