📤Upload Dispatch

Learn how to upload generated documents to storage providers and CRM systems through Docs-Dispatcher.

Overview

This recipe covers:

1. Uploading documents to cloud storage

2. Upload to CRM systems (Zoho CRM)

3. Universal upload provider

4. Combining upload with other services

5. File metadata and organization

What You'll Learn

• Upload documents to various storage providers

• Attach files to CRM records

• Configure upload destinations

• Handle upload responses

• Complete examples in 4 languages

Prerequisites

• Docs-Dispatcher account with JWT

• Upload provider configured (Zoho CRM, Universal, etc.)

• Template created

• Basic REST API knowledge

Upload Service Overview

Supported upload targets:

• ✅ Zoho CRM - Attach to records (Leads, Contacts, Deals, etc.)

• ✅ Universal - Generic file upload to any storage

• ✅ AWS S3 - Amazon S3 buckets

• ✅ Google Drive - Google Drive folders

• ✅ Dropbox - Dropbox folders

Step 1: Authentication

Dispatcher API uses HTTP Basic Authentication. You'll need your Dispatcher account email and password for all API calls.

Setup Credentials

# Store credentials as environment variables
export EMAIL="[email protected]"
export PASSWORD="your-password"

No token management needed! Unlike JWT-based APIs, Basic Auth doesn't require separate authentication endpoints or token refresh. Your credentials are sent with each request.

Quick links:

• Full authentication guide

• Using Basic Auth with Dispatcher

Step 2: Upload to Zoho CRM

Basic Zoho CRM Upload Structure

{
  "providerName": "zohocrm",
  "template": {
    "id": 123,
    "data": {
      "contractNumber": "CONTRACT-2026-001",
      "client": "Acme Corp",
      "amount": 50000.00
    }
  },
  "upload": {
    "module": "Deals",
    "recordId": "4876876000001234567",
    "filename": "contract-2026-001.pdf",
    "attachmentName": "Signed Contract"
  },
  "metadata": {
    "dealId": "DEAL-123",
    "salesRep": "[email protected]"
  }
}

Upload Request

curl -X POST https://api.docs-dispatcher.io/api/upload \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "zohocrm",
    "template": {
      "id": 123,
      "data": {
        "contractNumber": "CONTRACT-2026-001",
        "client": "Acme Corp",
        "startDate": "2026-03-01",
        "endDate": "2027-03-01",
        "amount": 50000.00
      }
    },
    "upload": {
      "module": "Deals",
      "recordId": "4876876000001234567",
      "filename": "contract-2026-001.pdf",
      "attachmentName": "Annual Service Contract"
    }
  }'

Success Response:

{
  "success": true,
  "dispatchId": "disp_upload_abc123",
  "providerResponse": {
    "attachmentId": "4876876000009876543",
    "module": "Deals",
    "recordId": "4876876000001234567",
    "filename": "contract-2026-001.pdf",
    "fileSize": 245678,
    "uploadedAt": "2026-02-13T12:30:00Z",
    "url": "https://crm.zoho.com/crm/org123/Deals/4876876000001234567/attachments/4876876000009876543"
  },
  "generatedDocument": {
    "url": "https://storage.docs-dispatcher.io/contracts/CONTRACT-2026-001.pdf",
    "size": 245678,
    "contentType": "application/pdf"
  },
  "executionTime": 3.2
}

Zoho CRM Modules

Common modules to upload to:

Module	Use Case
Leads	Lead documents, quotes
Contacts	Contact agreements, NDAs
Accounts	Company contracts, SOWs
Deals	Proposals, contracts
Invoices	Invoice PDFs
Quotes	Quote documents
Contracts	Contract PDFs

Step 3: Universal Upload Provider

Generic upload for any storage system:

curl -X POST https://api.docs-dispatcher.io/api/upload \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "providerName": "universal",
    "template": {
      "id": 123,
      "data": {
        "documentTitle": "Monthly Report Feb 2026",
        "month": "February",
        "year": 2026
      }
    },
    "upload": {
      "url": "https://your-storage-api.com/upload",
      "method": "POST",
      "headers": {
        "Authorization": "Bearer YOUR_STORAGE_TOKEN",
        "X-Custom-Header": "value"
      },
      "filename": "report-feb-2026.pdf",
      "fieldName": "file"
    }
  }'

Universal Upload Response:

