REST API Integration | IgniSign - The e-signature API for developers

REST API Integration

Integrate Ignisign using direct REST API calls without SDK dependencies

This guide explains how to integrate Ignisign's electronic signature capabilities directly using the REST API, without using the SDK. The REST API provides complete access to all Ignisign features, allowing you to build custom integrations in any programming language that supports HTTP requests.

tip

If you're looking for the quickest way to integrate digital signatures, check out our API Integration Quick Win guide. It covers the simplest implementation path that satisfies 80% of common use cases with minimal code.

Key Advantages

Using the direct REST API approach offers several benefits:

Language Agnostic

Integrate Ignisign with any programming language or framework

Minimal Dependencies

No need to include additional SDK libraries in your project

Fine-Grained Control

Access to precise API behaviors and detailed error handling

Lightweight Integration

Perfect for microservices or specialized implementations

Customizable Flow

Build exactly the signature experience your application needs

Authentication

All Ignisign API requests require authentication using your API key with a Bearer token:

// Add your API key to request headers
const headers = {
'Authorization': 'Bearer skv2_your_api_key_here',
'Content-Type': 'application/json'
};

async function makeApiRequest(endpoint, method, data = null) {
const response = await fetch(`https://api.ignisign.io/v4/${endpoint}`, {
  method,
  headers,
  ...(data && { body: JSON.stringify(data) })
});

if (!response.ok) {
  throw new Error(`API request failed: ${response.statusText}`);
}

return await response.json();
}

You can find your API key in the Ignisign Console under your application's API Keys section. API keys start with skv2_.

Core Functionality

Working with Documents

Before creating signature requests, you need to prepare the documents to be signed:

async function uploadDocument(token: string, appId: string, appEnv: string, documentFile: File) {
const formData = new FormData();
formData.append('document', documentFile);

const response = await fetch(`https://api.ignisign.io/v4/applications/${appId}/envs/${appEnv}/documents`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: formData
});

if (!response.ok) {
  throw new Error(`Document upload failed: ${response.statusText}`);
}

return await response.json();
}

Creating a Signature Request

Ignisign provides a "one-call-sign" endpoint that simplifies creating signature requests with all necessary components:

async function createSignatureRequest(token: string, requestData) {
const response = await fetch('https://api.ignisign.io/v4/signature-requests/one-call-sign', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestData)
});

if (!response.ok) {
  throw new Error(`Signature request creation failed: ${response.statusText}`);
}

return await response.json();
}

// Example request data
const signatureRequestData = {
title: "Contract signature",
signatureMethod: "SIMPLE_STD",
signers: [
  {
    email: "[email protected]",
    firstName: "John",
    lastName: "Doe"
  }
],
documents: [
  {
    originalName: "contract.pdf",
    mimeType: "application/pdf",
    base64: "JVBERi0xLjcKJb...[Base64 encoded content]"
  }
]
};

Retrieving Signature Request Status

You can check the status of signature requests to track their progress:

async function getSignatureRequestsStatus(token: string, appId: string, appEnv: string, signatureRequestIds: string[]) {
const response = await fetch(`https://api.ignisign.io/v4/applications/${appId}/envs/${appEnv}/signature-requests/status`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signatureRequestIds
  })
});

if (!response.ok) {
  throw new Error(`Failed to get status: ${response.statusText}`);
}

return await response.json();
}

Working with Signers

Managing signers is a key part of the signature process:

// Check if signers can be added to a signature request
async function checkSignersCanBeAdded(token: string, signatureRequestId: string, emails: string[]) {
const response = await fetch(`https://api.ignisign.io/v4/signature-requests/${signatureRequestId}/check-signers-can-be-added`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    emails
  })
});

if (!response.ok) {
  throw new Error(`Failed to check signers: ${response.statusText}`);
}

return await response.json();
}

