Get discounted Screen Watermarking with your subscription!

Funder API

Lightweight document protection. Route broker submissions to our endpoint prior to ingestion into your systems. We immediately return protected PDFs—ensuring unmarked files never enter your systems where users have access. Protection includes visible funder branding, optional broker attribution, and embedded metadata establishing clear chain of custody.

SOC2 Type II Certified Infrastructure
Files are encrypted in transit (TLS 1.2+) and at rest (AES-256). All downloads are logged. Files are automatically deleted and not retained in backups.
Setup time: 2-4 hours
Standard HTTP requests • Polling or webhook delivery • Most developers complete integration same day

Get Started

How It Works

The API uses asynchronous processing to handle submissions without timeouts. Choose whichever delivery method fits your workflow:

Option A: Polling (pull)

1 Submit job → Get job_id instantly

2 Poll status → Check if complete

3 Download → Get your watermarked PDFs
Option B: Webhooks (push)

1 Submit job with webhook_url → Get job_id instantly

2 We POST results to your URL when ready

3 Download → Get your watermarked PDFs

Both options return the same watermarked files. Webhooks eliminate the need to poll, making them ideal for high-volume or event-driven workflows.

Endpoints

Submit Job

POST https://aquamark-funder-broker.onrender.com/watermark-funder-broker

Check Status

GET https://aquamark-funder-broker.onrender.com/job-status/:job_id

Download (Authenticated)

GET https://aquamark-funder-broker.onrender.com/download/:job_id

Requires Bearer token. Returns the watermarked ZIP file directly. All downloads are logged for audit purposes.

Authentication

Authorization: Bearer aqua-funder-api-101060-042858-101812

This API key is universal and can be used immediately for testing.

Parameters

Parameter Type Description
user_email String Your company email (authorized funder account)
Use [email protected] for testing
broker String (optional) Broker's name or email address
If omitted, documents are watermarked with funder branding only (no broker attribution).
files Array of Objects Array of file objects, each containing:
name (required): Filename with .pdf extension
url or data (required): Public URL or base64-encoded PDF
Can mix URL and base64 files in the same request
webhook_url String (optional) HTTPS URL to receive job results
If provided, we POST the result to this URL on completion or failure.
metadata Object (optional) Freeform JSON object for your own tracking data
Stored with the job and echoed back in every response and webhook payload. Max 64KB. We never read or modify its contents.

Max file size: 50MB per file

Files Parameter Format:

Each file object must include:
• name: The filename (e.g., "bank-statement-jan.pdf")
• url: Public URL to the PDF file, OR
• data: Base64-encoded PDF data

You can mix URL and base64 files in the same request for maximum flexibility.

Note: Examples use cURL for clarity. Translate to your preferred language (Python, JavaScript, Java, etc.). Standard HTTP requests—nothing custom.

Complete Example: Polling

1 Submit Job

curl -X POST https://aquamark-funder-broker.onrender.com/watermark-funder-broker \
  -H "Authorization: Bearer aqua-funder-api-101060-042858-101812" \
  -H "Content-Type: application/json" \
  -d '{
    "user_email": "[email protected]",
    "broker": "ABC Capital Partners",
    "files": [
      {
        "name": "bank-statement-jan.pdf",
        "url": "https://your-portal.com/submissions/jan.pdf"
      },
      {
        "name": "bank-statement-feb.pdf",
        "data": "JVBERi0xLjcKJeLjz9MK..."
      },
      {
        "name": "bank-statement-mar.pdf",
        "data": "JVBERi0xLjcKJeLjz9MK..."
      },
      {
        "name": "credit-application.pdf",
        "url": "https://your-portal.com/submissions/credit-app.pdf"
      },
      {
        "name": "voided-check.pdf",
        "data": "JVBERi0xLjcKJeLjz9MK..."
      }
    ],
    "metadata": {
      "deal_id": "DEAL-9921",
      "source": "crm"
    }
  }'

Note: You can mix files with url and files with data (base64) in the same request. The data field should contain the complete base64-encoded PDF. Convert your PDF files to base64 using any standard library before sending.

Funder-Only Watermarking (No Broker Attribution)

Omit the broker parameter to watermark with your funder logo only:

curl -X POST https://aquamark-funder-broker.onrender.com/watermark-funder-broker \
  -H "Authorization: Bearer aqua-funder-api-101060-042858-101812" \
  -H "Content-Type: application/json" \
  -d '{
    "user_email": "[email protected]",
    "files": [
      {
        "name": "bank-statement-jan.pdf",
        "url": "https://your-portal.com/submissions/jan.pdf"
      }
    ]
  }'

Output files will be named bank-statement-jan-watermarked.pdf instead of including a broker slug.

2 Response (instant)

{
  "success": true,
  "job_id": "abc-123-def-456",
  "file_count": 5,
  "webhook_url": null,
  "message": "Watermarking job started",
  "status_url": "/job-status/abc-123-def-456",
  "metadata": {
    "deal_id": "DEAL-9921",
    "source": "crm"
  }
}

3 Poll Status

