📦Request Model

Understanding the CompositeRequest structure is essential for working with Docs-Dispatcher. This guide explains required and optional fields, service-specific parameters, and common request patterns.

CompositeRequest Structure

All Dispatcher API endpoints accept a CompositeRequest JSON object with this general structure:

{
  "providerName": "string (optional)",
  "template": {
    "id": "number (required)",
    "data": "object (required)"
  },
  "metadata": "object (optional)",

  // Service-specific fields
  "invoicing": {...},
  "esign": {...},
  "email": {...},
  "sms": {...},
  "postal": {...}
}

Core Fields

These fields are common across all services.

providerName (optional)

Explicitly specify which provider to use for the service.

{
  "providerName": "qonto"
}

Type: string

When to use:

Override company/user default configuration
Multi-provider scenarios (different regions, A/B testing)
One-off provider usage

When to omit:

Use company default provider
Use user override provider
Configuration already specifies provider

Valid values: See Provider Configurations

Example:

# Use explicit provider (overrides defaults)
curl -X POST https://api.docs-dispatcher.io/api/invoicing \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "providerName": "pennylane",
    "documentType": "INVOICE",
    "template": {...}
  }'

template (required)

Specifies which template to use and the data to populate it with.

{
  "template": {
    "id": 123,
    "data": {
      "customerName": "Acme Corp",
      "amount": 1500.00
    }
  }
}

Type: object

Fields:

id (number, required) - Template ID from Templater
data (object, required) - Template variables as JSON

How to get template ID:

Create template in Templater UI
Or via Dispatcher API: GET /api/v1/templates
Use template ID in dispatch requests

Data schema:

Schema is defined per template
Use validation endpoint to verify schema compliance
See template preview for expected fields

Example:

// Node.js - Invoice template
{
  template: {
    id: 123,
    data: {
      invoiceNumber: 'INV-2026-001',
      date: '2026-02-13',
      customer: {
        name: 'Acme Corp',
        email: '[email protected]',
        address: '123 Main St, Paris'
      },
      items: [
        {
          description: 'Web Development',
          quantity: 10,
          unitPrice: 150.00,
          total: 1500.00
        }
      ],
      subtotal: 1500.00,
      taxRate: 0.20,
      taxAmount: 300.00,
      total: 1800.00
    }
  }
}

Webhook URL to receive status updates (async mode) or completion notifications.

{
}

Type: string (URL)

When to use:

Async mode (?async=true)
eSign workflows (signature status updates)
Postal tracking updates
Long-running operations

Requirements:

Must be HTTPS (HTTP not supported)
Must return 200 OK within 10 seconds
Should handle duplicate events (idempotency)

Webhook payload:

{
  "event": "dispatch_completed",
  "dispatchId": "disp_abc123",
  "service": "invoicing",
  "status": "success",
  "timestamp": "2026-02-13T12:30:00Z",
  "data": {
    // Service-specific response data
  }
}

Example:

curl -X POST https://api.docs-dispatcher.io/api/invoicing?async=true \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "providerName": "qonto",
    "documentType": "INVOICE",
    "template": {...},
  }'

metadata (optional)

Custom key-value data for tracking and reference.

{
  "metadata": {
    "orderId": "ORD-2026-12345",
    "customerId": "CUST-789",
    "source": "web",
    "campaign": "winter-2026"
  }
}

Type: object

Purpose:

Track dispatch origin
Link to external system records
Add custom business context
Filter/search dispatches later

Limitations:

Max 20 key-value pairs
Keys: max 50 characters
Values: max 500 characters
No nested objects

Returned in response:

{
  "success": true,
  "dispatchId": "disp_abc123",
  "metadata": {
    "orderId": "ORD-2026-12345",
    "customerId": "CUST-789"
  }
}

Service-Specific Fields

Different services require different fields.

Invoicing

{
  "providerName": "qonto",
  "documentType": "INVOICE",
  "template": {
    "id": 123,
    "data": {...}
  },
  "invoicing": {
    "dueDate": "2026-03-13",
    "paymentTerms": "Net 30",
    "customerId": "qonto_customer_123"
  }
}

