Signnow Integration Patterns

Variable/field mapping framework:

Create a mapping configuration that translates external system fields to SignNow template fields:

mapping_config = {
    "template_id": "signnow_template_abc123",
    "field_mappings": [
        { "source": "deal.contact_name",    "target": "signer_name" },
        { "source": "deal.contact_email",   "target": "signer_email" },
        { "source": "deal.company_name",    "target": "company_name_field" },
        { "source": "deal.deal_value",      "target": "contract_amount" },
        { "source": "deal.start_date",      "target": "effective_date" },
    ],
    "signers": [
        { "role": "Signer 1", "email_source": "deal.contact_email" },
        { "role": "Approver", "email_source": "deal.owner_email" },
    ]
}

Prefill API usage:

• Create a document from the template: POST /template/{template_id}/copy
• Prefill fields on the document: PUT /document/{document_id} with field values
• The field name in the API must match the template's field names exactly

Best practices for field mapping:

• Store mappings in configuration (not hardcoded) so they can be updated without code changes
• Validate that all required fields have values before creating the document
• Handle missing or null values gracefully (use defaults or skip optional fields)
• Log mapping results for debugging

Document storage/writeback patterns:

After a document is signed, write the result back to the external system.

Download signed document:

• GET /document/{document_id}/download?type=collapsed — downloads the signed PDF
• The collapsed type flattens all fields into the PDF

Writeback to external system:

• Attach the signed PDF to the external system record (CRM deal, ERP order, DMS folder)
• Update status fields in the external system
• Extract field values from the completed document if needed (e.g., signed date, custom field entries)

Storage options:

• Direct attachment to CRM record (most CRMs support file attachments via API)
• Cloud storage (S3, GCS, Azure Blob) with a reference link in the CRM
• Document management system (SharePoint, Google Drive, Dropbox) with metadata

Webhook-to-system writeback:

SignNow Webhook (document.complete)
├── Parse payload -> extract document_id
├── Look up external system record by document_id (from your mapping store)
├── Download signed PDF from SignNow
├── Extract completed field data if needed
├── Upload PDF to external system record
├── Update external system record status
└── Log completion for audit trail

Implementation pattern:

• Maintain a mapping store: { signnow_document_id -> external_record_id }
• Populate this mapping when you create the signing invite (Step 3)
• When the webhook fires, use the mapping to find the external record
• Process asynchronously — respond to the webhook immediately, then do the writeback in a background job

In-app action framework (branded connectors):

If building a branded connector (e.g., a "Sign with SignNow" button inside a CRM):

• Trigger point: Add a button/action in the external system's UI (most CRMs support custom actions or widgets)
• Action handler: Your backend receives the action, extracts the record data, creates the SignNow document, and returns a signing link
• Signing experience: Redirect the user to the signing link or open it in a modal/iframe
• Completion: Webhook handles writeback; the CRM record updates automatically

This pattern works for any system that supports custom UI actions or webhooks.

Reference documentation:

• API Reference
• Embedded Signing Guide
• Developer Portal