Use the job_id from Step 2 to check status every 10 seconds:

curl https://aquamark-funder-broker.onrender.com/job-status/abc-123-def-456

While processing:

{
  "job_id": "abc-123-def-456",
  "status": "processing",
  "progress": "Processing file 2 of 5: bank-statement-feb.pdf",
  "created_at": "2025-01-06T10:00:00Z",
  "metadata": {
    "deal_id": "DEAL-9921",
    "source": "crm"
  }
}

When complete:

{
  "job_id": "abc-123-def-456",
  "status": "completed",
  "download_url": "https://...funder-job-results/abc-123-def-456.zip?token=eyJhbG...",
  "download_expires_at": "2026-02-24T19:45:22.418Z",
  "authenticated_download_url": "https://aquamark-funder-broker.onrender.com/download/abc-123-def-456",
  "message": "Ready for download. Signed link expires in 10 minutes. For logged/authenticated downloads, use the authenticated_download_url with your Bearer token.",
  "created_at": "2025-01-06T10:00:00Z",
  "completed_at": "2025-01-06T10:01:30Z",
  "metadata": {
    "deal_id": "DEAL-9921",
    "source": "crm"
  }
}

On error:

{
  "job_id": "abc-123-def-456",
  "status": "failed",
  "error_message": "Job timed out after 10 minutes",
  "created_at": "2025-01-06T10:00:00Z",
  "completed_at": "2025-01-06T10:10:00Z",
  "metadata": {
    "deal_id": "DEAL-9921",
    "source": "crm"
  }
}

The metadata field is only present if you included it in the original request.

4 Download

Two download methods are available:

Option A: Signed URL (direct)

Use the download_url from Step 3. No auth required, but the link expires in 10 minutes.

curl "https://...funder-job-results/abc-123-def-456.zip?token=eyJhbG..." --output watermarked.zip

Option B: Authenticated download

Use the authenticated_download_url with your Bearer token. Every download is logged with IP, timestamp, and file size.

curl -H "Authorization: Bearer aqua-funder-api-101060-042858-101812" \
  https://aquamark-funder-broker.onrender.com/download/abc-123-def-456 \
  --output watermarked.zip

Complete Example: Webhooks

Instead of polling, add a webhook_url to your request and we'll POST the results directly to your server when the job finishes.

1 Submit Job with Webhook

curl -X POST https://aquamark-funder-broker.onrender.com/watermark-funder-broker \
  -H "Authorization: Bearer aqua-funder-api-101060-042858-101812" \
  -H "Content-Type: application/json" \
  -d '{
    "user_email": "[email protected]",
    "broker": "ABC Capital Partners",
    "files": [
      {
        "name": "bank-statement-jan.pdf",
        "url": "https://your-portal.com/submissions/jan.pdf"
      }
    ],
    "webhook_url": "https://your-server.com/aquamark-webhook",
    "metadata": {
      "deal_id": "DEAL-9921"
    }
  }'

2 Response (instant)

{
  "success": true,
  "job_id": "abc-123-def-456",
  "file_count": 1,
  "webhook_url": "https://your-server.com/aquamark-webhook",
  "message": "Watermarking job started. You will receive a webhook when processing completes.",
  "status_url": "/job-status/abc-123-def-456",
  "metadata": {
    "deal_id": "DEAL-9921"
  }
}

3 Webhook Delivery

When processing completes, we POST to your webhook_url:

On success:

POST https://your-server.com/aquamark-webhook

Headers:
  Content-Type: application/json
  X-Aquamark-Event: job.completed
  X-Aquamark-Signature: 2ed0b90b005db9ef29a048f28a1e8acf...
  X-Aquamark-Delivery: 7860e1bc-0b42-48e5-ad95-587c04c0efbe
  User-Agent: Aquamark-Webhooks/1.0

Body:
{
  "event": "job.completed",
  "job_id": "abc-123-def-456",
  "status": "completed",
  "download_url": "https://...funder-job-results/abc-123-def-456.zip?token=eyJhbG...",
  "download_expires_at": "2026-02-20T15:40:12.456Z",
  "authenticated_download_url": "https://aquamark-funder-broker.onrender.com/download/abc-123-def-456",
  "file_count": 1,
  "failure_count": 0,
  "elapsed_ms": 1842,
  "completed_at": "2026-02-20T15:30:12.456Z",
  "metadata": {
    "deal_id": "DEAL-9921"
  }
}

On error:

{
  "event": "job.failed",
  "job_id": "abc-123-def-456",
  "status": "failed",
  "error_message": "All files failed to process",
  "completed_at": "2026-02-20T15:31:00.000Z",
  "metadata": {
    "deal_id": "DEAL-9921"
  }
}

4 Download

Two download options are available:

Option A: Signed URL (direct)

Use the download_url from the webhook payload. No auth required, but the link expires in 10 minutes.

curl "https://...funder-job-results/abc-123-def-456.zip?token=eyJhbG..." --output watermarked.zip

Option B: Authenticated download

Use the authenticated_download_url with your Bearer token. Every download is logged.

