> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdoc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Backend Implementation

After the user signs, your backend creates the final PDF using the SuperDoc API.

## Flow

```
Frontend sends → Backend processes → PDF created
    ↓                   ↓                 ↓
Signing data    1. Annotate fields    Stored
                2. Apply signature
```

## Complete example

```javascript Node.js theme={null}
app.post('/api/sign', async (req, res) => {
  try {
    const { eventId, document, auditTrail, documentFields, signerFields, signer } = req.body;

    if (!document?.url) {
      return res.status(400).json({ error: 'document.url is required' });
    }
    
    // 1. Fill document fields
    const annotated = await fetch('https://api.superdoc.dev/v1/annotate?to=pdf', {
      method: 'POST',
      headers: { 
        'Authorization': `Bearer ${process.env.SUPERDOC_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        document: { url: document.url },
        fields: [...documentFields, ...signerFields]
      })
    });
    
    if (!annotated.ok) throw new Error('Annotation failed');
    
    // 2. Apply digital signature
    const annotatedData = await annotated.json();
    const signed = await fetch('https://api.superdoc.dev/v1/sign', {
      method: 'POST', 
      headers: { 
        'Authorization': `Bearer ${process.env.SUPERDOC_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        eventId,
        document: { base64: annotatedData?.document?.base64 },
        auditTrail,
        signer
      })
    });
    
    if (!signed.ok) throw new Error('Signing failed');
    
    // 3. Save signed PDF
    const signedData = await signed.json();
    const signedPdfBase64 = signedData?.document?.base64;
    await saveToS3(Buffer.from(signedPdfBase64, 'base64'), `signed/${eventId}.pdf`);

    // 4. Log for compliance
    await db.signatures.create({
      eventId,
      signerName: signerFields.find(f => f.id === '1')?.value,
      signedAt: new Date(),
      auditTrail: JSON.stringify(auditTrail)
    });
    
    res.json({ success: true, documentId: eventId });
    
  } catch (error) {
    console.error('Signing failed:', error);
    res.status(500).json({ error: 'Failed to sign document' });
  }
});
```

```python Python theme={null}
from flask import Flask, request, jsonify
import requests
import base64
import boto3

app = Flask(__name__)
s3 = boto3.client('s3')

@app.route('/api/sign', methods=['POST'])
def sign():
    try:
        data = request.json

        if not data.get('document', {}).get('url'):
            return jsonify({'error': 'document.url is required'}), 400
        
        # 1. Fill document fields
        annotated = requests.post(
            'https://api.superdoc.dev/v1/annotate?to=pdf',
            headers={'Authorization': f'Bearer {API_KEY}'},
            json={
                'document': {'url': data['document']['url']},
                'fields': data['documentFields'] + data['signerFields']
            }
        )
        
        if annotated.status_code != 200:
            raise Exception('Annotation failed')
        
        # 2. Apply digital signature
        annotated_json = annotated.json()
        signed = requests.post(
            'https://api.superdoc.dev/v1/sign',
            headers={'Authorization': f'Bearer {API_KEY}'},
            json={
                'eventId': data['eventId'],
                'document': {'base64': annotated_json.get('document', {}).get('base64')},
                'auditTrail': data['auditTrail'],
                'signer': data.get('signer')
            }
        )
        
        if signed.status_code != 200:
            raise Exception('Signing failed')
        
        # 3. Save signed PDF
        signed_json = signed.json()
        signed_base64 = signed_json.get('document', {}).get('base64')
        s3.put_object(
            Bucket='signed-documents',
            Key=f"signed/{data['eventId']}.pdf",
            Body=base64.b64decode(signed_base64)
        )
        
        # 4. Log for compliance
        db.signatures.insert({
            'event_id': data['eventId'],
            'signer_name': next((f['value'] for f in data['signerFields'] 
                                if f['id'] == '1'), None),
            'signed_at': datetime.now(),
            'audit_trail': json.dumps(data['auditTrail'])
        })
        
        return jsonify({'success': True, 'documentId': data['eventId']})
        
    except Exception as e:
        print(f'Signing failed: {e}')
        return jsonify({'error': 'Failed to sign document'}), 500
```

## Download/PDF generation

Handle download requests to generate PDFs on-demand:

```javascript Node.js theme={null}
app.post('/api/generate-pdf', async (req, res) => {
  const { documentSource, fields } = req.body;

  if (!documentSource || typeof documentSource !== 'string') {
    return res.status(400).json({ error: 'documentSource URL is required' });
  }

  const result = await fetch('https://api.superdoc.dev/v1/annotate?to=pdf', {
    method: 'POST',
    headers: { 
      'Authorization': `Bearer ${process.env.SUPERDOC_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      document: { url: documentSource },
      fields: [...(fields?.document || []), ...(fields?.signer || [])]
    })
  });
  
  if (!result.ok) throw new Error('PDF generation failed');
  
  // Send PDF back to frontend
  const data = await result.json();
  const pdfBase64 = data?.document?.base64;
  res.type('application/pdf');
  res.send(Buffer.from(pdfBase64, 'base64'));
});
```

```python Python theme={null}
@app.route('/api/generate-pdf', methods=['POST'])
def generate_pdf():
    data = request.json
    
    if not isinstance(data.get('documentSource'), str):
        return jsonify({'error': 'documentSource URL is required'}), 400
    
    result = requests.post(
        'https://api.superdoc.dev/v1/annotate?to=pdf',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json={
            'document': {'url': data['documentSource']},
            'fields': (data.get('fields', {}).get('document', []) +
                       data.get('fields', {}).get('signer', []))
        }
    )
    
    if result.status_code != 200:
        raise Exception('PDF generation failed')
    
    pdf_base64 = result.json().get('document', {}).get('base64')
    return base64.b64decode(pdf_base64), 200, {'Content-Type': 'application/pdf'}