{
  "success": true,
  "dispatchId": "disp_upload_xyz789",
  "providerResponse": {
    "statusCode": 200,
    "responseBody": {
      "fileId": "file_abc123",
      "url": "https://your-storage.com/files/file_abc123",
      "uploadedAt": "2026-02-13T12:30:00Z"
    }
  },
  "generatedDocument": {
    "url": "https://storage.docs-dispatcher.io/reports/report-feb-2026.pdf",
    "size": 512345
  }
}

Step 4: Combine Upload with Other Services

Upload a document AND send it via email:

{
  "providerName": "zohocrm",
  "template": {
    "id": 123,
    "data": {
      "proposalNumber": "PROP-2026-001",
      "client": "Acme Corp",
      "amount": 25000.00
    }
  },
  "upload": {
    "module": "Deals",
    "recordId": "4876876000001234567",
    "filename": "proposal-2026-001.pdf"
  },
  "email": {
    "from": {
      "email": "[email protected]",
      "name": "Sales Team"
    },
    "to": [
      {
        "email": "[email protected]",
        "name": "Acme Procurement"
      }
    ],
    "subject": "Proposal PROP-2026-001",
    "body": {
      "html": "<p>Please find attached our proposal</p>"
    },
    "attachments": [
      {
        "filename": "proposal.pdf",
        "fromTemplate": true
      }
    ]
  }
}

Complete Examples

curl (Complete Flow)

#!/bin/bash

# Authenticate
AUTH_RESPONSE=$(curl -s -X POST https://api.docs-dispatcher.io/auth \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }')

JWT_TOKEN=$(echo $AUTH_RESPONSE | jq -r '.token')

# Upload to Zoho CRM
UPLOAD_REQUEST='{
  "providerName": "zohocrm",
  "template": {
    "id": 123,
    "data": {
      "contractNumber": "CONTRACT-2026-001",
      "client": "Acme Corp",
      "amount": 50000.00
    }
  },
  "upload": {
    "module": "Deals",
    "recordId": "4876876000001234567",
    "filename": "contract-2026-001.pdf",
    "attachmentName": "Annual Service Contract"
  }
}'

# Validate
VALIDATION=$(curl -s -X POST https://api.docs-dispatcher.io/api/upload/validate \
  -u "$EMAIL:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d "$UPLOAD_REQUEST")

if [ "$(echo $VALIDATION | jq -r '.valid')" = "true" ]; then
  # Upload
  RESULT=$(curl -s -X POST https://api.docs-dispatcher.io/api/upload \
    -u "$EMAIL:$PASSWORD" \
    -H "Content-Type: application/json" \
    -d "$UPLOAD_REQUEST")

  if [ "$(echo $RESULT | jq -r '.success')" = "true" ]; then
    echo "Upload successful!"
    echo "Attachment ID: $(echo $RESULT | jq -r '.providerResponse.attachmentId')"
    echo "Document URL: $(echo $RESULT | jq -r '.generatedDocument.url')"
  else
    echo "Upload failed:"
    echo $RESULT | jq
  fi
else
  echo "Validation failed:"
  echo $VALIDATION | jq '.errors'
fi

Node.js (Complete Flow)

const fetch = require('node-fetch');

const CONFIG = {
  templaterApiUrl: 'https://api.docs-dispatcher.io',
  dispatcherApiUrl: 'https://api.docs-dispatcher.io',
  email: '[email protected]',
  password: 'your-secure-password'
};

async function authenticate() {
  const response = await fetch(`${CONFIG.templaterApiUrl}/auth`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: CONFIG.email,
      password: CONFIG.password
    })
  });

  const data = await response.json();
  return data.token;
}