// Resend email to a signer
async function resendSignatureRequestEmail(token: string, signatureRequestId: string, signerId: string) {
const response = await fetch(`https://api.ignisign.io/v4/signature-requests/${signatureRequestId}/${signerId}/resend-email`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

if (!response.ok) {
  throw new Error(`Failed to resend email: ${response.statusText}`);
}

return await response.json();
}

Advanced Features

Webhooks Integration

Webhooks allow your application to receive real-time updates about signature events:

// Add a webhook endpoint to your application
async function addWebhookEndpoint(token: string, appId: string, appEnv: string, endpointData) {
const response = await fetch(`https://api.ignisign.io/v4/applications/${appId}/envs/${appEnv}/webhooks/endpoints`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(endpointData)
});

if (!response.ok) {
  throw new Error(`Failed to add webhook: ${response.statusText}`);
}

return await response.json();
}

// Example webhook endpoint data
const webhookEndpointData = {
url: "https://your-app.com/webhooks/ignisign",
topics: ["SIGNATURE_REQUEST", "SIGNATURE"],
description: "Main webhook endpoint"
};

// Example webhook handler implementation
function handleWebhookEvent(req, res) {
const eventData = req.body;

// Verify webhook authenticity
// Implement your verification logic here

// Process different event types
switch(eventData.topic) {
  case "SIGNATURE_REQUEST":
    handleSignatureRequestEvent(eventData);
    break;
  case "SIGNATURE":
    handleSignatureEvent(eventData);
    break;
  default:
    console.log("Unknown webhook event type:", eventData.topic);
}

// Acknowledge receipt
res.status(200).send();
}

Downloading Signature Proofs

After signatures are completed, you can download the proof documents:

async function downloadSignatureProof(token: string, documentId: string, signatureType: string) {
const response = await fetch(`https://api.ignisign.io/v4/documents/${documentId}/signature-type/${signatureType}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

if (!response.ok) {
  throw new Error(`Failed to download proof: ${response.statusText}`);
}

// Return the binary stream
return await response.blob();
}

// Save the proof to a file
async function saveProofToFile(proof, filename) {
const url = window.URL.createObjectURL(proof);
const a = document.createElement('a');
a.href = url;
a.download = filename;
document.body.appendChild(a);
a.click();
window.URL.revokeObjectURL(url);
document.body.removeChild(a);
}

// Usage example
async function getAndSaveProof(token, documentId) {
const proof = await downloadSignatureProof(token, documentId, 'PDF_WITH_SIGNATURES');
await saveProofToFile(proof, `proof-${documentId}.pdf`);
}

Common Issues & Troubleshooting

Here are some common issues and their solutions when working with the Ignisign REST API:

Authentication Errors

Make sure your API credentials (appId, appEnv, secret) are correct
Check that your JWT token hasn't expired
Ensure you're using the correct environment (DEVELOPMENT vs PRODUCTION)

Request Format Errors

Validate your JSON payloads against the API specification
Check for missing required fields or incorrect data types
Ensure all IDs (documentId, signerId, etc.) are valid

Webhook Issues

Verify your webhook endpoint is publicly accessible
Ensure proper error handling in your webhook receiver
Implement retry logic for processing webhook events

Error Handling

Implement proper error handling in your requests:

// Example error handling
async function apiRequest(url, options) {
try {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`API Error (${response.status}): ${errorData.message || response.statusText}`);
  }
  
  return await response.json();
} catch (error) {
  console.error('API request failed:', error);
  // Handle specific error types
  if (error.message.includes('401')) {
    // Handle authentication error
    refreshToken();
  }
  throw error;
}
}

Next Steps

Now that you understand how to integrate with Ignisign's REST API, you can:

Explore Advanced Features:
- Implement custom signature workflows
- Add multi-factor authentication for signers
- Integrate with your document management system
Optimize Your Integration:
- Implement caching strategies for tokens and frequently used data
- Add monitoring and logging for API requests
- Develop comprehensive error handling
Consider Compliance Requirements:
- Ensure your integration meets regulatory requirements (eIDAS, ESIGN, etc.)
- Implement appropriate data retention policies
- Document your signature processes for compliance audits

For more information, refer to the complete API reference or contact Ignisign support for assistance with your specific integration needs.