```

## Data structure

The frontend sends the `onSubmit` payload plus a document reference and signer details your backend can access:

```json theme={null}
{
  "eventId": "session-123",
  "document": { "url": "https://example.com/agreement.docx" },
  "signer": {
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "documentFields": [
    { "id": "1", "value": "Jane Smith" }
  ],
  "signerFields": [
    { "id": "1", "value": "Jane Smith" },
    { "id": "2", "value": true }
  ],
  "auditTrail": [
    { "type": "ready", "timestamp": "2024-01-15T10:30:00Z" },
    { "type": "scroll", "timestamp": "2024-01-15T10:30:15Z", 
      "data": { "percent": 100 } },
    { "type": "field_change", "timestamp": "2024-01-15T10:30:30Z",
      "data": { "fieldId": "1", "value": "Jane Smith" } },
    { "type": "submit", "timestamp": "2024-01-15T10:30:45Z" }
  ],
  "timestamp": "2024-01-15T10:30:45Z",
  "duration": 45,
  "isFullyCompleted": true
}
```

### Signer fields

When forwarding this payload to `POST /v1/sign`, only the following `signer` fields are accepted:

| Field | Required | Description |
| - | - | - |
| `name` | yes | Signer's full name (2–255 chars). Rendered on the signature. |
| `email` | yes | Signer's email address (valid email, max 255 chars). |
| `ip` | no | IPv4 address of the signer. Included in the audit trail certificate. |
| `userAgent` | no | Browser user agent string. Included in the audit trail certificate. |

No other properties are accepted on `signer`: the request is rejected with a validation error if extra keys are sent. For application-specific context (tenantId, contractId, etc.), pass a top-level `metadata` object instead.

> [!WARNING]
>
> Do **not** trust `ip` or `userAgent` values from the browser-submitted payload. Derive them server-side from the incoming request (e.g. `req.ip`, `req.headers['user-agent']`) before forwarding to `/v1/sign`, so the audit trail certificate reflects what your server actually observed.

## API reference

* [Authentication](https://docs.superdoc.dev/api-reference/authentication.md) - Get your API key
* [Annotate endpoint](https://docs.superdoc.dev/api-reference/documents/annotate.md) - Fill fields
* [Sign endpoint](https://docs.superdoc.dev/api-reference/signature/sign.md) - Apply signature


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.