Required fields:

documentType - One of: INVOICE, E_INVOICE, QUOTE, CREDIT

Optional fields:

invoicing.dueDate - Payment due date (ISO 8601)
invoicing.paymentTerms - Payment terms description
invoicing.customerId - Provider's customer ID
invoicing.reference - External reference number

Example:

// Node.js
const request = {
  providerName: 'qonto',
  documentType: 'INVOICE',
  template: {
    id: 123,
    data: {
      invoiceNumber: 'INV-2026-001',
      customer: {
        name: 'Acme Corp',
        email: '[email protected]'
      },
      items: [
        {description: 'Service', quantity: 1, unitPrice: 1000}
      ],
      total: 1000.00
    }
  },
  invoicing: {
    dueDate: '2026-03-13',
    paymentTerms: 'Net 30'
  }
};

eSign

{
  "providerName": "universign",
  "template": {
    "id": 456,
    "data": {...}
  },
  "signers": [
    {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "order": 1
    }
  ],
  "esign": {
    "signatureType": "ADVANCED",
    "expiresInDays": 30
  },
}

Required fields:

signers - Array of signer objects

Signer object:

email (required) - Signer's email address
firstName (required) - First name
lastName (required) - Last name
order (optional) - Signing order (sequential workflow)

Optional fields:

esign.signatureType - SIMPLE, ADVANCED, QUALIFIED
esign.expiresInDays - Transaction expiry (default: 30)
esign.locale - Language code (e.g., fr, en)

Example:

// PHP
$request = [
    'providerName' => 'universign',
    'template' => [
        'id' => 456,
        'data' => [
            'contractTitle' => 'Employment Agreement',
            'employeeName' => 'John Doe'
        ]
    ],
    'signers' => [
        [
            'email' => '[email protected]',
            'firstName' => 'John',
            'lastName' => 'Doe',
            'order' => 1
        ],
        [
            'email' => '[email protected]',
            'firstName' => 'Jane',
            'lastName' => 'Smith',
            'order' => 2
        ]
    ],
    'esign' => [
        'signatureType' => 'ADVANCED',
        'expiresInDays' => 30
    ],
];

Email

{
  "template": {
    "id": 123,
    "data": {...}
  },
  "email": {
    "to": "[email protected]",
    "cc": ["[email protected]"],
    "subject": "Your Invoice",
    "body": "Please find attached your invoice.",
    "attachGenerated": true
  }
}

Required fields:

email.to - Recipient email (string or array)
email.subject - Email subject

Optional fields:

email.body - Email body (HTML or plain text)
email.cc - CC recipients (array)
email.bcc - BCC recipients (array)
email.attachGenerated - Attach generated document (default: true)
email.replyTo - Reply-to address

Example:

// Java
Map<String, Object> request = new HashMap<>();
request.put("template", Map.of(
    "id", 123,
    "data", Map.of("invoiceNumber", "INV-2026-001")
));
request.put("email", Map.of(
    "to", "[email protected]",
    "cc", List.of("[email protected]"),
    "subject", "Your Invoice INV-2026-001",
    "body", "<p>Thank you for your business.</p>",
    "attachGenerated", true
));

SMS

{
  "providerName": "brevo",
  "sms": {
    "phoneNumber": "+33612345678",
    "message": "Your order has shipped. Track: https://track.example.com/1234",
    "sender": "Acme"
  }
}

Required fields:

sms.phoneNumber - Recipient phone (E.164 format: +33612345678)
sms.message - SMS content

Optional fields:

sms.sender - Sender ID (11 chars max, alphanumeric)

Limits:

Message: 160 chars (standard), 1530 chars (concatenated)
Phone: Must include country code (+33, +1, etc.)

Example:

# curl
curl -X POST https://api.docs-dispatcher.io/api/sms \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "providerName": "brevo",
    "sms": {
      "phoneNumber": "+33612345678",
      "message": "Your appointment is tomorrow at 10am.",
      "sender": "Clinic"
    }
  }'

Postal

