API Documentation

Integrate DeckExtract into your applications to extract documents from DocSend and Papermark programmatically.

Overview

The DeckExtract API allows you to programmatically extract and download documents from DocSend and Papermark links. The API handles authentication, email verification, and document conversion automatically, returning PDF files ready for download.

Base URL:https://deckextract.com/api

Rate Limiting

To ensure fair usage and maintain service quality, the API implements rate limiting:

5 requests per IP address per 30 minutes
Rate limit windows reset every 30 minutes
Rate limits are tracked by IP address (from x-forwarded-for, x-real-ip, or connection IP)

Rate Limit Exceeded: If you exceed the rate limit, you'll receive a 429 response with the error message: "Rate limit exceeded. Maximum 5 requests per 30 minutes per IP."

Endpoint

POST /api

The API accepts POST requests with a JSON body containing the document URL and optional authentication parameters.

Request Format

{
  "url": "https://docsend.com/view/...",
  "email": "optional@example.com",
  "password": "optional-password",
  "sessionId": "optional-session-id"
}

Request Parameters

Parameter	Type	Required	Description
`url`	string	Yes	The DocSend or Papermark document URL to extract
`email`	string	No	Email address (only required if the DocSend link requires email whitelist verification)
`password`	string	No	Password for password-protected documents
`sessionId`	string	No	Session ID from a previous request (for multi-step flows)

Response Types

The API can return different response types depending on the document requirements and extraction status:

1. Success Response (PDF)

When extraction is successful, the API returns the PDF file directly with:

Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"

2. Requires Credentials

{
  "success": false,
  "platform": "docsend",
  "requiresCredentials": true,
  "error": "This document requires a password",
  "sessionId": "abc123..."
}

The document requires authentication. Retry the request with the appropriate email or password parameters. Use the returned sessionId in subsequent requests.

3. Requires Email Confirmation (2-Step Process)

{
  "success": false,
  "platform": "docsend",
  "requiresEmailConfirmation": true,
  "email": "user@example.com",
  "isUserSuppliedEmail": true,
  "message": "Email confirmation required. Please check your email and paste the confirmation URL.",
  "sessionId": "abc123..."
}

The document requires email verification. If you provided a custom email (isUserSuppliedEmail: true), you need to:

Check the email inbox for a verification link
Make a new request with the verification URL and the same sessionId

Note: If you don't provide an email and the API generates a temporary email automatically, the API will poll for the verification email and complete the process automatically. You don't need to handle this case manually.

4. Email Not Whitelisted

{
  "success": false,
  "platform": "docsend",
  "requiresEmailReview": true,
  "requiresCredentials": true,
  "email": "user@example.com",
  "error": "The email address does not have permission to view this document. Please try a different email address.",
  "sessionId": "abc123..."
}

The provided email address is not whitelisted for this document. Retry with a different email address using the same sessionId.

5. Error Responses

{
  "success": false,
  "error": "Error message here"
}

Usage Examples

Simple Extraction (No Authentication)

curl -X POST https://deckextract.com/api \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docsend.com/view/abc123"
  }' \
  --output document.pdf

Password-Protected Document

curl -X POST https://deckextract.com/api \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docsend.com/view/abc123",
    "password": "mypassword"
  }' \
  --output document.pdf

Email Whitelist Required

If a DocSend link requires email whitelist verification, you must provide an email address:

curl -X POST https://deckextract.com/api \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docsend.com/view/abc123",
    "email": "your-email@example.com"
  }' \
  --output document.pdf

Two-Step Process with Custom Email

When email confirmation is required with a custom email:

# Step 1: Initial request
RESPONSE=$(curl -X POST https://deckextract.com/api \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docsend.com/view/abc123",
    "email": "your-email@example.com"
  }')

# Extract sessionId from response
SESSION_ID=$(echo $RESPONSE | jq -r '.sessionId')

# Step 2: After receiving email confirmation link, 
# make request with verification URL
curl -X POST https://deckextract.com/api \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docsend.com/view/abc123?token=...",
    "email": "your-email@example.com",
    "sessionId": "'$SESSION_ID'"
  }' \
  --output document.pdf

JavaScript/TypeScript Example

async function extractDocument(url, email, password) {
  let sessionId = null;
  
  while (true) {
    const response = await fetch('https://deckextract.com/api', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        url,
        email,
        password,
        sessionId,
      }),
    });

    // Check if response is PDF
    const contentType = response.headers.get('content-type');
    if (contentType === 'application/pdf') {
      const blob = await response.blob();
      const downloadUrl = window.URL.createObjectURL(blob);
      const a = document.createElement('a');
      a.href = downloadUrl;
      a.download = 'document.pdf';
      a.click();
      return;
    }

    // Parse JSON response
    const data = await response.json();
    
    if (data.success === false) {
      if (data.requiresEmailConfirmation && data.isUserSuppliedEmail) {
        // Wait for user to confirm email and provide verification URL
        const verificationUrl = prompt(
          data.message + '\\n\\nPaste the verification URL:'
        );
        if (verificationUrl) {
          url = verificationUrl;
          sessionId = data.sessionId;
          continue;
        }
      }
      
      if (data.requiresCredentials) {
        // Retry with credentials
        if (!email && data.error.includes('email')) {
          email = prompt('Email required:');
        }
        if (!password && data.error.includes('password')) {
          password = prompt('Password required:');
        }
        sessionId = data.sessionId;
        continue;
      }
      
      throw new Error(data.error || 'Extraction failed');
    }
  }
}

Error Codes

Error Message	Description	Solution
`Rate limit exceeded...`	Too many requests from your IP address	Wait 30 minutes or use a different IP address
`Platform not yet supported`	The URL is not from DocSend or Papermark	Ensure the URL is from a supported platform
`This document link is disabled...`	The document link has been disabled	Contact the document owner for a new link
`This document requires a password`	Document is password-protected	Include `password` in request body
`The email address does not have permission...`	Email is not whitelisted for this document	Try a different email address
`Timeout waiting for verification email`	Verification email not received within timeout period	Retry the request or use a custom email
`Failed to read PDF file`	Internal error during PDF generation	Retry the request
`Session error`	Browser session creation failed	Retry the request

Best Practices

Always handle session IDs: When a response includes a sessionId, use it in subsequent requests for the same extraction flow.
Email requirements: Only provide an email if the DocSend link requires email whitelist verification. The API will automatically generate a temporary email if needed.
Error handling: Check the response type before processing. PDF responses have Content-Type: application/pdf, while error responses are JSON.
Rate limiting: Implement exponential backoff if you hit rate limits, or batch requests to stay within limits.
Two-step flows: For email confirmation flows with custom emails, prompt users to check their email and provide the verification URL.

Support

For questions, issues, or feature requests, please visit our FAQ page or check out our blog for guides and tutorials.