async function uploadToZohoCRM(jwtToken, uploadData) {
  const response = await fetch(`${CONFIG.dispatcherApiUrl}/api/upload`, {
    method: 'POST',
    headers: {
      'Authorization': authHeader,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(uploadData)
  });

  return await response.json();
}

async function main() {
  try {
    const email = process.env.DOCS_DISPATCHER_EMAIL;
const password = process.env.DOCS_DISPATCHER_PASSWORD;
const authHeader = createBasicAuthHeader(email, password);
// await authenticate();

    const uploadData = {
      providerName: 'zohocrm',
      template: {
        id: 123,
        data: {
          contractNumber: 'CONTRACT-2026-001',
          client: 'Acme Corp',
          amount: 50000.00
        }
      },
      upload: {
        module: 'Deals',
        recordId: '4876876000001234567',
        filename: 'contract-2026-001.pdf',
        attachmentName: 'Annual Service Contract'
      }
    };

    const result = await uploadToZohoCRM(jwtToken, uploadData);

    if (result.success) {
      console.log('Upload successful!');
      console.log('Attachment ID:', result.providerResponse.attachmentId);
      console.log('Zoho URL:', result.providerResponse.url);
    } else {
      console.error('Upload failed:', result.message);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

PHP (Complete Flow)

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

class UploadDispatcher {
    private $client;
    private $jwtToken;

    public function __construct() {
        $this->client = new Client();
    }

    public function authenticate($email, $password) {
        $response = $this->client->post('https://api.docs-dispatcher.io/auth', [
            'json' => [
                'email' => $email,
                'password' => $password
            ]
        ]);

        $data = json_decode($response->getBody(), true);
        $this->jwtToken = $data['token'];
        return $this->jwtToken;
    }

    public function uploadToZohoCRM($uploadData) {
        $response = $this->client->post('https://api.docs-dispatcher.io/api/upload', [
            'headers' => [
                'Authorization' => 'Bearer ' . $this->jwtToken,
                'Content-Type' => 'application/json'
            ],
            'json' => $uploadData
        ]);

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

$dispatcher = new UploadDispatcher();
$dispatcher->authenticate('[email protected]', 'password');

$uploadData = [
    'providerName' => 'zohocrm',
    'template' => [
        'id' => 123,
        'data' => [
            'contractNumber' => 'CONTRACT-2026-001',
            'client' => 'Acme Corp',
            'amount' => 50000.00
        ]
    ],
    'upload' => [
        'module' => 'Deals',
        'recordId' => '4876876000001234567',
        'filename' => 'contract-2026-001.pdf',
        'attachmentName' => 'Annual Service Contract'
    ]
];

$result = $dispatcher->uploadToZohoCRM($uploadData);

if ($result['success']) {
    echo "Upload successful!\n";
    echo "Attachment ID: {$result['providerResponse']['attachmentId']}\n";
} else {
    echo "Upload failed\n";
}

Java (Complete Flow)

import java.net.URI;
import java.net.http.*;
import com.google.gson.Gson;
import java.util.*;

public class UploadDispatcher {
    private final HttpClient client;
    private final Gson gson;
    private String jwtToken;

    public UploadDispatcher() {
        this.client = HttpClient.newHttpClient();
        this.gson = new Gson();
    }

    public void authenticate(String email, String password) throws Exception {
        Map<String, String> auth = new HashMap<>();
        auth.put("email", email);
        auth.put("password", password);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.docs-dispatcher.io/auth"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(auth)))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        Map data = gson.fromJson(response.body(), Map.class);
        this.jwtToken = (String) data.get("token");
    }

    public Map uploadToZohoCRM(Map<String, Object> uploadData) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.docs-dispatcher.io/api/upload"))
            .header("Authorization", authHeader)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(gson.toJson(uploadData)))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        return gson.fromJson(response.body(), Map.class);
    }

    public static void main(String[] args) throws Exception {
        UploadDispatcher dispatcher = new UploadDispatcher();
        dispatcher.authenticate("[email protected]", "password");

        Map<String, Object> uploadData = new HashMap<>();
        // Build upload data...

        Map result = dispatcher.uploadToZohoCRM(uploadData);
        System.out.println("Upload success: " + result.get("success"));
    }
}

Provider Comparison

Feature	Zoho CRM	Universal	AWS S3	Google Drive
CRM Integration	✅	❌	❌	❌
Custom Headers	❌	✅	❌	❌
Folder Organization	⚠️ Modules	✅	✅	✅
Direct URLs	✅	Depends	✅	✅
Metadata	✅	Custom	✅	✅

Best Practices

1. Use Descriptive Filenames

{
  "filename": "contract-acme-corp-2026-001.pdf"
}

2. Include Attachment Names (Zoho CRM)

{
  "attachmentName": "Annual Service Contract - Signed"
}

3. Handle Large Files

For files > 10MB, consider async mode:

POST /api/upload?async=true

Error Handling

Common Errors

Record Not Found

{
  "error": "record_not_found",
  "message": "Zoho CRM record not found: 4876876000001234567"
}

Permission Denied

{
  "error": "permission_denied",
  "message": "No permission to attach files to this module"
}

Next Steps

Related Recipes

• Email - Combine upload with email

• Async Flow - Upload large files asynchronously

Summary

You've learned:

• ✅ Upload documents to Zoho CRM

• ✅ Use universal upload provider

• ✅ Combine upload with other services

• ✅ Complete implementations in 4 languages

Document upload streamlines your CRM and storage workflows!