{
  "providerName": "mysendingbox",
  "template": {
    "id": 789,
    "data": {...}
  },
  "postal": {
    "mailType": "REGISTERED",
    "recipient": {
      "name": "John Doe",
      "company": "Acme Corp",
      "address": "123 Main St",
      "city": "Paris",
      "postalCode": "75001",
      "country": "FR"
    }
  },
}

Required fields:

postal.recipient - Recipient address object
postal.recipient.name - Recipient name
postal.recipient.address - Street address
postal.recipient.city - City
postal.recipient.postalCode - Postal/ZIP code
postal.recipient.country - Country code (ISO 3166-1 alpha-2)

Optional fields:

postal.mailType - SIMPLE, REGISTERED (default: SIMPLE)
postal.recipient.company - Company name
postal.color - Print in color (default: false)
postal.duplex - Double-sided printing (default: false)

Example:

// Node.js
const request = {
  providerName: 'mysendingbox',
  template: {
    id: 789,
    data: {
      documentTitle: 'Contract Amendment',
      recipientName: 'John Doe'
    }
  },
  postal: {
    mailType: 'REGISTERED',
    recipient: {
      name: 'John Doe',
      company: 'Acme Corp',
      address: '123 Main St',
      city: 'Paris',
      postalCode: '75001',
      country: 'FR'
    },
    color: false,
    duplex: true
  },
};

File

{
  "template": {
    "id": 123,
    "data": {...}
  },
  "file": {
    "outputFormat": "PDF",
    "filename": "annual-report-2025.pdf"
  }
}

Optional fields:

file.outputFormat - PDF, DOCX, XLSX (default: PDF)
file.filename - Custom filename for download

Example:

// PHP
$request = [
    'template' => [
        'id' => 123,
        'data' => [
            'title' => 'Annual Report 2025',
            'content' => '...'
        ]
    ],
    'file' => [
        'outputFormat' => 'PDF',
        'filename' => 'annual-report-2025.pdf'
    ]
];

Upload

Upload uses multipart/form-data instead of JSON.

curl -X POST https://api.docs-dispatcher.io/api/upload \
  -H "Authorization: Bearer $JWT" \
  -F "file=@/path/to/document.pdf" \
  -F "metadata={\"category\":\"invoices\",\"year\":2026}"

Required fields:

file - File to upload (multipart field)

Optional fields:

metadata - JSON string with custom metadata

Composite Requests (Service Chaining)

Chain multiple services in a single request:

POST /api/invoicing/email/upload

{
  "providerName": "qonto",
  "documentType": "INVOICE",
  "template": {
    "id": 123,
    "data": {...}
  },
  "email": {
    "to": "[email protected]",
    "subject": "Your Invoice"
  }
}

How it works:

Invoicing service generates invoice
Email service sends generated document
Upload service archives document
Returns combined response

Example response:

{
  "success": true,
  "dispatchId": "disp_composite_abc123",
  "invoicing": {
    "invoiceId": "qonto_inv_789",
    "status": "sent"
  },
  "email": {
    "messageId": "smtp_msg_xyz",
    "sent": true
  },
  "upload": {
    "url": "https://storage.docs-dispatcher.io/archive/INV-2026-001.pdf",
    "size": 245678
  }
}

Common Request Patterns

Pattern 1: Simple Invoice

Generate and send invoice to accounting platform:

{
  "providerName": "qonto",
  "documentType": "INVOICE",
  "template": {
    "id": 123,
    "data": {
      "invoiceNumber": "INV-2026-001",
      "customer": {...},
      "items": [...],
      "total": 1800.00
    }
  }
}

Pattern 2: Invoice with Email

Generate invoice and email to customer:

{
  "providerName": "qonto",
  "documentType": "INVOICE",
  "template": {
    "id": 123,
    "data": {...}
  },
  "email": {
    "to": "[email protected]",
    "subject": "Your Invoice",
    "attachGenerated": true
  }
}

Pattern 3: Async eSign

Send document for signature with webhook notification:

{
  "providerName": "universign",
  "template": {
    "id": 456,
    "data": {...}
  },
  "signers": [
    {
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe"
    }
  ],
}

Pattern 4: Tracked Metadata