curl -H "Authorization: Bearer aqua-funder-api-101060-042858-101812" \
  https://aquamark-funder-broker.onrender.com/download/abc-123-def-456 \
  --output watermarked.zip

Verifying Webhook Signatures

Each webhook includes an X-Aquamark-Signature header — an HMAC-SHA256 hash of the request body signed with your API key. Verify it to confirm the webhook came from Aquamark:

// Node.js example
const crypto = require('crypto');

function verifyWebhook(requestBody, signatureHeader, apiKey) {
  const expected = crypto
    .createHmac('sha256', apiKey)
    .update(requestBody)
    .digest('hex');
  return expected === signatureHeader;
}

Webhook Behavior

Retry policy: If your server returns a 5xx error or is unreachable, we retry up to 3 times with exponential backoff (2s, 4s, 8s). Client errors (4xx) are not retried.

Timeout: Your endpoint must respond within 10 seconds.

HTTPS required: Webhook URLs must use HTTPS.

Fallback: You can always poll /job-status/:job_id as a backup, even when using webhooks.

Example ZIP Contents

With broker attribution:

watermarked.zip/
├── bank-statement-jan-abc-capital-partners.pdf
├── bank-statement-feb-abc-capital-partners.pdf
├── bank-statement-mar-abc-capital-partners.pdf
├── credit-application-abc-capital-partners.pdf
└── voided-check-abc-capital-partners.pdf

Funder-only (no broker):

watermarked.zip/
├── bank-statement-jan-watermarked.pdf
├── bank-statement-feb-watermarked.pdf
└── bank-statement-mar-watermarked.pdf

Each file is watermarked with your funder logo. When a broker is specified, the broker's name is also included in the watermark and filename.

Polling Interval

File Availability & Security

Important Notes

Unzip required. Downloads are ZIP files. Use standard extraction libraries in your language.

Error Handling & Failure Behavior

Failures fall into three categories depending on when they occur. Here's what to expect at each stage.

Submission Failures (Synchronous)

These happen before a job is created — your HTTP call gets an error status code and message directly. There is no job_id to poll.

Common causes: Invalid or missing API key (401), user not found or inactive (403), missing or malformed files array (400), file exceeds 50MB (400), invalid broker name characters (400), invalid webhook_url (400), or rate limit exceeded (429).

What to do: Check the error message in the response body. Fix the request and resubmit. No cleanup is needed since no job was created.

Processing Failures (Asynchronous)

The job was created and you received a job_id, but something failed during watermarking. The job status changes to "failed".

Common causes: A PDF is corrupted or can't be parsed, a PDF is password-protected and can't be decrypted, the output ZIP upload to storage fails after retries, or all files fail to process.

How you'll know: Poll /job-status/:job_id and the status will be "failed" with an error_message field. If you provided a webhook_url, you'll receive a job.failed webhook with the same error message.

Timeout: Jobs that haven't completed within 10 minutes are automatically marked as failed with the message "Job timed out after 10 minutes".

Partial Failures

If you submit multiple files and some succeed while others fail, the job still completes with the successful files in the ZIP.

How to detect: The webhook payload includes both file_count (successful) and failure_count. If failure_count is greater than 0, some files failed. The job status will be "completed", not "failed".

Example: You submit 5 files. If 1 is corrupted, you'll get 4 successful PDFs in the ZIP, with "file_count": 4 and "failure_count": 1.

Download Failures

Signed URL expired (403 from storage): Poll /job-status/:job_id again to get a fresh signed URL. The file stays available for 30 minutes total after job completion.

File already deleted (410): The file was either downloaded via the authenticated endpoint (which auto-deletes), manually confirmed via /job-complete/:job_id, or auto-cleaned after 30 minutes. The job data is gone — resubmit the original request.

Invalid API key on authenticated download (401): Check your Bearer token.

Webhook Delivery Failures

Your endpoint is down or returns 5xx: We retry up to 3 times with exponential backoff (2s, 4s, 8s). If all retries fail, the webhook is dropped.

Your endpoint returns 4xx (except 429): Not retried. Check your endpoint logic.

Fallback: Polling /job-status/:job_id always works regardless of webhook delivery.

Error Codes

Code Meaning Example Response
400 Bad request Validation error (missing params, invalid format)
401 Invalid API key Invalid API key
403 User not authorized User not found or inactive
404 Job not found Job not found
410 File expired or already downloaded File has already been downloaded and removed, or has expired
413 File too large File 'statement.pdf' exceeds 50MB limit
429 Rate limit exceeded Too many requests. Please wait 15 minutes and try again.
500 Server error Internal server error

Limits

Getting Started

To integrate watermarking API:

  1. Test: Verify integration using test parameters above (uses Aquamark branding).
  2. Ready?: Email [email protected] to request production access.
  3. Authorization: We'll authorize your company email.
  4. Upload logo: We'll provide instructions for logo upload.
  5. Billing: We'll send your first invoice after 30 days, based on usage.
  6. Go live: Deploy to production when ready.

Questions? Contact [email protected]
Privacy Policy