Custom Connector
DocSpring API Connector
Global
The DocSpring API Connector facilitates seamless integration with the DocSpring service, providing PDF generation, template management, submission processing, and document handling. It acts as a proxy for template creation, PDF generation, batch processing, and document management.
Overview
Integration Overview
This document provides a detailed guide for each integration point, its purpose, configuration, and workflow support using the DocSpring API Connector.
- Authentication. Test API authentication and verify credentials.
- Template management. Create, read, update, delete, and manage PDF/HTML templates.
- PDF generation. Generate individual PDFs from templates.
- Batch processing. Process multiple PDF submissions in batches.
- Submission management. Check status, expire, and manage PDF submissions.
- Combined PDFs. Merge multiple PDFs into single documents.
- Folder management. Organize templates in folder structures.
- Custom files. Upload and manage custom files for PDF operations.
- Data requests. Handle form data collection and processing.
Documentation
Detailed Integration Documentation
Authentication Testing
| Action | GET /authentication |
|---|---|
| Purpose | Validates API credentials and tests connectivity to the DocSpring service. |
| Configuration | Configure the connector with the appropriate environment variables. |
| Parameters | Required: Authorization – Basic authentication token. Optional: None. |
| Output | Successful: JSON with status (e.g. success). Failure: error details (e.g. Unauthorized). |
| Workflow example | Execute the authentication endpoint with a valid Authorization header, verify status is success, then proceed with API operations. |
Template Management
| Endpoints | GET /templates (list); POST /templates (create); GET /templates/{template_id} (details); PUT /templates/{template_id} (update); DELETE /templates/{template_id} (delete). |
|---|---|
| Purpose | Manage PDF and HTML templates for document generation. |
| Parameters | Required for creation: Authorization; template configuration (name, type, content). Optional: parent_folder_id, description, various template settings. |
| Output | Successful: template object (id, name, template_type, document_state, configuration). Failure: error with status code and message. |
| Workflow example | Create a template with POST /templates, retrieve its schema with GET /templates/{id}/schema, then use the template ID for PDF generation. |
Single PDF Generation
| Action | POST /templates/{template_id}/submissions |
|---|---|
| Purpose | Generate a single PDF from a template with provided data. |
| Parameters | Required: Authorization; template_id; JSON data for template filling. Optional: None. |
| Output | Successful: submission object (status, submission details, download URLs when ready). Failure: error with status code and message. |
| Workflow example | Prepare JSON data matching the template schema, submit to the submissions endpoint, monitor status, then retrieve the generated PDF. |
Batch PDF Processing
| Endpoints | POST /submissions/batches (create); GET /submissions/batches/{batch_id} (check status). |
|---|---|
| Purpose | Process multiple PDF generations in a single batch operation. |
| Parameters | Required: Authorization; array of submission data objects. |
| Output | Successful: batch object (submission_batch metadata, submissions array, completion_percentage, error_count). Failure: error with status code. |
| Workflow example | Prepare an array of submission data, submit a batch, monitor status by batch ID, then retrieve individual PDFs as they complete. |
Submission Status Management
| Endpoints | GET /submissions/{submission_id} (status); DELETE /submissions/{submission_id} (expire); GET /submissions (list). |
|---|---|
| Purpose | Monitor and manage the PDF submission lifecycle. |
| Parameters | Required: Authorization; submission_id. |
| Output | Successful: submission object (processing state, timestamps, download URLs, validation errors). Failure: error with status code. |
| Workflow example | Generate a submission and obtain its ID, poll until state is processed, retrieve the permanent download URL, then optionally expire it. |
PDF Combination Service
| Endpoints | POST /combined_submissions (merge); GET /combined_submissions/{combined_id} (status); DELETE /combined_submissions/{combined_id} (expire). |
|---|---|
| Purpose | Combine multiple PDF documents into a single file. |
| Parameters | Required: Authorization; source_pdfs – array of PDF sources (submissions, templates, URLs). |
| Output | Successful: combined submission object (metadata, status, download URL, source references). Failure: error with status code. |
| Workflow example | Identify PDF sources to combine, submit a combination request, monitor status, then download the merged PDF. |
Example Workflow: Document Generation Pipeline
| Template setup | Create or upload a template with POST /templates, retrieve its schema, and validate the data structure. |
|---|---|
| Single generation | Execute POST /templates/{id}/submissions with JSON data, monitor status, then download the PDF. |
| Batch processing | Prepare multiple payloads, submit via POST /submissions/batches, track progress, and retrieve PDFs as available. |
| Document management | Organize templates in folders, combine related PDFs, and manage the submission lifecycle. |
Support
For technical support, contact custom-connectors-support@isolutions.sa.