Dispatch with custom tracking data:

{
  "providerName": "qonto",
  "documentType": "INVOICE",
  "template": {
    "id": 123,
    "data": {...}
  },
  "metadata": {
    "orderId": "ORD-2026-12345",
    "customerId": "CUST-789",
    "salesRep": "[email protected]"
  }
}

Pattern 5: Document Preview

Generate without external dispatch:

{
  "template": {
    "id": 123,
    "data": {...}
  },
  "file": {
    "outputFormat": "PDF"
  }
}

Field Validation

Required Field Errors

Missing required fields return 400 Bad Request:

{
  "error": "validation_error",
  "message": "Missing required field: template.id",
  "field": "template.id"
}

Invalid Field Errors

Invalid field values return 400 Bad Request:

{
  "error": "validation_error",
  "message": "Invalid document type: RECEIPT. Must be one of: INVOICE, E_INVOICE, QUOTE, CREDIT",
  "field": "documentType"
}

Type Errors

Wrong data types return 400 Bad Request:

{
  "error": "validation_error",
  "message": "Field 'template.id' must be a number, got string",
  "field": "template.id"
}

Request Validation

Test requests before dispatch using validation endpoints:

POST /api/invoicing/validate

Benefits:

Validate structure without external calls
Check required fields
Verify template data schema
No credits charged
Fast feedback (< 100ms)

Example:

curl -X POST https://api.docs-dispatcher.io/api/invoicing/validate \
  -H "Authorization: Bearer $JWT" \
  -d '{
    "providerName": "qonto",
    "documentType": "INVOICE",
    "template": {
      "id": 123,
      "data": {...}
    }
  }'

Success response:

{
  "valid": true,
  "message": "Request is valid and ready for dispatch"
}

Validation error:

{
  "valid": false,
  "errors": [
    {
      "field": "template.data.dueDate",
      "message": "Due date must be after invoice date"
    }
  ]
}

Code Examples

Full Invoice Request (JavaScript)

const dispatchInvoice = async (invoiceData) => {
  const request = {
    providerName: 'qonto',
    documentType: 'INVOICE',
    template: {
      id: 123,
      data: {
        invoiceNumber: invoiceData.number,
        date: new Date().toISOString().split('T')[0],
        customer: {
          name: invoiceData.customer.name,
          email: invoiceData.customer.email,
          address: invoiceData.customer.address
        },
        items: invoiceData.items.map(item => ({
          description: item.description,
          quantity: item.quantity,
          unitPrice: item.unitPrice,
          total: item.quantity * item.unitPrice
        })),
        subtotal: invoiceData.subtotal,
        taxRate: 0.20,
        taxAmount: invoiceData.subtotal * 0.20,
        total: invoiceData.subtotal * 1.20
      }
    },
    invoicing: {
      dueDate: calculateDueDate(30), // 30 days from now
      paymentTerms: 'Net 30'
    },
    metadata: {
      orderId: invoiceData.orderId,
      source: 'web'
    }
  };

  const response = await fetch('https://api.docs-dispatcher.io/api/invoicing', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(request)
  });

  return await response.json();
};

function calculateDueDate(days) {
  const date = new Date();
  date.setDate(date.getDate() + days);
  return date.toISOString().split('T')[0];
}

Full eSign Request (PHP)

<?php
function sendForSignature($contractData) {
    $request = [
        'providerName' => 'universign',
        'template' => [
            'id' => 456,
            'data' => [
                'contractTitle' => $contractData['title'],
                'employeeName' => $contractData['employee']['name'],
                'startDate' => $contractData['startDate'],
                'salary' => $contractData['salary']
            ]
        ],
        'signers' => [
            [
                'email' => $contractData['employee']['email'],
                'firstName' => $contractData['employee']['firstName'],
                'lastName' => $contractData['employee']['lastName'],
                'order' => 1
            ],
            [
                'email' => '[email protected]',
                'firstName' => 'Jane',
                'lastName' => 'Smith',
                'order' => 2
            ]
        ],
        'esign' => [
            'signatureType' => 'ADVANCED',
            'expiresInDays' => 15
        ],
        'metadata' => [
            'contractId' => $contractData['id'],
            'department' => $contractData['department']
        ]
    ];

    $client = new \GuzzleHttp\Client();
    $response = $client->post('https://api.docs-dispatcher.io/api/esign', [
        'headers' => [
            'Authorization' => 'Bearer ' . $_ENV['JWT_TOKEN'],
            'Content-Type' => 'application/json'
        ],
        'json' => $request
    ]);

    return json_decode($response->getBody(), true);
}

