Kingsign API Client

Official JavaScript/TypeScript client for the Kingsign API. This package provides a simple and intuitive way to interact with the Kingsign document signing platform.

Installation

npm install kingsign-api-client

Quick Start

import { KingsignClient } from 'kingsign-api-client';

// Create a client instance
const client = new KingsignClient({
  apiKey: 'your-api-key-here',
  apiUrl: 'https://api.kingsign.com' // optional, defaults to production
});

// Use the client to interact with the API
try {
  const templates = await client.getTemplates();
  console.log('Templates:', templates);
} catch (error) {
  console.error('API Error:', error);
}

Configuration

The KingsignClient constructor accepts a configuration object with the following options:

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | apiKey | string | ✅ | - | Your Kingsign API key (automatically determines workspace) | | apiUrl | string | ❌ | 'https://api.kingsign.com' | Base URL for the API | | timeout | number | ❌ | 30000 | Request timeout in milliseconds | | headers | Record<string, string> | ❌ | {} | Additional headers to include |

API Methods

Document Management

Create Document

Creates a new document from a template with field assignments.

const document = await client.createDocument({
  template_id: 'template-123',
  title: 'Employment Contract',
  description: 'Please review and sign',
  fields: [
    {
      field_id: 'field-456',
      contact: {
        name: 'John Doe',
        email: '[email protected]',
        phone: '+1234567890'
      }
    }
  ]
});

Get Document

Retrieves a specific document by ID.

const document = await client.getDocument('document-123');

Get Documents

Retrieves all documents in the workspace.

const documents = await client.getDocuments();
// With optional query parameters
const pendingDocuments = await client.getDocuments({ status: 'pending' });

Template Management

Get Template

Retrieves a specific template by ID.

const template = await client.getTemplate('template-123');

Get Templates

Retrieves all templates in the workspace.

const templates = await client.getTemplates();
// With optional query parameters
const activeTemplates = await client.getTemplates({ archived: false });

Contact Management

Create Contact

Creates a new contact in the workspace.

const contact = await client.createContact({
  name: 'John Doe',
  email: '[email protected]',
  phone: '+1234567890'
});

Get Contact

Retrieves a specific contact by ID.

const contact = await client.getContact('contact-123');

Get Contacts

Retrieves all contacts in the workspace.

const contacts = await client.getContacts();
// With optional query parameters
const contactsByEmail = await client.getContacts({ email: '[email protected]' });

Complete Example

import { KingsignClient, CreateDocumentData } from 'kingsign-api-client';

const client = new KingsignClient({
  apiKey: 'your-api-key-here'
});

async function workflow() {
  try {
    // 1. Get available templates
    const templates = await client.getTemplates();
    console.log('Available templates:', templates);

    // 2. Create a contact
    const contact = await client.createContact({
      name: 'Jane Smith',
      email: '[email protected]',
      phone: '+1234567890'
    });
    console.log('Created contact:', contact);

    // 3. Create a document from a template
    if (templates.length > 0) {
      const createDocumentData: CreateDocumentData = {
        template_id: templates[0]._id,
        title: 'Employment Agreement',
        description: 'Please review and sign this employment agreement',
        fields: [
          {
            field_id: 'signature-field-1',
            contact: {
              name: 'Jane Smith',
              email: '[email protected]'
            }
          }
        ]
      };

      const document = await client.createDocument(createDocumentData);
      console.log('Created document:', document);
    }

    // 4. Get all documents
    const documents = await client.getDocuments();
    console.log('All documents:', documents);

  } catch (error) {
    console.error('Error:', error);
  }
}

workflow();

Error Handling

The client automatically transforms API errors into a consistent format:

try {
  const document = await client.getDocument('non-existent-id');
} catch (error) {
  if (error.name === 'ApiError') {
    console.error(`API Error ${error.code}: ${error.message}`);
    console.error('Details:', error.data);
  } else {
    console.error('Network or other error:', error);
  }
}

Types

The package includes comprehensive TypeScript definitions for all interfaces:

import { 
  // Client configuration
  KingsignClientConfig,
  
  // API responses
  ApiResponse, 
  ApiError,
  
  // Document types
  Document, 
  DocumentWithFields,
  CreateDocumentData,
  CreateDocumentResponse,
  DocumentStatus,
  
  // Template types
  Template,
  TemplateWithFields,
  
  // Contact types
  Contact,
  CreateContactData,
  
  // API actions
  ApiAction
} from 'kingsign-api-client';

Advanced Usage

Accessing the Axios Instance

For advanced use cases, you can access the underlying Axios instance:

const axiosInstance = client.getAxiosInstance();
// Use axiosInstance for custom requests

Getting Configuration

You can retrieve the current client configuration:

const config = client.getConfig();
console.log('API URL:', config.apiUrl);
console.log('Timeout:', config.timeout);

Development

To build the package locally:

npm install
npm run build

License

MIT License - see LICENSE file for details.

Support

For support and questions, please contact the Kingsign team or create an issue in the repository.