# API Integration Guide
> Guide to implement an electronic signature flow using the Legaldoc.io API and the embedded widget.
Guide to implement an electronic signature flow using the Legaldoc.io API and the embedded widget.
---
## Prerequisites
- **API Key**: Authentication token for the API
- **Configured Template**: A template created in the Legaldoc.io portal
### Authentication
All requests must include:
```http
Authorization: {API_KEY}
Content-Type: application/json
```
---
## Integration Flow
---
## Step 1: Get the Template ID
The ID is obtained from the URL when editing a template:
```
https://app.legaldoc.io/t/my-team/templates/18
↑
Template ID = 18
```
### Email Options Configuration
If you **do not want** automatic emails to be sent to signers, you must configure the **Email Options** in the template editor:
1. In the template editor, under **General**
2. In the **Email Options** section, uncheck all email sending checkboxes:
- ❌ Send recipient completed signature email
- ❌ Send recipient signature request email
- ❌ Send recipient deleted email
- ❌ Send document pending email
- ❌ Send document completed email
- ❌ Send document deleted email
- ❌ Send document completed email to owner
> **Note:** With these options disabled, you must manually distribute the signing links using the API or the embedded widget.
---
## Step 2: Get Template Details
Get the signer ID configured in the template.
### Request
```http
GET https://app.legaldoc.io/api/v1/templates/18
```
### Response (simplified)
```json
{
"id": 18,
"title": "My Contract.pdf",
"recipients": [
{
"id": 52,
"name": "Recipient",
"email": "recipient@legaldoc.io",
"role": "SIGNER"
}
]
}
```
> **Important:** Save the `recipients[].id` (in this example: **52**) for the next step.
---
## Step 3: Generate the Document
Create a document from the template with the actual signer data.
### Request
```http
POST https://app.legaldoc.io/api/v1/templates/18/generate-document
```
### Body
```json
{
"title": "Contract - Client ABC",
"recipients": [
{
"id": 52,
"name": "John Doe",
"email": "john.doe@company.com"
}
]
}
```
### Response
```json
{
"documentId": 153,
"recipients": [
{
"recipientId": 174,
"name": "John Doe",
"email": "john.doe@company.com",
"token": "abc123XYZ",
"role": "SIGNER",
"signingUrl": "https://app.legaldoc.io/sign/abc123XYZ"
}
]
}
```
> **Important:** Save the `token` (**abc123XYZ**) for use in the embedded widget.
### 3.1 Pre-fill Document Fields (Optional)
If you need certain fields to appear with default values, you can use `prefillFields`.
**Example:** Pre-fill a text field with a bank account number.
#### Prerequisite: Identify the field
From the response in **Step 2** (Get Template Details), find the field you want to pre-fill in the `fields` array:
```json
{
"id": 526,
"type": "TEXT",
"recipientId": 144,
"fieldMeta": {
"label": "Account Number",
"type": "text",
"required": true
}
}
```
> **Note:** Save the field `id` (in this example: **526**).
#### Request with pre-filled fields
```http
POST https://app.legaldoc.io/api/v1/templates/19/generate-document
```
```json
{
"title": "Commercial Contract",
"recipients": [
{
"id": 144,
"name": "John Doe",
"email": "john.doe@company.com"
}
],
"prefillFields": [
{
"id": 526,
"type": "text",
"label": "Account Number",
"value": "12323123"
}
]
}
```
The generated document will have the "Account Number" field already completed with the value `12323123`.
#### Make the field read-only
If you want the signer **not to be able to modify** the pre-filled value:
1. In the template editor at app.legaldoc.io, select the field, go to **advanced settings**
2. Enable the **"Read only"** option in the field properties
3. Save the template
This way, the field will appear pre-filled and locked for editing.
---
## Step 4: Send the Document
Activate the document for signing.
### Request
```http
POST https://app.legaldoc.io/api/v1/documents/153/send
```
### Response
```json
{
"message": "Document sent for signing successfully",
"id": 153,
"status": "PENDING",
"recipients": [
{
"id": 174,
"name": "John Doe",
"email": "john.doe@company.com",
"token": "abc123XYZ",
"signingUrl": "https://app.legaldoc.io/sign/abc123XYZ"
}
]
}
```
---
## Step 5: Embedded Widget
### 5.1 Include the Script
```html
```
### 5.2 Add the Component
```html
```
### Available Attributes
| Attribute | Type | Description |
| ------------------ | ------- | --------------------------------- |
| `token` | string | **Required.** Signer token |
| `host` | string | Legaldoc.io URL |
| `lockName` | boolean | Locks the name field |
| `lockEmail` | boolean | Locks the email field |
| `darkModeDisabled` | boolean | Disables dark mode |
| `css` | string | CSS styles for the iframe |
### 5.3 Angular Example
**Template:**
```html
```
**Component:**
```typescript
@Component({
selector: 'app-sign-document',
templateUrl: './sign-document.component.html'
})
export class SignDocumentComponent implements OnChanges, AfterViewInit {
@Input() companyData: any;
legaldocToken: string = '';
constructor(private _cdr: ChangeDetectorRef) {}
ngOnChanges(changes: SimpleChanges): void {
if (changes['companyData']?.currentValue?.token) {
this.legaldocToken = changes['companyData'].currentValue.token;
this._cdr.detectChanges();
setTimeout(() => this.configureLegaldocComponent(), 200);
}
}
ngAfterViewInit(): void {
if (this.companyData?.token) {
this.legaldocToken = this.companyData.token;
setTimeout(() => this.configureLegaldocComponent(), 100);
}
}
private configureLegaldocComponent(): void {
const element = document.getElementById('legaldoc-component') as any;
if (element) {
element.darkModeDisabled = true;
element.lockName = true;
element.lockEmail = true;
element.cssVars = {
background: '#ffffff',
foreground: '#2c3e50',
primary: '#60B22E'
};
}
}
}
```
### 5.4 React Example
```jsx
export const SignDocument = ({ token }) => {
const widgetRef = useRef(null);
useEffect(() => {
// Load Legaldoc script
const script = document.createElement('script');
script.src = 'https://cdn.legaldoc.io/v1.0/embed.js';
script.async = true;
document.body.appendChild(script);
return () => document.body.removeChild(script);
}, []);
useEffect(() => {
if (!token || !widgetRef.current) return;
const element = widgetRef.current;
element.darkModeDisabled = true;
element.lockName = true;
element.lockEmail = true;
element.cssVars = {
background: '#ffffff',
foreground: '#2c3e50',
primary: '#60B22E',
};
element.onDocumentCompleted = () => {
console.log('Document signed successfully');
};
}, [token]);
if (!token) return Loading...
;
return (
);
};
```
---
## Widget Customization
### CSS Variables
```javascript
element.cssVars = {
background: '#ffffff', // Background
foreground: '#2c3e50', // Text
primary: '#60B22E', // Primary color (buttons)
};
```
### Events
| Event | Description |
| --------------------- | --------------------------- |
| `onDocumentReady` | Document ready for signing |
| `onDocumentCompleted` | Signature completed |
| `onDocumentError` | Error in the process |