Full Postal Request (Java)

import java.util.Map;
import java.util.HashMap;

public class PostalDispatcher {
    public Map<String, Object> sendPostal(Map<String, Object> documentData) throws Exception {
        Map<String, Object> request = new HashMap<>();

        request.put("providerName", "mysendingbox");

        request.put("template", Map.of(
            "id", 789,
            "data", documentData
        ));

        request.put("postal", Map.of(
            "mailType", "REGISTERED",
            "recipient", Map.of(
                "name", documentData.get("recipientName"),
                "company", documentData.get("recipientCompany"),
                "address", documentData.get("address"),
                "city", documentData.get("city"),
                "postalCode", documentData.get("postalCode"),
                "country", documentData.get("country")
            ),
            "color", false,
            "duplex", true
        ));


        request.put("metadata", Map.of(
            "documentId", documentData.get("id"),
            "type", "legal-notice"
        ));

        String requestJson = new ObjectMapper().writeValueAsString(request);

        HttpRequest httpRequest = HttpRequest.newBuilder()
            .uri(URI.create("https://api.docs-dispatcher.io/api/postal"))
            .header("Authorization", "Bearer " + jwtToken)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestJson))
            .build();

        HttpResponse<String> response = client.send(
            httpRequest,
            HttpResponse.BodyHandlers.ofString()
        );

        return new ObjectMapper().readValue(response.body(), Map.class);
    }
}

Provider Configurations - Configure providers
Services Overview - Service-specific details
Validation - Test requests before dispatch
Sync vs Async - Choose execution mode

Summary

The CompositeRequest model provides:

Flexible provider selection - Default, user override, or explicit
Template-based generation - Reusable templates with dynamic data
Service-specific fields - Each service has unique requirements
Custom tracking - Metadata for business context
Service composition - Chain services in single request

Understanding the request model enables you to build powerful, automated document workflows with Docs-Dispatcher.

PreviousUse Basic Auth with Dispatcher NextServices

Last updated 5 days ago

hashtagCompositeRequest Structure

hashtagCore Fields

hashtagproviderName (optional)

hashtagtemplate (required)

hashtagmetadata (optional)

hashtagService-Specific Fields

hashtagInvoicing

hashtageSign

hashtagEmail

hashtagSMS

hashtagPostal

hashtagFile

hashtagUpload

hashtagComposite Requests (Service Chaining)

hashtagCommon Request Patterns

hashtagPattern 1: Simple Invoice

hashtagPattern 2: Invoice with Email

hashtagPattern 3: Async eSign

hashtagPattern 4: Tracked Metadata

hashtagPattern 5: Document Preview

hashtagField Validation

hashtagRequired Field Errors

hashtagInvalid Field Errors

hashtagType Errors

hashtagRequest Validation

hashtagCode Examples

hashtagFull Invoice Request (JavaScript)

hashtagFull eSign Request (PHP)

hashtagFull Postal Request (Java)

hashtagRelated Documentation

hashtagSummary

CompositeRequest Structure

Core Fields

providerName (optional)

template (required)

metadata (optional)

Service-Specific Fields

Invoicing

eSign

Email

SMS

Postal

File

Upload

Composite Requests (Service Chaining)

Common Request Patterns

Pattern 1: Simple Invoice

Pattern 2: Invoice with Email

Pattern 3: Async eSign

Pattern 4: Tracked Metadata

Pattern 5: Document Preview

Field Validation

Required Field Errors

Invalid Field Errors

Type Errors

Request Validation

Code Examples

Full Invoice Request (JavaScript)

Full eSign Request (PHP)

Full Postal Request (Java)

Related Documentation

Summary