# Upload
Source: https://docs.iinkedsign.com/v4/api/files/upload
POST /files/upload
Upload one or more files to be signed. Save the returned `fileId` or `externalId` for use in future API requests.
Post the raw file (do not convert to base64) with a `Content-Type` of `application/pdf` for PDF or `application/octet-stream` for DOCX.
You must add a `Content-Disposition` header with the filename to allow any of the supported file conversions to PDF.
## Request
```http Request theme={null}
POST /files/upload
Content-Type: multipart/form-data
Content-Disposition: form-data; filename="document.pdf"
Content-Type: application/pdf
```
```http Request highlight={5} theme={null}
POST /files/upload
Content-Type: multipart/form-data
Content-Disposition: form-data; filename="document.docx"
Content-Type: application/octet-stream
```
```http Request highlight={4} theme={null}
POST /files/upload
Content-Type: multipart/form-data
Content-Disposition: form-data; filename*=UTF-8''r%C3%A9sum%C3%A9.pdf
Content-Type: application/pdf
```
### Query parameters
| Value | Description |
| :-------- | :----------------------------------------------------------------------------------------- |
| temporary | The file will be stored temporarily and deleted if not added to a package within 24 hours. |
Provide an external ID that can be used to reference the file.
This `externalId` will be stored with the document during `packages/add` request. It will then be included in future:
* `packages/status` requests
* `document` webhook events
If a user replaces a document after the package was created the `externalId` will no longer be associated with the document.
## Response
List of uploaded files with their statuses.
Unique identifier for the uploaded file.
External system identifier for the file, if available.
Original filer name of the uploaded file.
Indicates if the file is invalid or corrupted.
Indicates if the file was successfully converted to the required format.
Indicates if the file type is not supported.
Indicates if the file is password protected.
Error code or message related to the file upload or processing.
Additional message or details about the file status.
Type of stored file.
| Value | Description |
| :-------- | :----------------------------------------------------------------------------------------- |
| temporary | The file will be stored temporarily and deleted if not added to a package within 24 hours. |
## Errors
**PDF Error: PDF header not found.**
If a `PDF Error: PDF header not found.` error is returned, make sure you
are sending the file as binary data.
## Notes
**Encoding filename using UTF-8**
Replace filename (ISO-8859-1) in Content-Disposition header with filename\*=UTF-8''
* Place two separate single quotes after the UTF-8, not one double quote.
* You must URL Encode the filename to escape the UTF-8 characters and any whitespaces.
* Do not wrap the encoded filename with double quotes.
* Do not add a semicolon after the encoded filename.
**Example**
résumé.pdf `filename*=UTF-8''r%C3%A9sum%C3%A9.pdf`
For more information, refer to [RFC 5987](https://tools.ietf.org/html/rfc5987)
# Edit
Source: https://docs.iinkedsign.com/v4/api/links/edit
POST /packages/{packageId}/link/edit
Generate a secure link to allow editing of a package without requiring authentication.
You will have to refresh the package edit link before it expires. The link is short lived for security reasons.
## Request
```http Request theme={null}
POST /packages/{packageId}/link/edit
```
### Parameters
The unique identifier of the package you want to generate an edit link for.
## Response
Unique identifier of the package the link was generated for.
Display name for of the package the link was generated for.
URL that grants access to the package.
Type of link returned.
Token generated to provide access to the package.
Timestamp when the link expires (ISO 8601 format).
### Examples
```json Response (200) theme={null}
{
"name": "Signing",
"link": "https://sign.syngrafii.com/link/6iC4sCyjRaMTm2FcMjwIVA",
"type": "package_edit",
"token": "6iC4sCyjRaMTm2FcMjwIVA",
"timeExpires": "2021-08-10T15:40:51.7746401Z",
"packageId": "581aa1e0-49ea-4e49-841a-a74050e7d776"
}
```
# Sign
Source: https://docs.iinkedsign.com/v4/api/links/sign
POST /packages/{packageId}/link/sign/{signerId}
Generate a secure link to allow a signer to sign a package without requiring authentication.
If multi-factor authentication is enabled for the signer, they will be prompted to complete the second factor after accessing the link.
## Request
```http Request theme={null}
POST /packages/{packageId}/link/sign/{signerId}
```
### Parameters
The unique identifier of the package you want to generate a sign link for.
The unique identifier of the signer you want to generate a sign link for.
## Response
Unique identifier of the package the link was generated for.
Display name for of the package the link was generated for.
URL that grants access to the package.
Type of link returned.
Token generated to provide access to the package.
Timestamp when the link expires (ISO 8601 format).
### Examples
```json Response (200) theme={null}
{
"name": "Signing",
"link": "https://sign.syngrafii.com/link/6iC4sCyjRaMTm2FcMjwIVA",
"type": "package_sign",
"token": "6iC4sCyjRaMTm2FcMjwIVA",
"timeExpires": "2021-08-10T15:40:51.7746401Z",
"packageId": "581aa1e0-49ea-4e49-841a-a74050e7d776"
}
```
# Download
Source: https://docs.iinkedsign.com/v4/api/masterfile/download
GET /masterfiles/{packageId}/pdf/download
This endpoint will generate a MasterFile with all signers personally identifiable information (PII) included.
If you want more control over the content included in the MasterFile consider using the [MasterFile export API](/v4/api/masterfile/export) endpoint instead.
## Request
```http Request theme={null}
GET /masterfiles/{packageId}/pdf/download
```
### Parameters
The unique identifier of the package you want to download MasterFile for.
## Response
Returns a PDF file of the requested package's MasterFile.
```http Response theme={null}
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; name="example.pdf";filename*=utf-8''example.pdf
```
# Export
Source: https://docs.iinkedsign.com/v4/api/masterfile/export
POST /masterfiles/export/pdf
You can export a customized version of the MasterFile PDF through the `masterfiles/export/pdf` endpoint.
MasterFile export allows you to control the included sections, PII, as well as filtering sections to include or exclude specific record types.
## Request
```http Request expandable theme={null}
POST /masterfiles/export/pdf
{
"packageId": "245f9562-7ddc-4d38-9e61-2d75b0774af9",
"signerId": null,
"options": {
"details": {
"include": true,
"maps": false,
"counts": true
},
"host": null,
"signers": {
"include": true,
"name": true,
"email": false,
"mobileNumber": false,
"device": false,
"ipAddress": false,
"location": false,
"verification": {
"include": true,
"passed": true,
"failed": true,
"errored": false,
"analysis": true,
"data": true,
"identity": true,
"documents": {
"include": true,
"includeTypes": [
"drivers_license",
"passport"
],
"images": {
"include": true,
"includeTypes": [
"live_photo"
]
}
}
}
},
"recipients": {
"include": false
},
"documents": {
"include": true
},
"meetings": null,
"verificationHistory": {
"include": false
},
"accessHistory": {
"include": false
},
"packageHistory": {
"include": true,
"excludeTypes": [
"package_added"
]
},
"notificationHistory": {
"include": false
},
"logs": {
"include": true,
"excludeTypes": [
"field_digitalsignature_add",
"page_enter",
"page_exit"
]
}
}
}
```
### Body
Unique package ID of the package to export MasterFile for.
Generates the MasterFile for the specified signer ID, hiding other signers' PII and including the specified signer's PII based on the export options.
If not provided, the MasterFile will include all signers' PII based on the export options.
Overrides the default package or organization's time zone.
IANA Time Zones: [https://www.iana.org/time-zones](https://www.iana.org/time-zones)
When set to true the export options will not be merged with the default MasterFile export options. This is useful if you do not want new sections to automatically appear in future releases.
Options to customize how the MasterFile PDF is generated during export.
Include details section.
Include field counts summaries.
Include location maps. (requires location)
Include link in footer that can be used to request viewing the MasterFile online.
Include host section.
Include name.
Include email.
Include mobile number.
Include device details.
Include IP address.
include location details.
Include verification section
Include verification ID in verification summary
Include verification results that have passed
Include verification results that have failed
Include verification results that were not processed due to an error
Include result analysis section
Include result identity section
Include result data section
Include verification documents
Include by Verification Document Type
| Key | Description |
| ---------------- | ---------------------------------------------------- |
| drivers\_license | Driver's License |
| health\_card | Health Card |
| identity\_card | Identity Card |
| military\_id | Military ID |
| other | Other (Returned when document type detection failed) |
| passport | Passport |
| resident\_card | Resident Card |
| travel\_document | Travel Document |
| visa | Visa |
| voter\_id | Voter ID |
Exclude by Verification Document Type
| Key | Description |
| ---------------- | ---------------------------------------------------- |
| drivers\_license | Driver's License |
| health\_card | Health Card |
| identity\_card | Identity Card |
| military\_id | Military ID |
| other | Other (Returned when document type detection failed) |
| passport | Passport |
| resident\_card | Resident Card |
| travel\_document | Travel Document |
| visa | Visa |
| voter\_id | Voter ID |
Include verification document images
Include by Verification Document Image Type
| Key | Description |
| ----------- | ------------------------------------------------------------------------------ |
| live\_photo | Selfie of signer captured during live selfie process of document verification. |
| front | Front image of document captured during document verification. |
| back | Back image of document captured during document verification. |
| passport | Image of passport captured during document verification. |
Exclude by Verification Document Image Type
| Key | Description |
| ----------- | ------------------------------------------------------------------------------ |
| live\_photo | Selfie of signer captured during live selfie process of document verification. |
| front | Front image of document captured during document verification. |
| back | Back image of document captured during document verification. |
| passport | Image of passport captured during document verification. |
Include signers section.
Include name.
Include email.
Include mobile number.
Include device details.
Include IP address.
include location details.
Include verification section
Include verification ID in verification summary
Include verification results that have passed
Include verification results that have failed
Include verification results that were not processed due to an error
Include result analysis section
Include result identity section
Include result data section
Include verification documents
Include by Verification Document Type
| Key | Description |
| ---------------- | ---------------------------------------------------- |
| drivers\_license | Driver's License |
| health\_card | Health Card |
| identity\_card | Identity Card |
| military\_id | Military ID |
| other | Other (Returned when document type detection failed) |
| passport | Passport |
| resident\_card | Resident Card |
| travel\_document | Travel Document |
| visa | Visa |
| voter\_id | Voter ID |
Exclude by Verification Document Type
| Key | Description |
| ---------------- | ---------------------------------------------------- |
| drivers\_license | Driver's License |
| health\_card | Health Card |
| identity\_card | Identity Card |
| military\_id | Military ID |
| other | Other (Returned when document type detection failed) |
| passport | Passport |
| resident\_card | Resident Card |
| travel\_document | Travel Document |
| visa | Visa |
| voter\_id | Voter ID |
Include verification document images
Include by Verification Document Image Type
| Key | Description |
| ----------- | ------------------------------------------------------------------------------ |
| live\_photo | Selfie of signer captured during live selfie process of document verification. |
| front | Front image of document captured during document verification. |
| back | Back image of document captured during document verification. |
| passport | Image of passport captured during document verification. |
Exclude by Verification Document Image Type
| Key | Description |
| ----------- | ------------------------------------------------------------------------------ |
| live\_photo | Selfie of signer captured during live selfie process of document verification. |
| front | Front image of document captured during document verification. |
| back | Back image of document captured during document verification. |
| passport | Image of passport captured during document verification. |
Include signers by ID.
Exclude signers by ID.
Include by signers by role(s).
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Exclude by signers by role(s).
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Include by signers by type(s).
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
Exclude by signers by type(s).
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
Include recipients section.
Include name.
Include email.
Include mobile number.
Include device details.
Include IP address.
include location details.
Include recipients by ID.
Exclude recipients by ID.
Include by recipients by type(s).
| Value | Description |
| :---- | :------------------------------------------------------------- |
| cc | Recipient that will be **CC** on package email notifications. |
| bcc | Recipient that will be **BCC** on package email notifications. |
Exclude by recipients by type(s).
| Value | Description |
| :---- | :------------------------------------------------------------- |
| cc | Recipient that will be **CC** on package email notifications. |
| bcc | Recipient that will be **BCC** on package email notifications. |
Include documents section.
Include meetings section.
Include verification history section.
Include access history section.
Include access history by action(s).
| Value | Description |
| :-------------------- | :------------------------------------------------------------------------------- |
| access\_challenged | Signer was issued MFA challenge |
| access\_failed | Signer failed MFA attempt |
| access\_lockout | Signer failed MFA attempt multiple times in a row and was temporarily locked out |
| document\_opened | Signer opened document |
| meeting\_joined | Signer joined VSR meeting |
| mobile\_started | Signer started mobile signature pad session |
| session\_started | Signer started signing session |
| verification\_started | Signer started verification session |
Exclude access history by action(s).
| Value | Description |
| :-------------------- | :------------------------------------------------------------------------------- |
| access\_challenged | Signer was issued MFA challenge |
| access\_failed | Signer failed MFA attempt |
| access\_lockout | Signer failed MFA attempt multiple times in a row and was temporarily locked out |
| document\_opened | Signer opened document |
| meeting\_joined | Signer joined VSR meeting |
| mobile\_started | Signer started mobile signature pad session |
| session\_started | Signer started signing session |
| verification\_started | Signer started verification session |
Include access history by type(s).
| Value | Description |
| :----------- | :---------------------------------- |
| meeting | VSR meeting access history |
| mobile | Mobile signature pad access history |
| security | MFA access history |
| session | Signing session access history |
| verification | Verification session access history |
Exclude access history by type(s).
| Value | Description |
| :----------- | :---------------------------------- |
| meeting | VSR meeting access history |
| mobile | Mobile signature pad access history |
| security | MFA access history |
| session | Signing session access history |
| verification | Verification session access history |
Include package history section.
Include package history by type(s).
| Value | Description |
| :----------------------------------------------- | :------------------------------------------------------------------------------------------- |
| document\_added | Document was added |
| document\_deleted | Document was deleted |
| document\_regen | Document was regenerated after changes |
| document\_regen\_signed | Signed document was regenerated after changes requiring signer(s) to sign the document again |
| document\_updated | Document was modified |
| document\_updated\_template | Document template was updated |
| document\_updated\_template\_annotation\_added | Package owner added annotation to document |
| document\_updated\_template\_annotation\_deleted | Package owner deleted annotation from document |
| document\_updated\_template\_annotation\_updated | Package owner updated annotation in document |
| master\_file\_exported | MasterFile was exported by organization member |
| meeting\_added | VSR meeting was scheduled |
| meeting\_deleted | VSR meeting was cancelled |
| meeting\_updated | VSR meeting was updated |
| meeting\_video\_deleted | VSR video was deleted |
| package\_added | Package was added |
| package\_deleted | Package was deleted |
| package\_passphrase | MFA passphrase was added to package |
| package\_sent | Package was sent to signer |
| package\_updated | Package was updated |
| recipient\_added | Recipient was added |
| recipient\_deleted | Recipient was deleted |
| recipient\_updated | Recipient was updated |
| signer\_added | Signer was added |
| signer\_deleted | Signer was deleted |
| signer\_updated | Signer was updated |
| verification\_viewed | Verification was viewed by organization member |
Exclude package history by type(s).
| Value | Description |
| :----------------------------------------------- | :------------------------------------------------------------------------------------------- |
| document\_added | Document was added |
| document\_deleted | Document was deleted |
| document\_regen | Document was regenerated after changes |
| document\_regen\_signed | Signed document was regenerated after changes requiring signer(s) to sign the document again |
| document\_updated | Document was modified |
| document\_updated\_template | Document template was updated |
| document\_updated\_template\_annotation\_added | Package owner added annotation to document |
| document\_updated\_template\_annotation\_deleted | Package owner deleted annotation from document |
| document\_updated\_template\_annotation\_updated | Package owner updated annotation in document |
| master\_file\_exported | MasterFile was exported by organization member |
| meeting\_added | VSR meeting was scheduled |
| meeting\_deleted | VSR meeting was cancelled |
| meeting\_updated | VSR meeting was updated |
| meeting\_video\_deleted | VSR video was deleted |
| package\_added | Package was added |
| package\_deleted | Package was deleted |
| package\_passphrase | MFA passphrase was added to package |
| package\_sent | Package was sent to signer |
| package\_updated | Package was updated |
| recipient\_added | Recipient was added |
| recipient\_deleted | Recipient was deleted |
| recipient\_updated | Recipient was updated |
| signer\_added | Signer was added |
| signer\_deleted | Signer was deleted |
| signer\_updated | Signer was updated |
| verification\_viewed | Verification was viewed by organization member |
Include notification history section.
Include notification history by template(s).
| Value | Description |
| :---------------------------- | :------------------------------------------------------------------- |
| document\_accessed | Document was opened by signer |
| document\_executed | Document was executed by all signers |
| document\_executed\_all | All documents were executed by all signers |
| document\_next | Next signer in a sequential signing |
| document\_reminder | Reminder to sign document(s) |
| document\_signed | Document signed by signer |
| mobile\_link | Link to open mobile signature pad |
| package\_cancelled | Signing package was cancelled |
| package\_executed | Signing package was executed by all signers |
| package\_masterfile\_link | MasterFile link was requested and sent to signer's email address |
| package\_meeting | VSR meeting was scheduled |
| package\_meeting\_cancelled | VSR meeting was cancelled |
| package\_notification | Custom signing package notification was sent to signer |
| package\_notification\_failed | Delivery failure notification sent to package owner |
| package\_review\_link | Package review link was requested and sent to signer's email address |
| package\_sign | Signing package sign document(s) request sent to signer |
| package\_updated | Signing package has been updated |
| security\_code | MFA security code has been sent to signer's mobile number |
| verification\_completed | Signer completed IDV |
| verification\_failed | Signer failed IDV |
| verification\_link | Link to open IDV |
Exclude notification history by template(s).
| Value | Description |
| :---------------------------- | :------------------------------------------------------------------- |
| document\_accessed | Document was opened by signer |
| document\_executed | Document was executed by all signers |
| document\_executed\_all | All documents were executed by all signers |
| document\_next | Next signer in a sequential signing |
| document\_reminder | Reminder to sign document(s) |
| document\_signed | Document signed by signer |
| mobile\_link | Link to open mobile signature pad |
| package\_cancelled | Signing package was cancelled |
| package\_executed | Signing package was executed by all signers |
| package\_masterfile\_link | MasterFile link was requested and sent to signer's email address |
| package\_meeting | VSR meeting was scheduled |
| package\_meeting\_cancelled | VSR meeting was cancelled |
| package\_notification | Custom signing package notification was sent to signer |
| package\_notification\_failed | Delivery failure notification sent to package owner |
| package\_review\_link | Package review link was requested and sent to signer's email address |
| package\_sign | Signing package sign document(s) request sent to signer |
| package\_updated | Signing package has been updated |
| security\_code | MFA security code has been sent to signer's mobile number |
| verification\_completed | Signer completed IDV |
| verification\_failed | Signer failed IDV |
| verification\_link | Link to open IDV |
Include notification history by type(s).
| Value | Description |
| :---- | :----------------- |
| email | Email notification |
| sms | SMS notification |
Exclude notification history by type(s).
| Value | Description |
| :---- | :----------------- |
| email | Email notification |
| sms | SMS notification |
Include signing logs section.
Include signing logs by type(s).
| Value | Description |
| :------------------------------ | :------------------------------------------------- |
| document\_opened | Document opened |
| document\_saved | Document saved |
| document\_finalized | Document finalized |
| page\_enter | Page entered |
| page\_exit | Page exited |
| field\_annotation\_add | Annotation field added (free form ink annotations) |
| field\_checkbox\_check | Checkbox field checked |
| field\_checkbox\_uncheck | Checkbox field unchecked |
| field\_date\_add | Date field added |
| field\_date\_delete | Date field deleted |
| field\_digitalsignature\_add | Digital Signature field added |
| field\_digitalsignature\_delete | Digital Signature field deleted |
| field\_dropdown\_delete | Dropdown field deleted |
| field\_dropdown\_select | Dropdown field selected |
| field\_image\_add | Image field added |
| field\_image\_delete | Image field deleted |
| field\_initials\_add | Initials added |
| field\_initials\_delete | Initials deleted |
| field\_radio\_select | Radio field selected |
| field\_signature\_add | Signature field added |
| field\_signature\_delete | Signature field deleted |
| field\_stamp\_add | Stamp field added |
| field\_text\_add | Text field added |
| field\_text\_delete | Text field deleted |
Exclude signing logs by type(s).
| Value | Description |
| :------------------------------ | :------------------------------------------------- |
| document\_opened | Document opened |
| document\_saved | Document saved |
| document\_finalized | Document finalized |
| page\_enter | Page entered |
| page\_exit | Page exited |
| field\_annotation\_add | Annotation field added (free form ink annotations) |
| field\_checkbox\_check | Checkbox field checked |
| field\_checkbox\_uncheck | Checkbox field unchecked |
| field\_date\_add | Date field added |
| field\_date\_delete | Date field deleted |
| field\_digitalsignature\_add | Digital Signature field added |
| field\_digitalsignature\_delete | Digital Signature field deleted |
| field\_dropdown\_delete | Dropdown field deleted |
| field\_dropdown\_select | Dropdown field selected |
| field\_image\_add | Image field added |
| field\_image\_delete | Image field deleted |
| field\_initials\_add | Initials added |
| field\_initials\_delete | Initials deleted |
| field\_radio\_select | Radio field selected |
| field\_signature\_add | Signature field added |
| field\_signature\_delete | Signature field deleted |
| field\_stamp\_add | Stamp field added |
| field\_text\_add | Text field added |
| field\_text\_delete | Text field deleted |
## Response
Returns a PDF file of the requested package's MasterFile based on the provided options.
```http Response theme={null}
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; name="example.pdf";filename*=utf-8''example.pdf
```
# Get
Source: https://docs.iinkedsign.com/v4/api/masterfile/get
GET /masterfiles/{packageId}
This returns the full MasterFile object.
Parsing the MasterFile JSON is not recommended as the structure is complex and is subject to change over time.
## Request
```http Request theme={null}
GET /masterfiles/{packageId}
```
### Parameters
The unique identifier of the package you want to download MasterFile for.
# Download
Source: https://docs.iinkedsign.com/v4/api/masterfile/signer/download
GET /masterfiles/{packageId}/signer/{signerId}/pdf/download
This endpoint will generate a MasterFile for the specified signer, all other signers' sensitive personally identifiable information (PII) will be nulled out. If the signer is also the package owner they will still see all signers' PII. If the signer is not the package owner they will only see their own PII. This is useful when sharing MasterFile data with signers while keeping other signers' PII private.
### PII not shared when using `/signer/{signerId}` endpoint:
* Mobile Number
* Device
* IP Address
* Location (Address, Latitude, and Longitude)
If you want more control over the content included in the MasterFile consider using the [MasterFile export API](/v4/api/masterfile/export) endpoint instead.
## Request
```http Request theme={null}
GET /masterfiles/{packageId}/signer/{signerId}/pdf/download
```
### Parameters
The unique identifier of the package you want to download MasterFile for.
The unique identifier of the signer you want to download MasterFile as.
## Response
Returns a PDF file of the requested package's MasterFile for the specified signer.
```http Response theme={null}
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; name="example.pdf";filename*=utf-8''example.pdf
```
# Get
Source: https://docs.iinkedsign.com/v4/api/masterfile/signer/get
GET /masterfiles/{packageId}/signer/{signerId}
This returns the full MasterFile object for the specified signer, all other signers' sensitive personally identifiable information (PII) will be nulled out. If the signer is also the package owner they will still see all signers' PII. If the signer is not the package owner they will only see their own PII. This is useful when sharing MasterFile data with signers while keeping other signers' PII private.
Parsing the MasterFile JSON is not recommended as the structure is complex and is subject to change over time.
## Request
```http Request theme={null}
GET /masterfiles/{packageId}/signer/{signerId}
```
### Parameters
The unique identifier of the package you want to download MasterFile for.
The unique identifier of the signer you want to download MasterFile as.
# Add
Source: https://docs.iinkedsign.com/v4/api/packages/add
POST /packages/add
The `/packages/add` endpoint allows you to create a new package within the application.
A package typically contains one or more documents and signers who are required to review and sign those documents.
In production it is recommended to upload files using the [Files upload API](/v4/api/files/upload) and reference them by `fileId` when adding your documents to a package.
## Request
```http Request highlight={4} theme={null}
POST /packages/add
{
"name": "New Package",
"type": "concurrent",
"signers": [
{
"firstName": "Signer",
"lastName": "One",
"email": "signer.one@example.com"
}
],
"documents": [
{
"fileName": "agreement.pdf",
"fileId": "d29e25e0-624b-4adb-b118-19c4d0125e5e"
}
]
}
```
```http Request highlight={4} theme={null}
POST /packages/add
{
"name": "New Package",
"type": "Sequential",
"signers": [
{
"firstName": "Signer",
"lastName": "One",
"email": "signer.one@example.com"
},
{
"firstName": "Signer",
"lastName": "Two",
"email": "signer.two@example.com"
}
],
"documents": [
{
"fileName": "agreement.pdf",
"fileId": "d29e25e0-624b-4adb-b118-19c4d0125e5e"
}
]
}
```
```http Request highlight={4,6-7,14} theme={null}
POST /packages/add
{
"name": "New Package",
"type": "video_closing_room",
"meeting": {
"timeStart": "2024-12-01T15:00:00Z",
"duration": "PT1H"
},
"signers": [
{
"firstName": "Host",
"lastName": "One",
"email": "host.one@example.com",
"role": "host"
},
{
"firstName": "Signer",
"lastName": "One",
"email": "signer.one@example.com",
"role": "signer"
}
{
"firstName": "Signer",
"lastName": "Two",
"email": "signer.two@example.com",
"role": "signer"
}
],
"documents": [
{
"fileName": "agreement.pdf",
"fileId": "d29e25e0-624b-4adb-b118-19c4d0125e5e"
}
]
}
```
When using templating tags in a document for a video signing room the host should be referenced as `{{signer_host:signature_1}}`, and the first signer will be referenced as `{{signer_1:signature_1}}`.
See the [Package options guide](/v4/guides/package-options#video-signing-room) for more information.
```http Request highlight={4,10} theme={null}
POST /packages/add
{
"name": "New Package",
"type": "Live Session",
"signers": [
{
"firstName": "Signer",
"lastName": "Host",
"email": "signer.host@example.com",
"role": "host"
},
{
"firstName": "Signer",
"lastName": "One",
"email": "signer.one@example.com"
}
{
"firstName": "Signer",
"lastName": "Two",
"email": "signer.two@example.com"
}
],
"documents": [
{
"fileName": "agreement.pdf",
"fileId": "d29e25e0-624b-4adb-b118-19c4d0125e5e"
}
]
}
```
When creating an In Person package you need to specify which signer is the host. The host will be the only signer that will receive a notification to sign the package.
### Body
Name of the package.
Description of the package.
Message to be shared with all signers.
Type of package signing workflow.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
State of the package.
| Value | Description |
| :----- | :------------------------------------------------------------------------------------------------ |
| open | Package is ready for signing, notifications will be sent to signers (if enabled). `default` |
| draft | Package is not ready to be sent and will appear under Drafts. |
| add | Use when embedding the package editor to provide an experience similar to creating a new package. |
| select | Use when embedding the package editor to let users choose a signing workflow type. |
Category of the package.
Client number associated with the package.
Matter number associated with the package.
Date by which the document should be signed. After this date, the package will expire and can no longer be signed unless extended.
If not specified, the default value is 7 days from the current date.
The date should be in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
Details about the meeting associated with the package.
This is only applicable for packages with the `video_closing_room` signing workflow type.
Start time of the meeting in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.
Duration of the meeting in ISO 8601 format: `PT1H30M`.
Locale to create the package in.
If not provided, the package will be created in the organization's default locale.
| Value | Description |
| :---- | :---------- |
| en | English |
| fr | français |
| de | Deutsch |
| es | Español |
Member ID to create the package under.
If not provided, the package will be created under the current member.
You require `Sign Editor` or `Package Editor` role to create a package on behalf of another member.
Team ID to create the package under.
If not provided, the package will be created under the given member, or under the current member if none is provided.
Folder ID to create the package under.
If not provided, the package will be created in the root folder.
Set to `true` to return links for integrating document signing workflows.
See the [Embed signing guide](/v4/guides/embed-signing) for more information.
Set to `true` to return a link for integrating document editing workflows.
See the [Embed editor guide](/v4/guides/embed-editor) for more information.
Additional options for the package.
Enable embedded signing mode.
Embed options used to customize the embedded package editor.
2.8
User can only save changes to draft packages; the user will not be able to send it.
User will not be allowed to modify package properties.
User will not be allowed to modify package verification properties.
User will not be allowed to modify package signers.
User will not be allowed to modify package documents.
User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.
The first document will be focused when the package editor is loaded instead of the package properties.
User will be redirected back to the returnUrl when they are done editing the package.
Will be included in a `state` query string parameter appended to the `returnUrl`.
Show custom brand when signing package.
1.10
Add document identifier to each page (QR code).
Allow VSR participants to review documents before a meeting via a Review Documents link added to email meeting invitation.
2.6
Allow signers to forward the signing to another email address.
4.0
Enabled to not share email addresses between signers.
2.11
Supported in the following package types:
* Concurrent (`concurrent`)
* Sequential (`Sequential`)
* Group Send (`Counterparts`)
Do not allow signers to fill AcroForm fields during signing.
3.3
Do not allow signers to modify AcroForm fields during signing.
3.6
Control how Acroform fields are flattened after signing a document.
2.6
| Value | Description |
| :----- | :----------------------------------- |
| none | Do not flatten fields |
| filled | Flatten only fields filled by signer |
| all | Flatten all fields `default` |
Override the default ink color `#0000FF` for Ink to Sign signatures and initials with a valid #-hexadecimal RGB color value.
2.10
Set preferred default mark type.
4.0
| Value | Description |
| :-------------- | :---------- |
| touch\_to\_sign | iink It |
| type\_to\_sign | Type It |
| click\_to\_sign | Accept It |
Add a retention period to the package to prevent deletion. (ISO 8601 duration)
1.11
Override system messages by message key. Each value contains an optional
`default` string and an optional `locale` map of locale codes to strings.
Values are limited to 1,024 characters and cannot contain website domains or
email addresses.
3.6
Add custom consent notice text by consent type: `signing`, `verification`, or
`video_recording`. Each value contains an optional `default` string and an
optional `locale` map of locale codes to strings. Custom text is appended to
the system notice, supports locale fallback, is limited to 1,024 characters,
and cannot contain website domains or email addresses.
4.2
Parse document for templating tags. Defaults to true.
Parse merger data templating tags. Defaults to false.
4.0
Control how unused signer tags are handled.
2.6
| Value | Description |
| :----- | :------------------------------- |
| keep | Leave unused tags in document |
| hide | Move unused tags to hidden layer |
| remove | Remove unused tags `default` |
Control which document(s) within a package have the CAC page appended to them.
3.2
| Value | Description |
| :-------------- | :---------------------------------- |
| document\_all | Append to all documents in package |
| document\_first | Append to first document in package |
| document\_last | Append to last document in package |
When enabled will add a signer identification placeholder for each signer on the CAC page.
3.2
Add a custom disclaimer to the top of the Compliance Audit Certificate.
1.10
Enabled 2FA security code.
All signers will require a valid mobile phone number to enable mobile MFA.
Enabled 2FA security passphrase.
You must also set a passphrase as part of add or update request to enabled 2FA security passphrase.
```json theme={null}
{
"options": {
"securityPassphrase": true,
...
},
"securityPassphrase": "mySecretPassphrase"
}
```
Enable all mark types.
Enabled click to sign `Accept It`.
Enabled type to sign `Type It`.
Enabled touch to sign `Ink It`.
Allows signer to use desktop mouse to draw signature via touch to sign.
Allow signers to apply their last used iink signature during a signing session. Defaults to `false`.
4.1
Automatically starts video recording after host starts meeting and first attendee joins.
Disables video recording feature preventing host from recording signing session.
Add a retention period to all package videos to prevent deletion. (ISO 8601 duration)
1.11
Share meeting details and videos with guest signers via MasterFile.
Prevent all package notifications from being sent to signers. This option will override other notify options. This option will not prevent Document Accessed (notifyAccessed) notifications if enabled.
1.10.4
Set to false to not include signed documents as attachments in executed email notifications.
2.5
Send email notification to owner to confirm package was created.
Send email notification to owner whenever a signer opens a document (limited to once every hour).
Send email notification to each signer when it is their turn to sign.
Send email notification to each signer to notify them that they are waiting their turn to sign.
Send email notification to each signer when Video Signing Room meeting is scheduled.
Include ICS compatible meeting invitation with email notification to schedule meeting date and time in recipients' calendar.
Send email notification to signer after they sign each document.
2.5
For Sequential packages, the next signer notification is only sent after the current signer has signed all of their documents.
3.3
Send email to owner to notify them when all signers have signed each document.
Don't send document executed email until all documents in the package have been fully signed.
3.3
`Counterparts` Send document executed notification TO package owner and CC signer.
1.10
Send signers fully executed document with CAC page appended to end of document.
1.10
Send signers fully executed document without CAC page appended to end of document.
1.10
Send signers separated CAC page as an additional attachment.
1.10
Allow signer to add additional fields while signing documents. Customize signerTools to control what fields the signer can add.
Allow signer to delete any templated fields while signing a document. This is default behavior for VSR and In Person package types. It is recommended to use optional fields instead for Concurrent, Sequential, and Group Send package types.
2.10
Customize signer toolbar options.
Enable sign.
Enable annotations (ink) on mobile devices.
Enable annotations (ink) on desktop.
Enable text.
Enable note.
Enable forms.
Auto highlight form fields.
Enable image.
Request Signers Geolocation while signing documents, joining VSR meetings, performing IDV, and connecting to a mobile signature pad.
Customize how Geolocation is collected.
3.6
Require geolocation to be shared before allowing the signer to continue.
Require geolocation to be shared before the signer can sign documents.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can use signature pad.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can join VSR meetings.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can verify their identity.
(`required` must also be set to `true`)
Enable custom PDF security options.
2.10
Customize PDF security options.
2.10
Allow PDF merge operations.
Allow copying PDF content.
Allow only degraded PDF printing.
Allow PDF AcroForms fields to be filled in (when formFlattening option is not set to "all").
Allow PDF annotations.
Allow PDF editing.
Allow PDF printing.
Allow screen readers.
PDF security options are enforced only when the PDF is opened in a PDF viewer that supports the PDF security settings. Not all PDF viewers support these settings.
Configure consent requirements and automatic reuse.
4.2
Require the signer to provide consent before completing a configured consent
action. Defaults to `false`.
Require consent before signing. Defaults to `true`.
Require consent before video recording in a Video Signing Room package.
Defaults to `false`.
Reuse a member's previously accepted consent when the consent type and notice
version match and the acceptance occurred within this number of days. Defaults
to `90`. Set to `0` to disable automatic reuse.
Set identity verification options.
3.2
The policy ID of the custom Identity Verification Policy to use during signer identity verification. (Custom IDV policies currently must be created by our Support Team for your organization.)
The code of one of our standard Identity Verification Policy to use during signer identity verification.
| Policy Code | Pass-To-Sign | Region | Retries |
| :--------------------------------------- | :----------: | :----: | :-----: |
| trulioo3\_document | false | Any | 2 |
| trulioo3\_document\_required | true | Any | 2 |
| trulioo3\_document\_ca\_strict | false | CA | 2 |
| trulioo3\_document\_ca\_strict\_required | true | CA | 2 |
**Pass-To-Sign** indicates whether the signer must successfully complete identity verification before they can sign their documents.
Configure the digital signature types and providers available to signers.
4.2
Map each enabled digital signature type to an ordered list of provider names.
| Signature type | Description |
| :------------- | :----------------------------- |
| `qes` | Qualified Electronic Signature |
| Value | Provider |
| :------------ | :---------- |
| `digidentity` | Digidentity |
Provider availability depends on your subscription and organization configuration.
Set package `Remind Me Later` options.
4.0
Number of days, from today, to send a reminder notification to the package owner.
Message that will be sent with the reminder notification to package owner.
List of signers for the package.
User-defined identifier used to associate template tags with this signer.
See the [Signer tags guide](/v4/guides/template-tagging/signer-tags) for more information.
Signer's first name.
Signer's last name.
Signer's email. (used to send notifications)
Signer's mobile number. (used for 2FA and mobile signatures)
Role of signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Set to `true` to request signer identity verification.
Requires a verification policy to be assigned to package.
Set to `true` to include the signer in the CAC page.
List of recipients for the package.
Recipient's first name.
Recipient's last name.
Recipient's email. (used to send notifications)
Recipient's mobile number. (used for 2FA if enabled)
Type of recipient.
| Value | Description |
| :---- | :------------------------------------------------------------- |
| cc | Recipient that will be **CC** on package email notifications. |
| bcc | Recipient that will be **BCC** on package email notifications. |
List of documents for the package.
Friendly file name shown to signers. (defaults to `fileName` if not specified)
Filename including extension.
Base64 encoding of file.
URL of file. (must be https and publicly accessible)
Unique file ID of an existing file added via [Files upload API](/v4/api/files/upload.mdx).
Either `fileData`, `fileUrl`, or `fileId` is required. We recommend using `fileId` to avoid exceeding per request size limits.
The template collection that will be searched to automatically apply any matching templates.
Use this when you want to utilize auto-templates but do not know the specific template or document to apply. This will look for any matching auto-templates in the specified collection.
The full auto-template code `{templateCode}:{documentCode}` that will be used to automatically apply an existing auto-template document.
Use this when you know the specific auto-template and document you want to apply.
The template document ID to apply to this document.
Use this when you want to apply a specific document template from the template passed via `templateId` in the parent object.
Set of key/value pairs of data used to pre-populate templated fields with. The key must match a unique data ID assigned to a template field.
```json theme={null}
...
"templateData": {
"field1": "value1",
"field2": "value2"
},
...
```
## Response
Unique identifier for the package.
Full package object, returned when `returnPackage` is set to `true` on the request.
Unique identifier for the package.
Unique identifier for the organization that owns the package.
Identifier for the member who created/owns the package.
Team identifier associated with the package. (optional)
Folder identifier where the package is stored. (optional)
Set to `true` if the package is shared.
Current scheduled meeting ID for the package (if applicable).
ID of the template the package was created from (if applicable).
ID of the form the package was created from (if applicable).
ID of the API key used to create the package (if created via API key).
Display name of the package.
Category for the package. (optional)
Client reference number. (optional)
Matter reference number. (optional)
Description of the package. (optional)
Message included when the package was sent. (optional)
Message explaining why the package was rescinded. (optional)
Reminder message for signers. (optional)
Creation time (ISO 8601 date-time).
Reminder time (ISO 8601 date-time).
Retention expiry time (ISO 8601 date-time).
Time the package was rescinded (ISO 8601).
Time the package was deleted (ISO 8601).
Deadline for signing (ISO 8601 date-time).
Last modification time (ISO 8601 date-time).
Package options.
Enable embedded signing mode.
Embed options used to customize the embedded package editor.
2.8
User can only save changes to draft packages; the user will not be able to send it.
User will not be allowed to modify package properties.
User will not be allowed to modify package verification properties.
User will not be allowed to modify package signers.
User will not be allowed to modify package documents.
User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.
The first document will be focused when the package editor is loaded instead of the package properties.
User will be redirected back to the returnUrl when they are done editing the package.
Will be included in a `state` query string parameter appended to the `returnUrl`.
Show custom brand when signing package.
1.10
Add document identifier to each page (QR code).
Allow VSR participants to review documents before a meeting via a Review Documents link added to email meeting invitation.
2.6
Allow signers to forward the signing to another email address.
4.0
Enabled to not share email addresses between signers.
2.11
Supported in the following package types:
* Concurrent (`concurrent`)
* Sequential (`Sequential`)
* Group Send (`Counterparts`)
Do not allow signers to fill AcroForm fields during signing.
3.3
Do not allow signers to modify AcroForm fields during signing.
3.6
Control how Acroform fields are flattened after signing a document.
2.6
| Value | Description |
| :----- | :----------------------------------- |
| none | Do not flatten fields |
| filled | Flatten only fields filled by signer |
| all | Flatten all fields `default` |
Override the default ink color `#0000FF` for Ink to Sign signatures and initials with a valid #-hexadecimal RGB color value.
2.10
Set preferred default mark type.
4.0
| Value | Description |
| :-------------- | :---------- |
| touch\_to\_sign | iink It |
| type\_to\_sign | Type It |
| click\_to\_sign | Accept It |
Add a retention period to the package to prevent deletion. (ISO 8601 duration)
1.11
Override system messages by message key. Each value contains an optional
`default` string and an optional `locale` map of locale codes to strings.
Values are limited to 1,024 characters and cannot contain website domains or
email addresses.
3.6
Add custom consent notice text by consent type: `signing`, `verification`, or
`video_recording`. Each value contains an optional `default` string and an
optional `locale` map of locale codes to strings. Custom text is appended to
the system notice, supports locale fallback, is limited to 1,024 characters,
and cannot contain website domains or email addresses.
4.2
Parse document for templating tags. Defaults to true.
Parse merger data templating tags. Defaults to false.
4.0
Control how unused signer tags are handled.
2.6
| Value | Description |
| :----- | :------------------------------- |
| keep | Leave unused tags in document |
| hide | Move unused tags to hidden layer |
| remove | Remove unused tags `default` |
Control which document(s) within a package have the CAC page appended to them.
3.2
| Value | Description |
| :-------------- | :---------------------------------- |
| document\_all | Append to all documents in package |
| document\_first | Append to first document in package |
| document\_last | Append to last document in package |
When enabled will add a signer identification placeholder for each signer on the CAC page.
3.2
Add a custom disclaimer to the top of the Compliance Audit Certificate.
1.10
Enabled 2FA security code.
All signers will require a valid mobile phone number to enable mobile MFA.
Enabled 2FA security passphrase.
You must also set a passphrase as part of add or update request to enabled 2FA security passphrase.
```json theme={null}
{
"options": {
"securityPassphrase": true,
...
},
"securityPassphrase": "mySecretPassphrase"
}
```
Enable all mark types.
Enabled click to sign `Accept It`.
Enabled type to sign `Type It`.
Enabled touch to sign `Ink It`.
Allows signer to use desktop mouse to draw signature via touch to sign.
Allow signers to apply their last used iink signature during a signing session. Defaults to `false`.
4.1
Automatically starts video recording after host starts meeting and first attendee joins.
Disables video recording feature preventing host from recording signing session.
Add a retention period to all package videos to prevent deletion. (ISO 8601 duration)
1.11
Share meeting details and videos with guest signers via MasterFile.
Prevent all package notifications from being sent to signers. This option will override other notify options. This option will not prevent Document Accessed (notifyAccessed) notifications if enabled.
1.10.4
Set to false to not include signed documents as attachments in executed email notifications.
2.5
Send email notification to owner to confirm package was created.
Send email notification to owner whenever a signer opens a document (limited to once every hour).
Send email notification to each signer when it is their turn to sign.
Send email notification to each signer to notify them that they are waiting their turn to sign.
Send email notification to each signer when Video Signing Room meeting is scheduled.
Include ICS compatible meeting invitation with email notification to schedule meeting date and time in recipients' calendar.
Send email notification to signer after they sign each document.
2.5
For Sequential packages, the next signer notification is only sent after the current signer has signed all of their documents.
3.3
Send email to owner to notify them when all signers have signed each document.
Don't send document executed email until all documents in the package have been fully signed.
3.3
`Counterparts` Send document executed notification TO package owner and CC signer.
1.10
Send signers fully executed document with CAC page appended to end of document.
1.10
Send signers fully executed document without CAC page appended to end of document.
1.10
Send signers separated CAC page as an additional attachment.
1.10
Allow signer to add additional fields while signing documents. Customize signerTools to control what fields the signer can add.
Allow signer to delete any templated fields while signing a document. This is default behavior for VSR and In Person package types. It is recommended to use optional fields instead for Concurrent, Sequential, and Group Send package types.
2.10
Customize signer toolbar options.
Enable sign.
Enable annotations (ink) on mobile devices.
Enable annotations (ink) on desktop.
Enable text.
Enable note.
Enable forms.
Auto highlight form fields.
Enable image.
Request Signers Geolocation while signing documents, joining VSR meetings, performing IDV, and connecting to a mobile signature pad.
Customize how Geolocation is collected.
3.6
Require geolocation to be shared before allowing the signer to continue.
Require geolocation to be shared before the signer can sign documents.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can use signature pad.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can join VSR meetings.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can verify their identity.
(`required` must also be set to `true`)
Enable custom PDF security options.
2.10
Customize PDF security options.
2.10
Allow PDF merge operations.
Allow copying PDF content.
Allow only degraded PDF printing.
Allow PDF AcroForms fields to be filled in (when formFlattening option is not set to "all").
Allow PDF annotations.
Allow PDF editing.
Allow PDF printing.
Allow screen readers.
PDF security options are enforced only when the PDF is opened in a PDF viewer that supports the PDF security settings. Not all PDF viewers support these settings.
Configure consent requirements and automatic reuse.
4.2
Require the signer to provide consent before completing a configured consent
action. Defaults to `false`.
Require consent before signing. Defaults to `true`.
Require consent before video recording in a Video Signing Room package.
Defaults to `false`.
Reuse a member's previously accepted consent when the consent type and notice
version match and the acceptance occurred within this number of days. Defaults
to `90`. Set to `0` to disable automatic reuse.
Set identity verification options.
3.2
The policy ID of the custom Identity Verification Policy to use during signer identity verification. (Custom IDV policies currently must be created by our Support Team for your organization.)
The code of one of our standard Identity Verification Policy to use during signer identity verification.
| Policy Code | Pass-To-Sign | Region | Retries |
| :--------------------------------------- | :----------: | :----: | :-----: |
| trulioo3\_document | false | Any | 2 |
| trulioo3\_document\_required | true | Any | 2 |
| trulioo3\_document\_ca\_strict | false | CA | 2 |
| trulioo3\_document\_ca\_strict\_required | true | CA | 2 |
**Pass-To-Sign** indicates whether the signer must successfully complete identity verification before they can sign their documents.
Configure the digital signature types and providers available to signers.
4.2
Map each enabled digital signature type to an ordered list of provider names.
| Signature type | Description |
| :------------- | :----------------------------- |
| `qes` | Qualified Electronic Signature |
| Value | Provider |
| :------------ | :---------- |
| `digidentity` | Digidentity |
Provider availability depends on your subscription and organization configuration.
Set package `Remind Me Later` options.
4.0
Number of days, from today, to send a reminder notification to the package owner.
Message that will be sent with the reminder notification to package owner.
Set to `true` if the package is protected by a security passphrase.
Language/locale for the package.
Time zone for package date/time presentation.
Formatting options for dates and presentation.
Locale code used for formatting. (optional)
Inherits from the package locale if not specified.
Number of signed revisions across package documents.
Total number of revisions across package documents.
Restriction type applied to the package. (optional)
Set to `true` if the package was created via the API.
Package type identifier.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Current state of the package.
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
Arbitrary external data attached to the package.
Package version or timestamp (ISO 8601).
If the package is scheduled for a meeting, the meeting details.
Unique identifier for the meeting.
Organization associated with the meeting.
Package associated with the meeting.
Meeting start time (ISO 8601 date-time).
Meeting duration (ISO 8601 duration string).
Set to `true` if the meeting is private.
Meeting type identifier.
Current state of the meeting.
| Value | Description |
| :---------- | :------------------- |
| scheduled | Scheduled meeting. |
| rescheduled | Rescheduled meeting. |
| cancelled | Cancelled meeting. |
Documents that belong to the package.
Unique identifier for the document.
Identifier of the package this document belongs to.
Unique identifier for the file associated with the document.
Auto-template identifier (if created from an auto-template).
Auto-template document identifier (if applicable).
External identifier for the document. (optional)
Order/index of the document within the package.
Document display name.
Original filename uploaded.
File extension or type identifier.
Size of the file in bytes.
Number of pages in the document.
Upload time (ISO 8601 date-time).
Last modified time (ISO 8601 date-time).
Number of signed revisions for this document.
Total number of revisions for this document.
Description of the document. (optional)
Set to `true` if a CAC (Compliance Audit Certificate) has been appended to the document.
Number of CAC pages if `cac` is `true`.
Current state of the document.
Most document states are used internally. All documents included in a returned package will always be in the open state.
| Values | Description |
| :----- | :--------------------------------------------------- |
| open | The document is open and can be interacted with. |
| failed | The document failed to process and cannot be signed. |
Revision history for the document. Typically includes one revision per signer.
ID of the document this revision belongs to.
Unique identifier for the revision.
Revision number (incrementing integer).
Identifier of the previous revision this revision replaced. (optional)
Last opened time for the revision (ISO 8601).
Signer who is associated with this revision.
Set to `true` if this revision has been signed.
Time the revision was signed (ISO 8601).
Address metadata captured on sign. (optional)
Latitude coordinate captured on sign. (optional)
Longitude coordinate captured on sign. (optional)
State of the revision (for example: signed, pending).
Signers associated with this document.
Identifier for the signer associated with the document.
Internal signer key used to map fields/tags.
Full name for the signer on this document.
Signer initials.
Email for the signer on this document.
Mobile number for the signer on this document. (optional)
Set to `true` if the signer has signed this document.
Set to `true` if this signer is next in the signing order for this document.
Template role name if the signer was created from a template role. (optional)
Signers for the package.
Unique identifier for the signer.
Package identifier the signer belongs to.
Member identifier when the signer is an organization member. (optional)
Tag associated with the signer. (optional)
When the signer record was created (ISO 8601).
Time the signer declined (if applicable).
Last update time for the signer record.
Signing order index.
Locale for the signer. (optional)
Set to `true` if signer requires CAC signing.
Set to `true` if signer requires identity verification before signing.
First name of the signer.
Last name of the signer.
Email address for the signer.
Country code for the mobile number. (optional)
Original mobile number provided.
Normalized mobile number (E.164) when available.
Message left by the signer when declining (if any).
Reason code for decline (if applicable).
Set to `true` if this signer is next in signing order across the package.
Number of revisions the signer has signed.
Number of revisions assigned to the signer.
Role of the signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Type of signer.
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
Current state of the signer.
| Value | Description |
| :------- | :-------------------------------------------------------------- |
| active | Signer that is actively participating in the signing process. |
| declined | Signer that has declined to participate in the signing process. |
| deleted | Signer that has been removed from the package. |
Signer verification status. (if any)
Identifier for the verification record.
Signer identifier associated with this verification.
Set to `true` if the signer is can sign documents after verification.
Set to `true` if the signer can join VSR after verification.
Set to `true` if the signer may retry verification on failure.
Set to `true` if the signer has successfully signed after verification.
Set to `true` if the verification is currently locked.
Number of verification attempts made.
Number of errors encountered during verification.
Whether the verification flow should continue to next step.
Whether to continue the flow when verification errors occur.
Current verification error code (if any).
Current state of the verification.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Recipients related to the package (additional recipients beyond signers).
Unique identifier for the recipient.
Identifier of the package the recipient belongs to.
Creation time for the recipient record (ISO 8601).
Last update time for the recipient record (ISO 8601).
Recipient first name.
Recipient last name.
Recipient email address.
Recipient mobile number country code. (optional)
Original recipient mobile number provided.
Normalized recipient mobile number. (optional)
Recipient locale. (optional)
Recipient type.
Current state of the recipient record.
Verification records associated with the package.
Identifier for the verification record.
Signer identifier associated with this verification.
Set to `true` if the signer is can sign documents after verification.
Set to `true` if the signer can join VSR after verification.
Set to `true` if the signer may retry verification on failure.
Set to `true` if the signer has successfully signed after verification.
Set to `true` if the verification is currently locked.
Number of verification attempts made.
Number of errors encountered during verification.
Whether the verification flow should continue to next step.
Whether to continue the flow when verification errors occur.
Current verification error code (if any).
Current state of the verification.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Consent records associated with the package.
4.2
Unique identifier for the consent record.
Consent record reused by an automatic acceptance.
Organization that owns the consent record.
Member associated with the consent.
Package associated with the consent.
Signer associated with the consent.
Identity verification associated with the consent.
Signing session associated with the consent.
Time the consent was accepted (ISO 8601 date-time).
Time the consent was declined (ISO 8601 date-time).
Time the consent was revoked (ISO 8601 date-time).
IP address from which consent was recorded.
Action used to record the consent.
| Value | Version | Description |
| :------------------------- | :------ | :------------------------------------------------------------ |
| `auto` | 4.2 | Consent was reused automatically under the configured policy. |
| `clicked_consent_button` | 4.2 | The signer accepted by selecting the consent button. |
| `clicked_decline_button` | 4.2 | The signer declined by selecting the decline button. |
| `checked_consent_checkbox` | 4.2 | The signer accepted by selecting the consent checkbox. |
| `on_behalf_of` | 4.2 | Consent was recorded on behalf of the signer. |
Base64-encoded SHA-256 version of the consent notice.
Notice presented when consent was recorded.
Default notice text.
Notice text keyed by locale code.
Consent type.
| Value | Version | Description |
| :---------------- | :------ | :---------------------------------------------- |
| `signing` | 4.2 | Consent to sign documents. |
| `verification` | 4.2 | Consent to complete identity verification. |
| `video_recording` | 4.2 | Consent to record a Video Signing Room session. |
Current consent state.
| Value | Version | Description |
| :--------- | :------ | :------------------------------------------------------------- |
| `required` | 4.2 | Consent is required and has not yet been accepted or declined. |
| `accepted` | 4.2 | Consent was accepted. |
| `declined` | 4.2 | Consent was declined. |
| `revoked` | 4.2 | Previously accepted consent was revoked. |
List of contacts created during package creation, returned when `addSignersToContacts` is set to `true` on the request.
# Data
Source: https://docs.iinkedsign.com/v4/api/packages/data
GET /packages/{packageId}/data
After the signers have signed their documents and the package has been finalized you can retrieve the values of all fields in the package by calling the `/packages/{packageId}/data` endpoint.
## Request
```http Request theme={null}
GET /packages/{packageId}/data
```
### Parameters
The unique identifier of the package you want to retrieve field data for.
## Response
Unique identifier for the package.
Display name of the package.
Package type.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Current workflow state of the package.
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
Arbitrary external data attached to the package.
List of documents along with their captured field values.
Unique identifier for the document.
Identifier of the package this document belongs to.
Document display name.
Original filename uploaded for the document.
Current state of the document.
Most document states are used internally. All documents included in a returned package will always be in the open state.
| Values | Description |
| :----- | :--------------------------------------------------- |
| open | The document is open and can be interacted with. |
| failed | The document failed to process and cannot be signed. |
Field values captured for the document.
Unique identifier for the field instance (for example: signer\_1-text\_1).
Data identifier from the template or field definition. (optional)
Signer identifier associated with this field value. (optional)
Origin of the value (for example: template, user).
Field type (for example: text, multiline, checkbox).
Captured value for the field.
Page number within the document where the field appears.
# Delete
Source: https://docs.iinkedsign.com/v4/api/packages/delete
POST /packages/delete
The `/packages/delete` endpoint allows you to delete an existing package from the iinked Sign platform.
Once a package is deleted, all signers associated with the package will no longer be able to access or sign the documents within that package.
You can alternatively rescind a package using the [/packages/rescind](/v4/api/packages/rescind) endpoint, which notifies all signers that the package has been rescinded but retains the package and its documents in the platform.
Please note that this will mark the package and all of its documents and videos for permanent deletion from the iinked Sign platform and you should only do so if you no longer need the package.
## Request
```http Request highlight={3} theme={null}
POST /packages/delete
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02",
"notify": true,
"overrideRetention": false
}
```
### Body
Unique identifier for the package.
When `true`, notifies all signers of the package deletion via email. When `false`, no notifications are sent.
When `true`, overrides any retention policies that would normally prevent the package from being deleted.
Use with caution.
## Response
Unique identifier of the package deleted.
List of videos that were deleted from the package.
Unique identifier for the video.
Shared identifier for the video.
Identifier of the meeting the video belongs to.
Identifier of the meeting session.
External system identifier for the video (if available).
External storage identifier for the video (if available).
Creation time (ISO 8601 date-time).
Retention expiry time (ISO 8601 date-time).
Deletion time (ISO 8601 date-time).
Video duration (ISO 8601 duration).
Size of the video in bytes.
Source of the video.
Type of video.
| Value | Description |
| :---- | :------------------------ |
| video | Standard video recording. |
Current state of the video.
| Value | Description |
| :------- | :------------------------------------------------------------------------------ |
| started | Video recording session is currently active. |
| stopped | Video recording session ended successfully. |
| queued | Video recording is waiting to download. |
| failed | Video recording failed to download because of an error. |
| archived | Video recording has been successfully downloaded and is available for playback. |
| deleted | Video recording has been permanently removed. |
Temporary URL to download or playback the video.
Expires based on `timeUrlExpires`.
Expiration time for the temporary URL (ISO 8601 date-time).
# Download
Source: https://docs.iinkedsign.com/v4/api/packages/download
GET /packages/{packageId}/documents/{documentId}/pdf/{version}/download
## Request
Download the **executed** version of a document within a package. This provides access to the completed document that has been fully signed and is ready for record-keeping or distribution.
```http Request theme={null}
GET /packages/{packageId}/documents/{documentId}/pdf/executed/download
```
Download the **CAC** (Compliance Audit Certificate) for a package.
```http Request theme={null}
GET /packages/{packageId}/documents/{documentId}/pdf/cac/download
```
Download the **current** revision of a document within a package. This allows you to retrieve the most up-to-date version of the document, which may include any recent changes or signatures.
```http Request theme={null}
GET /packages/{packageId}/documents/{documentId}/pdf/current/download
```
Use the `revisionId` to download a specific revision of a document within a package. This is useful when you need to access a particular version of the document, such as one before or after certain changes were made.
```http Request theme={null}
GET /packages/{packageId}/documents/{documentId}/pdf/{revisionId}/download
```
### Parameters
Unique identifier for the package to download a document from.
Unique identifier for the document within the package to download.
Specifies the version of the document to download. Accepted values are:
| Value | Description |
| -------------- | ------------------------------------------------------------------------------------------ |
| executed | The fully signed and completed version of the document. |
| cac | The Compliance Audit Certificate for the package. |
| current | The most up-to-date revision of the document. |
| `{revisionId}` | A specific unique revision identifier to download that particular version of the document. |
See the [MasterFile download API](/v4/api/masterfile/download) for more information on downloading MasterFiles.
## Response
Returns a PDF file of the requested document version.
```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; name="example.pdf";filename*=utf-8''example.pdf
```
# Get
Source: https://docs.iinkedsign.com/v4/api/packages/get
GET /packages/{packageId}
The `/packages/{packageId}` endpoint allows you to retrieve detailed information about a specific package by its unique identifier.
## Request
```http Request theme={null}
GET /packages/{packageId}
```
### Parameters
The unique identifier of the package you want to retrieve.
## Response
Unique identifier for the package.
Unique identifier for the organization that owns the package.
Identifier for the member who created/owns the package.
Team identifier associated with the package. (optional)
Folder identifier where the package is stored. (optional)
Set to `true` if the package is shared.
Current scheduled meeting ID for the package (if applicable).
ID of the template the package was created from (if applicable).
ID of the form the package was created from (if applicable).
ID of the API key used to create the package (if created via API key).
Display name of the package.
Category for the package. (optional)
Client reference number. (optional)
Matter reference number. (optional)
Description of the package. (optional)
Message included when the package was sent. (optional)
Message explaining why the package was rescinded. (optional)
Reminder message for signers. (optional)
Creation time (ISO 8601 date-time).
Reminder time (ISO 8601 date-time).
Retention expiry time (ISO 8601 date-time).
Time the package was rescinded (ISO 8601).
Time the package was deleted (ISO 8601).
Deadline for signing (ISO 8601 date-time).
Last modification time (ISO 8601 date-time).
Package options.
Enable embedded signing mode.
Embed options used to customize the embedded package editor.
2.8
User can only save changes to draft packages; the user will not be able to send it.
User will not be allowed to modify package properties.
User will not be allowed to modify package verification properties.
User will not be allowed to modify package signers.
User will not be allowed to modify package documents.
User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.
The first document will be focused when the package editor is loaded instead of the package properties.
User will be redirected back to the returnUrl when they are done editing the package.
Will be included in a `state` query string parameter appended to the `returnUrl`.
Show custom brand when signing package.
1.10
Add document identifier to each page (QR code).
Allow VSR participants to review documents before a meeting via a Review Documents link added to email meeting invitation.
2.6
Allow signers to forward the signing to another email address.
4.0
Enabled to not share email addresses between signers.
2.11
Supported in the following package types:
* Concurrent (`concurrent`)
* Sequential (`Sequential`)
* Group Send (`Counterparts`)
Do not allow signers to fill AcroForm fields during signing.
3.3
Do not allow signers to modify AcroForm fields during signing.
3.6
Control how Acroform fields are flattened after signing a document.
2.6
| Value | Description |
| :----- | :----------------------------------- |
| none | Do not flatten fields |
| filled | Flatten only fields filled by signer |
| all | Flatten all fields `default` |
Override the default ink color `#0000FF` for Ink to Sign signatures and initials with a valid #-hexadecimal RGB color value.
2.10
Set preferred default mark type.
4.0
| Value | Description |
| :-------------- | :---------- |
| touch\_to\_sign | iink It |
| type\_to\_sign | Type It |
| click\_to\_sign | Accept It |
Add a retention period to the package to prevent deletion. (ISO 8601 duration)
1.11
Override system messages by message key. Each value contains an optional
`default` string and an optional `locale` map of locale codes to strings.
Values are limited to 1,024 characters and cannot contain website domains or
email addresses.
3.6
Add custom consent notice text by consent type: `signing`, `verification`, or
`video_recording`. Each value contains an optional `default` string and an
optional `locale` map of locale codes to strings. Custom text is appended to
the system notice, supports locale fallback, is limited to 1,024 characters,
and cannot contain website domains or email addresses.
4.2
Parse document for templating tags. Defaults to true.
Parse merger data templating tags. Defaults to false.
4.0
Control how unused signer tags are handled.
2.6
| Value | Description |
| :----- | :------------------------------- |
| keep | Leave unused tags in document |
| hide | Move unused tags to hidden layer |
| remove | Remove unused tags `default` |
Control which document(s) within a package have the CAC page appended to them.
3.2
| Value | Description |
| :-------------- | :---------------------------------- |
| document\_all | Append to all documents in package |
| document\_first | Append to first document in package |
| document\_last | Append to last document in package |
When enabled will add a signer identification placeholder for each signer on the CAC page.
3.2
Add a custom disclaimer to the top of the Compliance Audit Certificate.
1.10
Enabled 2FA security code.
All signers will require a valid mobile phone number to enable mobile MFA.
Enabled 2FA security passphrase.
You must also set a passphrase as part of add or update request to enabled 2FA security passphrase.
```json theme={null}
{
"options": {
"securityPassphrase": true,
...
},
"securityPassphrase": "mySecretPassphrase"
}
```
Enable all mark types.
Enabled click to sign `Accept It`.
Enabled type to sign `Type It`.
Enabled touch to sign `Ink It`.
Allows signer to use desktop mouse to draw signature via touch to sign.
Allow signers to apply their last used iink signature during a signing session. Defaults to `false`.
4.1
Automatically starts video recording after host starts meeting and first attendee joins.
Disables video recording feature preventing host from recording signing session.
Add a retention period to all package videos to prevent deletion. (ISO 8601 duration)
1.11
Share meeting details and videos with guest signers via MasterFile.
Prevent all package notifications from being sent to signers. This option will override other notify options. This option will not prevent Document Accessed (notifyAccessed) notifications if enabled.
1.10.4
Set to false to not include signed documents as attachments in executed email notifications.
2.5
Send email notification to owner to confirm package was created.
Send email notification to owner whenever a signer opens a document (limited to once every hour).
Send email notification to each signer when it is their turn to sign.
Send email notification to each signer to notify them that they are waiting their turn to sign.
Send email notification to each signer when Video Signing Room meeting is scheduled.
Include ICS compatible meeting invitation with email notification to schedule meeting date and time in recipients' calendar.
Send email notification to signer after they sign each document.
2.5
For Sequential packages, the next signer notification is only sent after the current signer has signed all of their documents.
3.3
Send email to owner to notify them when all signers have signed each document.
Don't send document executed email until all documents in the package have been fully signed.
3.3
`Counterparts` Send document executed notification TO package owner and CC signer.
1.10
Send signers fully executed document with CAC page appended to end of document.
1.10
Send signers fully executed document without CAC page appended to end of document.
1.10
Send signers separated CAC page as an additional attachment.
1.10
Allow signer to add additional fields while signing documents. Customize signerTools to control what fields the signer can add.
Allow signer to delete any templated fields while signing a document. This is default behavior for VSR and In Person package types. It is recommended to use optional fields instead for Concurrent, Sequential, and Group Send package types.
2.10
Customize signer toolbar options.
Enable sign.
Enable annotations (ink) on mobile devices.
Enable annotations (ink) on desktop.
Enable text.
Enable note.
Enable forms.
Auto highlight form fields.
Enable image.
Request Signers Geolocation while signing documents, joining VSR meetings, performing IDV, and connecting to a mobile signature pad.
Customize how Geolocation is collected.
3.6
Require geolocation to be shared before allowing the signer to continue.
Require geolocation to be shared before the signer can sign documents.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can use signature pad.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can join VSR meetings.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can verify their identity.
(`required` must also be set to `true`)
Enable custom PDF security options.
2.10
Customize PDF security options.
2.10
Allow PDF merge operations.
Allow copying PDF content.
Allow only degraded PDF printing.
Allow PDF AcroForms fields to be filled in (when formFlattening option is not set to "all").
Allow PDF annotations.
Allow PDF editing.
Allow PDF printing.
Allow screen readers.
PDF security options are enforced only when the PDF is opened in a PDF viewer that supports the PDF security settings. Not all PDF viewers support these settings.
Configure consent requirements and automatic reuse.
4.2
Require the signer to provide consent before completing a configured consent
action. Defaults to `false`.
Require consent before signing. Defaults to `true`.
Require consent before video recording in a Video Signing Room package.
Defaults to `false`.
Reuse a member's previously accepted consent when the consent type and notice
version match and the acceptance occurred within this number of days. Defaults
to `90`. Set to `0` to disable automatic reuse.
Set identity verification options.
3.2
The policy ID of the custom Identity Verification Policy to use during signer identity verification. (Custom IDV policies currently must be created by our Support Team for your organization.)
The code of one of our standard Identity Verification Policy to use during signer identity verification.
| Policy Code | Pass-To-Sign | Region | Retries |
| :--------------------------------------- | :----------: | :----: | :-----: |
| trulioo3\_document | false | Any | 2 |
| trulioo3\_document\_required | true | Any | 2 |
| trulioo3\_document\_ca\_strict | false | CA | 2 |
| trulioo3\_document\_ca\_strict\_required | true | CA | 2 |
**Pass-To-Sign** indicates whether the signer must successfully complete identity verification before they can sign their documents.
Configure the digital signature types and providers available to signers.
4.2
Map each enabled digital signature type to an ordered list of provider names.
| Signature type | Description |
| :------------- | :----------------------------- |
| `qes` | Qualified Electronic Signature |
| Value | Provider |
| :------------ | :---------- |
| `digidentity` | Digidentity |
Provider availability depends on your subscription and organization configuration.
Set package `Remind Me Later` options.
4.0
Number of days, from today, to send a reminder notification to the package owner.
Message that will be sent with the reminder notification to package owner.
Set to `true` if the package is protected by a security passphrase.
Language/locale for the package.
Time zone for package date/time presentation.
Formatting options for dates and presentation.
Locale code used for formatting. (optional)
Inherits from the package locale if not specified.
Number of signed revisions across package documents.
Total number of revisions across package documents.
Restriction type applied to the package. (optional)
Set to `true` if the package was created via the API.
Package type identifier.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Current state of the package.
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
Arbitrary external data attached to the package.
Package version or timestamp (ISO 8601).
If the package is scheduled for a meeting, the meeting details.
Unique identifier for the meeting.
Organization associated with the meeting.
Package associated with the meeting.
Meeting start time (ISO 8601 date-time).
Meeting duration (ISO 8601 duration string).
Set to `true` if the meeting is private.
Meeting type identifier.
Current state of the meeting.
| Value | Description |
| :---------- | :------------------- |
| scheduled | Scheduled meeting. |
| rescheduled | Rescheduled meeting. |
| cancelled | Cancelled meeting. |
Documents that belong to the package.
Unique identifier for the document.
Identifier of the package this document belongs to.
Unique identifier for the file associated with the document.
Auto-template identifier (if created from an auto-template).
Auto-template document identifier (if applicable).
External identifier for the document. (optional)
Order/index of the document within the package.
Document display name.
Original filename uploaded.
File extension or type identifier.
Size of the file in bytes.
Number of pages in the document.
Upload time (ISO 8601 date-time).
Last modified time (ISO 8601 date-time).
Number of signed revisions for this document.
Total number of revisions for this document.
Description of the document. (optional)
Set to `true` if a CAC (Compliance Audit Certificate) has been appended to the document.
Number of CAC pages if `cac` is `true`.
Current state of the document.
Most document states are used internally. All documents included in a returned package will always be in the open state.
| Values | Description |
| :----- | :--------------------------------------------------- |
| open | The document is open and can be interacted with. |
| failed | The document failed to process and cannot be signed. |
Revision history for the document. Typically includes one revision per signer.
ID of the document this revision belongs to.
Unique identifier for the revision.
Revision number (incrementing integer).
Identifier of the previous revision this revision replaced. (optional)
Last opened time for the revision (ISO 8601).
Signer who is associated with this revision.
Set to `true` if this revision has been signed.
Time the revision was signed (ISO 8601).
Address metadata captured on sign. (optional)
Latitude coordinate captured on sign. (optional)
Longitude coordinate captured on sign. (optional)
State of the revision (for example: signed, pending).
Signers associated with this document.
Identifier for the signer associated with the document.
Internal signer key used to map fields/tags.
Full name for the signer on this document.
Signer initials.
Email for the signer on this document.
Mobile number for the signer on this document. (optional)
Set to `true` if the signer has signed this document.
Set to `true` if this signer is next in the signing order for this document.
Template role name if the signer was created from a template role. (optional)
Signers for the package.
Unique identifier for the signer.
Package identifier the signer belongs to.
Member identifier when the signer is an organization member. (optional)
Tag associated with the signer. (optional)
When the signer record was created (ISO 8601).
Time the signer declined (if applicable).
Last update time for the signer record.
Signing order index.
Locale for the signer. (optional)
Set to `true` if signer requires CAC signing.
Set to `true` if signer requires identity verification before signing.
First name of the signer.
Last name of the signer.
Email address for the signer.
Country code for the mobile number. (optional)
Original mobile number provided.
Normalized mobile number (E.164) when available.
Message left by the signer when declining (if any).
Reason code for decline (if applicable).
Set to `true` if this signer is next in signing order across the package.
Number of revisions the signer has signed.
Number of revisions assigned to the signer.
Role of the signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Type of signer.
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
Current state of the signer.
| Value | Description |
| :------- | :-------------------------------------------------------------- |
| active | Signer that is actively participating in the signing process. |
| declined | Signer that has declined to participate in the signing process. |
| deleted | Signer that has been removed from the package. |
Signer verification status. (if any)
Identifier for the verification record.
Signer identifier associated with this verification.
Set to `true` if the signer is can sign documents after verification.
Set to `true` if the signer can join VSR after verification.
Set to `true` if the signer may retry verification on failure.
Set to `true` if the signer has successfully signed after verification.
Set to `true` if the verification is currently locked.
Number of verification attempts made.
Number of errors encountered during verification.
Whether the verification flow should continue to next step.
Whether to continue the flow when verification errors occur.
Current verification error code (if any).
Current state of the verification.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Recipients related to the package (additional recipients beyond signers).
Unique identifier for the recipient.
Identifier of the package the recipient belongs to.
Creation time for the recipient record (ISO 8601).
Last update time for the recipient record (ISO 8601).
Recipient first name.
Recipient last name.
Recipient email address.
Recipient mobile number country code. (optional)
Original recipient mobile number provided.
Normalized recipient mobile number. (optional)
Recipient locale. (optional)
Recipient type.
Current state of the recipient record.
Verification records associated with the package.
Identifier for the verification record.
Signer identifier associated with this verification.
Set to `true` if the signer is can sign documents after verification.
Set to `true` if the signer can join VSR after verification.
Set to `true` if the signer may retry verification on failure.
Set to `true` if the signer has successfully signed after verification.
Set to `true` if the verification is currently locked.
Number of verification attempts made.
Number of errors encountered during verification.
Whether the verification flow should continue to next step.
Whether to continue the flow when verification errors occur.
Current verification error code (if any).
Current state of the verification.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Consent records associated with the package.
4.2
Unique identifier for the consent record.
Consent record reused by an automatic acceptance.
Organization that owns the consent record.
Member associated with the consent.
Package associated with the consent.
Signer associated with the consent.
Identity verification associated with the consent.
Signing session associated with the consent.
Time the consent was accepted (ISO 8601 date-time).
Time the consent was declined (ISO 8601 date-time).
Time the consent was revoked (ISO 8601 date-time).
IP address from which consent was recorded.
Action used to record the consent.
| Value | Version | Description |
| :------------------------- | :------ | :------------------------------------------------------------ |
| `auto` | 4.2 | Consent was reused automatically under the configured policy. |
| `clicked_consent_button` | 4.2 | The signer accepted by selecting the consent button. |
| `clicked_decline_button` | 4.2 | The signer declined by selecting the decline button. |
| `checked_consent_checkbox` | 4.2 | The signer accepted by selecting the consent checkbox. |
| `on_behalf_of` | 4.2 | Consent was recorded on behalf of the signer. |
Base64-encoded SHA-256 version of the consent notice.
Notice presented when consent was recorded.
Default notice text.
Notice text keyed by locale code.
Consent type.
| Value | Version | Description |
| :---------------- | :------ | :---------------------------------------------- |
| `signing` | 4.2 | Consent to sign documents. |
| `verification` | 4.2 | Consent to complete identity verification. |
| `video_recording` | 4.2 | Consent to record a Video Signing Room session. |
Current consent state.
| Value | Version | Description |
| :--------- | :------ | :------------------------------------------------------------- |
| `required` | 4.2 | Consent is required and has not yet been accepted or declined. |
| `accepted` | 4.2 | Consent was accepted. |
| `declined` | 4.2 | Consent was declined. |
| `revoked` | 4.2 | Previously accepted consent was revoked. |
# List
Source: https://docs.iinkedsign.com/v4/api/packages/list
POST /packages/list
You can retrieve a list of an organization members' current packages by calling the `packages/list` endpoint.
## Request
```http Request theme={null}
POST /packages/list
{
"memberId": "e4f0bce5-30fc-43c4-b9ee-364ff5b04dea",
"search": null,
"types": null,
"states": null,
"isExecuted": true,
"sortBy": "created",
"take": 50,
"skip": 0
}
```
### Body
Some filters are restricted based on the authentication method used or permissions of the organization member.
To filter packages for other members, you must use one of the following authentication methods:
- Organization API Key
- User API Key with `Sign Editor` or `Package Editor` role enabled
- Organization OAuth App
To filter packages for teams, the authenticated member must belong to the specified team.
The member ID to retrieve packages for.
The team ID to retrieve packages for.
Filter packages by folder ID.
When true, retrieves packages for all members in the organization.
Filter packages by search terms.
This performs a full text search on package `name`, `description`, `message`, `category`, `client number`, `matter number`, as well as signer and recipient `first name`, `last name`, `email`, and `mobile number`.
You can use `*` as a wildcard character to perform suffix matching (e.g., `Contract*` matches any package whose name contains a word starting with "Contract").
Filter packages by package type.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Filter packages by package state.
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
When `true` will only return executed packages, when `false` will only return non-executed packages. Leave null to not apply any executed filter.
Filter packages whose sign by date is within the next X days.
For example, setting `days` to `7` will return packages whose sign by date is within the next 7 days.
You can use a negative value to filter packages whose sign by date is in the past.
Sort results by one of the following:
| Value | Description |
| :------------------ | :--------------------------------------------------- |
| created | Date package was created (descending). |
| last\_modified | Date package was last modified (descending). |
| reminder | Date of scheduled reminder (descending). |
| signed | Date package was signed by last signer (descending). |
| sign\_by | Date package is to be signed by (descending). |
| sign\_by\_ascending | Date package is to be signed by (ascending). |
Number of packages to return.
Number of packages to skip. Used for pagination or infinite scroll.
## Response
Array of packages returned.
Unique identifier for the package.
Unique identifier for the organization that owns the package.
Identifier for the member who created/owns the package.
Team identifier associated with the package. (optional)
Folder identifier where the package is stored. (optional)
Set to `true` if the package is shared.
Creation time (ISO 8601 date-time).
Last modification time (ISO 8601 date-time).
Deadline for signing (ISO 8601 date-time).
Display name of the package.
Category for the package. (optional)
Client reference number. (optional)
Matter reference number. (optional)
Description of the package. (optional)
Package type identifier.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Current state of the package.
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
Arbitrary external data attached to the package.
Documents that belong to the package.
Unique identifier for the document.
External identifier for the document. (optional)
Order/index of the document within the package.
Document display name.
Original filename uploaded.
Set to `true` if the document has been executed.
Execution time (ISO 8601 date-time).
Signers for the package.
Unique identifier for the signer.
Signing order index.
First name of the signer.
Last name of the signer.
Email address of the signer.
Role of the signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Type of the signer.
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
Set to `true` if signer requires identity verification before signing.
Set to `true` if the signer has been verified.
Set to `true` if the signer is the next in line to sign.
Set to `true` if the signer has executed all documents in the signing package.
Execution time (ISO 8601 date-time).
Recipients related to the package (additional recipients beyond signers).
Unique identifier for the recipient.
Recipient first name.
Recipient last name.
Recipient email address.
Recipient type.
| Value | Description |
| :---- | :------------------------------------------------------------- |
| cc | Recipient that will be **CC** on package email notifications. |
| bcc | Recipient that will be **BCC** on package email notifications. |
Set to `true` if the package has been executed.
Execution time (ISO 8601 date-time).
Total number of packages that match filter criteria.
Number of packages returned per request.
Number of packages skipped.
# Remind signer
Source: https://docs.iinkedsign.com/v4/api/packages/remind
POST /packages/signers/remind
The `/packages/signers/remind` endpoint sends a reminder to one signer in a package that is available for signing.
For a Video Signing Room (VSR) package, the signer receives a meeting notification. For other package types, the signer receives a signing reminder.
## Request
```http Request theme={null}
POST /packages/signers/remind
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02",
"signerId": "95d2f093-cd27-4d7f-bb51-442e98ad56e8"
}
```
### Body
Unique identifier for the package containing the signer.
Unique identifier for the signer to remind.
## Response
Signer who received the reminder.
Unique identifier for the signer.
Package identifier the signer belongs to.
Member identifier when the signer is an organization member. (optional)
Tag associated with the signer. (optional)
When the signer record was created (ISO 8601).
Time the signer declined (if applicable).
Last update time for the signer record.
Signing order index.
Locale for the signer. (optional)
Set to `true` if signer requires CAC signing.
Set to `true` if signer requires identity verification before signing.
First name of the signer.
Last name of the signer.
Email address for the signer.
Country code for the mobile number. (optional)
Original mobile number provided.
Normalized mobile number (E.164) when available.
Message left by the signer when declining (if any).
Reason code for decline (if applicable).
Set to `true` if this signer is next in signing order across the package.
Number of revisions the signer has signed.
Number of revisions assigned to the signer.
Role of the signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Type of signer.
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
Current state of the signer.
| Value | Description |
| :------- | :-------------------------------------------------------------- |
| active | Signer that is actively participating in the signing process. |
| declined | Signer that has declined to participate in the signing process. |
| deleted | Signer that has been removed from the package. |
Signer verification status. (if any)
Identifier for the verification record.
Signer identifier associated with this verification.
Set to `true` if the signer is can sign documents after verification.
Set to `true` if the signer can join VSR after verification.
Set to `true` if the signer may retry verification on failure.
Set to `true` if the signer has successfully signed after verification.
Set to `true` if the verification is currently locked.
Number of verification attempts made.
Number of errors encountered during verification.
Whether the verification flow should continue to next step.
Whether to continue the flow when verification errors occur.
Current verification error code (if any).
Current state of the verification.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
# Rescind
Source: https://docs.iinkedsign.com/v4/api/packages/rescind
POST /packages/rescind
The `/packages/rescind` endpoint allows you to rescind a package that has already been sent for signing.
This operation cancels the signing process and optionally notifies all signers associated with the package.
## Request
```http Request theme={null}
POST /packages/rescind
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02",
"rescindMessage": "The package has been rescinded due to an error in the documents.",
"notify": true
}
```
### Body
Unique identifier for the package to rescind.
Message explaining why the package is being rescinded.
Set to true to notify all signers about the rescind action.
## Response
Unique identifier of the package rescinded.
# Send
Source: https://docs.iinkedsign.com/v4/api/packages/send
POST /packages/send
The `/packages/send` endpoint allows you to send a package that has been previously created in a `select`, `add`, or `draft` state (not yet sent for signing).
This operation initiates the signing process by notifying all signers associated with the package.
## Request
```http Request theme={null}
POST /packages/send
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02"
}
```
### Body
Unique identifier for the package to send.
## Response
Unique identifier of the package sent.
# Status
Source: https://docs.iinkedsign.com/v4/api/packages/status
GET /packages/{packageId}/status
At any time you can get the status of a package by calling `packages/{packageId}/status` endpoint.
Depending on your needs you may want to process the documents or signers array (sometimes both).
Package status will not contain links unless you set generateSignerLinks to true when calling packages/add.
## Request
```http Request theme={null}
GET /packages/{packageId}/status
```
### Parameters
Unique identifier of the package to retrieve status for.
## Response
Unique identifier for the package.
Unique identifier for the organization.
Unique identifier for the member who owns the package.
Name of the package.
Date by which the package should be signed (ISO 8601 format).
Type of the package.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Current state of the package.
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
External data associated with the package.
Set to `true` if all documents have been signed by all signers.
List of documents in the package.
Unique identifier for the package.
Unique identifier for the document.
Unique identifier for the file associated with the document.
External system identifier for the document, if available.
Name of the document.
File name of the document.
Order of the document in the package.
Set to `true` if document has been signed by all signers.
List of revisions for the document.
Unique identifier for the package.
Unique identifier for the document.
Unique identifier for the revision.
Unique identifier for the signer.
Link for signer to sign their revision of document.
Set to `true` if signer is next signer in sequential signing.
Set to `true` if signer has signed their revision of document.
List of signers for the package.
Unique identifier for the signer.
First name of the signer.
Last name of the signer.
Email address of the signer.
Mobile number of the signer.
Order of the signer in the signing process.
List of signing links for the signer.
Token for the signing link.
Unique identifier for the package.
Unique identifier for the document.
Unique identifier for the revision.
Name of document.
Link for signer to sign their revision of document.
Time link expires (ISO 8601 format).
Link type.
Set to `true` if signer is next signer in sequential signing.
Set to `true` if signer has signed their revision of document.
### Examples
```json Response (200) expandable theme={null}
{
"packageId": "7a17e4e7-bc32-4256-bf81-27eac794c2b7",
"organizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"memberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
"name": "My First Signing",
"timeSignBy": "2022-03-02T20:08:41Z",
"type": "Sequential",
"state": "open",
"externalData": null,
"isExecuted": false,
"documents": [
{
"packageId": "7a17e4e7-bc32-4256-bf81-27eac794c2b7",
"documentId": "ad8eac67-94e9-481b-a799-7396b447b8eb",
"fileId": null,
"exernalId": null,
"name": null,
"fileName": "agreement.pdf",
"order": 0,
"isExecuted": false,
"revisions": [
{
"packageId": "7a17e4e7-bc32-4256-bf81-27eac794c2b7",
"documentId": "ad8eac67-94e9-481b-a799-7396b447b8eb",
"revisionId": "a53b203b-af52-4766-a8be-eb0cdd18eb5f",
"signerId": "229c1a3b-c9d3-4546-bcf5-44cb8ea3bd1c",
"link": "https://localhost/tws/link/BKhD5EA0Dw6o0fv7-p3wnw",
"isNext": true,
"isSigned": false
}
]
}
],
"signers": [
{
"signerId": "229c1a3b-c9d3-4546-bcf5-44cb8ea3bd1c",
"firstName": "Signer",
"lastName": "One",
"email": "signer.one@example.com",
"mobileNumber": "",
"order": 0,
"links": [
{
"name": "agreement",
"link": "https://localhost/tws/link/BKhD5EA0Dw6o0fv7-p3wnw",
"type": "document",
"token": "BKhD5EA0Dw6o0fv7-p3wnw",
"timeExpires": "2022-03-02T20:08:41.261Z",
"packageId": "7a17e4e7-bc32-4256-bf81-27eac794c2b7",
"documentId": "ad8eac67-94e9-481b-a799-7396b447b8eb",
"revisionId": "a53b203b-af52-4766-a8be-eb0cdd18eb5f",
"isNext": true,
"isSigned": false
}
],
"signLink": {
"name": "My First Signing",
"link": "https://localhost/tws/link/MnWkMecgfNjfFZsye1YJmg",
"type": "package_sign",
"token": "MnWkMecgfNjfFZsye1YJmg",
"timeExpires": "2022-03-02T20:08:41.261Z",
"packageId": "7a17e4e7-bc32-4256-bf81-27eac794c2b7"
},
"meetingLink": null
}
]
}
```
# Update
Source: https://docs.iinkedsign.com/v4/api/packages/update
POST /packages/update
Package updates can be broken up into the following categories:
* **Modifying Package Properties** (Name, Meeting, Sign by Date, …)
* **Modifying Signers** (Add, Update, and Delete)
* **Modifying Documents** (Add, Update, and Delete)
* **Moving Packages** (Move to Member or Team folder)
## Document regeneration & renotification
Depending on the changes made during a package update, a document may be regenerated, and update notifications may be sent to signers.
* Updating a document that has already been signed or partially signed will result in regenerating the document and requiring the document to be re-signed. A notification will also be sent out to the affected signer(s), notifying them that the package has been updated and to re-sign the documents.
* Updating a signer's email address will result in sending a new notification to the signer's new email address.
* Updating a signer's email address will result in all previous signer links being invalidated.
* Updating a signer's mobile number will result in all previous mobile signer links being invalidated.
## Request
### Adding
```http Request highlight={3-4} theme={null}
POST /packages/update
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02",
"addSigners": [
{
"firstName": "Add",
"lastName": "Signer",
"email": "add.signer@example.com",
"mobileNumber": "+1 555-555-5555",
"role": "signer",
"signCac": true
}
],
"returnPackage": false
}
```
```http Request highlight={3-4} theme={null}
POST /packages/update
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02",
"addDocuments": [
{
"name": "Agreement",
"fileName": "agreement.pdf",
"fileId": "d29e25e0-624b-4adb-b118-19c4d0125e5e"
}
],
"returnPackage": false
}
```
### Updating
```http Request highlight={3} theme={null}
POST /packages/update
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02",
"name": "Updated Package Name",
"returnPackage": false
}
```
```http Request highlight={3-4, 6} theme={null}
POST /packages/update
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02",
"updateSigners": [
{
"signerId": "fc4df1cb-5c42-4dc1-b8ff-55679947fcf4",
"firstName": "Update",
"lastName": "Signer",
"email": "update.signer3@example.com",
"mobileNumber": "+1 555-555-6666",
}
],
"returnPackage": false
}
```
```http Request highlight={3-4, 6} theme={null}
POST /packages/update
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02",
"updateDocuments": [
{
"documentId": "f896cd65-0428-46c1-9209-db4234736dbf",
"name": "Agreement (Updated)",
"fileName": "agreement-updated.pdf",
"fileId": "d29e25e0-624b-4adb-b118-19c4d0125e5e"
}
],
"returnPackage": false
}
```
Set `returnPackage` to false if you do not need the updated package included in the response. If you set `generateSignerLinks` to true, the updated package will always be returned.
### Moving
You can move a package to a member or team folder by specifying the `folderId` along with the `memberId` or `teamId`. If you want to move the package to the root of the member or team, set the `folderId` to `null`.
You must have the necessary permissions to move packages to the specified member or team folder.
```http Request theme={null}
POST /packages/update
{
"packageId": "dce4e52d-3965-4260-b86d-2b62f6bdf78d",
"move": {
"memberId": "e4f0bce5-30fc-43c4-b9ee-364ff5b04dea",
"teamId": null,
"folderId": null
},
"returnPackage": false
}
```
```http Request theme={null}
POST /packages/update
{
"packageId": "dce4e52d-3965-4260-b86d-2b62f6bdf78d",
"move": {
"memberId": "e4f0bce5-30fc-43c4-b9ee-364ff5b04dea",
"teamId": null,
"folderId": "2ca40c83-7034-466e-8fde-f165bb363638"
},
"returnPackage": false
}
```
```http Request theme={null}
POST /packages/update
{
"packageId": "dce4e52d-3965-4260-b86d-2b62f6bdf78d",
"move": {
"memberId": null,
"teamId": "d375b4d6-c0b4-493a-918c-cde26fa7dd1d",
"folderId": null
},
"returnPackage": false
}
```
```http Request theme={null}
POST /packages/update
{
"packageId": "dce4e52d-3965-4260-b86d-2b62f6bdf78d",
"move": {
"memberId": null,
"teamId": "d375b4d6-c0b4-493a-918c-cde26fa7dd1d",
"folderId": "2ca40c83-7034-466e-8fde-f165bb363638"
},
"returnPackage": false
}
```
### Deleting
```http Request highlight={3-4, 6} theme={null}
POST /packages/update
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02",
"deleteSigners": [
{
"signerId": "fc4df1cb-5c42-4dc1-b8ff-55679947fcf4"
}
],
"returnPackage": false
}
```
```http Request highlight={3-4, 6} theme={null}
POST /packages/update
{
"packageId": "cf91071d-966d-41ea-b9bf-aa96a8e56c02",
"deleteDocuments": [
{
"documentId": "f896cd65-0428-46c1-9209-db4234736dbf"
}
],
"returnPackage": false
}
```
### Body
Unique identifier of the package to update
Name of the package.
Category of the package.
Description of the package.
Message to be shared to all signers.
Date by which the document should be signed. After this date, the package will expire and can no longer be signed unless extended.
Security passphrase for the package.
Additional options for the package.
Enable embedded signing mode.
Embed options used to customize the embedded package editor.
2.8
User can only save changes to draft packages; the user will not be able to send it.
User will not be allowed to modify package properties.
User will not be allowed to modify package verification properties.
User will not be allowed to modify package signers.
User will not be allowed to modify package documents.
User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.
The first document will be focused when the package editor is loaded instead of the package properties.
User will be redirected back to the returnUrl when they are done editing the package.
Will be included in a `state` query string parameter appended to the `returnUrl`.
Show custom brand when signing package.
1.10
Add document identifier to each page (QR code).
Allow VSR participants to review documents before a meeting via a Review Documents link added to email meeting invitation.
2.6
Allow signers to forward the signing to another email address.
4.0
Enabled to not share email addresses between signers.
2.11
Supported in the following package types:
* Concurrent (`concurrent`)
* Sequential (`Sequential`)
* Group Send (`Counterparts`)
Do not allow signers to fill AcroForm fields during signing.
3.3
Do not allow signers to modify AcroForm fields during signing.
3.6
Control how Acroform fields are flattened after signing a document.
2.6
| Value | Description |
| :----- | :----------------------------------- |
| none | Do not flatten fields |
| filled | Flatten only fields filled by signer |
| all | Flatten all fields `default` |
Override the default ink color `#0000FF` for Ink to Sign signatures and initials with a valid #-hexadecimal RGB color value.
2.10
Set preferred default mark type.
4.0
| Value | Description |
| :-------------- | :---------- |
| touch\_to\_sign | iink It |
| type\_to\_sign | Type It |
| click\_to\_sign | Accept It |
Add a retention period to the package to prevent deletion. (ISO 8601 duration)
1.11
Override system messages by message key. Each value contains an optional
`default` string and an optional `locale` map of locale codes to strings.
Values are limited to 1,024 characters and cannot contain website domains or
email addresses.
3.6
Add custom consent notice text by consent type: `signing`, `verification`, or
`video_recording`. Each value contains an optional `default` string and an
optional `locale` map of locale codes to strings. Custom text is appended to
the system notice, supports locale fallback, is limited to 1,024 characters,
and cannot contain website domains or email addresses.
4.2
Parse document for templating tags. Defaults to true.
Parse merger data templating tags. Defaults to false.
4.0
Control how unused signer tags are handled.
2.6
| Value | Description |
| :----- | :------------------------------- |
| keep | Leave unused tags in document |
| hide | Move unused tags to hidden layer |
| remove | Remove unused tags `default` |
Control which document(s) within a package have the CAC page appended to them.
3.2
| Value | Description |
| :-------------- | :---------------------------------- |
| document\_all | Append to all documents in package |
| document\_first | Append to first document in package |
| document\_last | Append to last document in package |
When enabled will add a signer identification placeholder for each signer on the CAC page.
3.2
Add a custom disclaimer to the top of the Compliance Audit Certificate.
1.10
Enabled 2FA security code.
All signers will require a valid mobile phone number to enable mobile MFA.
Enabled 2FA security passphrase.
You must also set a passphrase as part of add or update request to enabled 2FA security passphrase.
```json theme={null}
{
"options": {
"securityPassphrase": true,
...
},
"securityPassphrase": "mySecretPassphrase"
}
```
Enable all mark types.
Enabled click to sign `Accept It`.
Enabled type to sign `Type It`.
Enabled touch to sign `Ink It`.
Allows signer to use desktop mouse to draw signature via touch to sign.
Allow signers to apply their last used iink signature during a signing session. Defaults to `false`.
4.1
Automatically starts video recording after host starts meeting and first attendee joins.
Disables video recording feature preventing host from recording signing session.
Add a retention period to all package videos to prevent deletion. (ISO 8601 duration)
1.11
Share meeting details and videos with guest signers via MasterFile.
Prevent all package notifications from being sent to signers. This option will override other notify options. This option will not prevent Document Accessed (notifyAccessed) notifications if enabled.
1.10.4
Set to false to not include signed documents as attachments in executed email notifications.
2.5
Send email notification to owner to confirm package was created.
Send email notification to owner whenever a signer opens a document (limited to once every hour).
Send email notification to each signer when it is their turn to sign.
Send email notification to each signer to notify them that they are waiting their turn to sign.
Send email notification to each signer when Video Signing Room meeting is scheduled.
Include ICS compatible meeting invitation with email notification to schedule meeting date and time in recipients' calendar.
Send email notification to signer after they sign each document.
2.5
For Sequential packages, the next signer notification is only sent after the current signer has signed all of their documents.
3.3
Send email to owner to notify them when all signers have signed each document.
Don't send document executed email until all documents in the package have been fully signed.
3.3
`Counterparts` Send document executed notification TO package owner and CC signer.
1.10
Send signers fully executed document with CAC page appended to end of document.
1.10
Send signers fully executed document without CAC page appended to end of document.
1.10
Send signers separated CAC page as an additional attachment.
1.10
Allow signer to add additional fields while signing documents. Customize signerTools to control what fields the signer can add.
Allow signer to delete any templated fields while signing a document. This is default behavior for VSR and In Person package types. It is recommended to use optional fields instead for Concurrent, Sequential, and Group Send package types.
2.10
Customize signer toolbar options.
Enable sign.
Enable annotations (ink) on mobile devices.
Enable annotations (ink) on desktop.
Enable text.
Enable note.
Enable forms.
Auto highlight form fields.
Enable image.
Request Signers Geolocation while signing documents, joining VSR meetings, performing IDV, and connecting to a mobile signature pad.
Customize how Geolocation is collected.
3.6
Require geolocation to be shared before allowing the signer to continue.
Require geolocation to be shared before the signer can sign documents.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can use signature pad.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can join VSR meetings.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can verify their identity.
(`required` must also be set to `true`)
Enable custom PDF security options.
2.10
Customize PDF security options.
2.10
Allow PDF merge operations.
Allow copying PDF content.
Allow only degraded PDF printing.
Allow PDF AcroForms fields to be filled in (when formFlattening option is not set to "all").
Allow PDF annotations.
Allow PDF editing.
Allow PDF printing.
Allow screen readers.
PDF security options are enforced only when the PDF is opened in a PDF viewer that supports the PDF security settings. Not all PDF viewers support these settings.
Configure consent requirements and automatic reuse.
4.2
Require the signer to provide consent before completing a configured consent
action. Defaults to `false`.
Require consent before signing. Defaults to `true`.
Require consent before video recording in a Video Signing Room package.
Defaults to `false`.
Reuse a member's previously accepted consent when the consent type and notice
version match and the acceptance occurred within this number of days. Defaults
to `90`. Set to `0` to disable automatic reuse.
Set identity verification options.
3.2
The policy ID of the custom Identity Verification Policy to use during signer identity verification. (Custom IDV policies currently must be created by our Support Team for your organization.)
The code of one of our standard Identity Verification Policy to use during signer identity verification.
| Policy Code | Pass-To-Sign | Region | Retries |
| :--------------------------------------- | :----------: | :----: | :-----: |
| trulioo3\_document | false | Any | 2 |
| trulioo3\_document\_required | true | Any | 2 |
| trulioo3\_document\_ca\_strict | false | CA | 2 |
| trulioo3\_document\_ca\_strict\_required | true | CA | 2 |
**Pass-To-Sign** indicates whether the signer must successfully complete identity verification before they can sign their documents.
Configure the digital signature types and providers available to signers.
4.2
Map each enabled digital signature type to an ordered list of provider names.
| Signature type | Description |
| :------------- | :----------------------------- |
| `qes` | Qualified Electronic Signature |
| Value | Provider |
| :------------ | :---------- |
| `digidentity` | Digidentity |
Provider availability depends on your subscription and organization configuration.
Set package `Remind Me Later` options.
4.0
Number of days, from today, to send a reminder notification to the package owner.
Message that will be sent with the reminder notification to package owner.
There are limitations on how you can transition between package states using this endpoint:
If the current package state is `select` or `add`, the package will be automatically transitioned to the `draft` state when updated.
To prevent this automatic transition, set the state to `select` or `add` explicitly to maintain the current state.
If the current package state is `draft`, you can transition back to `add` by setting the state to `add`.
This is useful when using the embedded package editor and you want to maintain the `add` state.
If the package is in a `select`, `add`, or `draft` state, you can **send** the package to transition to the `open` state.
If the package is in an `open` state, you can **rescind** or **delete** the package.
Details about the meeting associated with the package.
Unique identifier for the meeting associated with the package.
Scheduled start time of the meeting (ISO 8601 format).
Duration of the meeting (ISO 8601 duration format).
Set to `true` if the meeting is private.
Set to `true` if participants should be notified about the meeting.
Type of the meeting.
| Value | Description |
| :------ | :---------------------------------------------------------------------- |
| signing | Scheduled Video Signing Room meeting where participants sign documents. |
Move a package to another member, team, or folder.
You can easily copy `teamId` and `folderId` from Teams and Folders management pages within the iinked Sign portal.
The member ID to move a package to.
The team ID to move a package to.
The folder ID to move a package to.
Documents to add to the package.
Must provide one of `fileBase64`, `fileUrl`, or `fileId`.
Friendly file name shown to signers. (defaults to `fileName` if not specified)
Filename including extension.
Base64 encoding of file.
URL of file. (must be https and publicly accessible)
Unique file ID of an existing file added via [Files upload API](/v4/api/files/upload.mdx).
Either `fileData`, `fileUrl`, or `fileId` is required. We recommend using `fileId` to avoid exceeding per request size limits.
The template collection that will be searched to automatically apply any matching templates.
Use this when you want to utilize auto-templates but do not know the specific template or document to apply. This will look for any matching auto-templates in the specified collection.
The full auto-template code `{templateCode}:{documentCode}` that will be used to automatically apply an existing auto-template document.
Use this when you know the specific auto-template and document you want to apply.
The template document ID to apply to this document.
Use this when you want to apply a specific document template from the template passed via `templateId` in the parent object.
Set of key/value pairs of data used to pre-populate templated fields with. The key must match a unique data ID assigned to a template field.
```json theme={null}
...
"templateData": {
"field1": "value1",
"field2": "value2"
},
...
```
Documents to update in the package.
Unique document ID of the document to be updated.
Friendly file name shown to signers. (defaults to `fileName` if not specified)
Filename including extension.
Base64 encoding of file.
URL of file. (must be https and publicly accessible)
Unique file ID of an existing file added via [Files upload API](/v4/api/files/upload.mdx).
Either `fileData`, `fileUrl`, or `fileId` is required. We recommend using `fileId` to avoid exceeding per request size limits.
Set of key/value pairs used to pre-populate templated fields with. The key must match a unique data ID assigned to a template field.
```json theme={null}
...
"templateData": {
"field1": "value1",
"field2": "value2"
},
...
```
Documents to delete from the package.
Unique document ID of the document to be deleted.
Signers to add to the package.
User-defined identifier used to associate template tags with this signer.
See the [Signer tags guide](/v4/guides/template-tagging/signer-tags) for more information.
Signer's first name.
Signer's last name.
Signer's email. (used to send notifications)
Signer's mobile number. (used for 2FA and mobile signatures)
Role of signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Set to `true` to request signer identity verification.
Requires a verification policy to be assigned to package.
Set to `true` to include the signer in the CAC page.
Signers to update in the package.
Unique identifier of the signer to be updated.
Signer's first name.
Signer's last name.
Signer's email. (used to send notifications)
Signer's mobile number. (used for 2FA and mobile signatures)
Role of signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Set to `true` to request signer identity verification.
Requires a verification policy to be assigned to package.
Set to `true` to include the signer in the CAC page.
Signers to delete from the package.
Unique identifier of the signer to be deleted.
Recipients to add to the package.
Recipient's first name.
Recipient's last name.
Recipient's email. (used to send notifications)
Recipient's mobile number. (used for 2FA if enabled)
Type of recipient.
| Value | Description |
| :---- | :------------------------------------------------------------- |
| cc | Recipient that will be **CC** on package email notifications. |
| bcc | Recipient that will be **BCC** on package email notifications. |
Recipients to update in the package.
Unique recipient ID of the recipient to be updated.
Recipient's first name.
Recipient's last name.
Recipient's email. (used to send notifications)
Recipient's mobile number. (used for 2FA if enabled)
Type of recipient.
| Value | Description |
| :---- | :------------------------------------------------------------- |
| cc | Recipient that will be **CC** on package email notifications. |
| bcc | Recipient that will be **BCC** on package email notifications. |
Recipients to delete from the package.
Unique recipient ID of the recipient to be deleted.
Add new signers and update existing signers in user's contacts.
Set to `true` to return links you can use to integrate document signing workflows. If you set `generateSignerLinks` to `true` during `packages/add`, `packages/update` will automatically generate new signer links unless you explicitly set `generateSignerLinks` to `false`.
Return updated package with response.
## Response
Unique identifier for the package.
Full package object, returned when `returnPackage` is set to `true` on the request.
Unique identifier for the package.
Unique identifier for the organization that owns the package.
Identifier for the member who created/owns the package.
Team identifier associated with the package. (optional)
Folder identifier where the package is stored. (optional)
Set to `true` if the package is shared.
Current scheduled meeting ID for the package (if applicable).
ID of the template the package was created from (if applicable).
ID of the form the package was created from (if applicable).
ID of the API key used to create the package (if created via API key).
Display name of the package.
Category for the package. (optional)
Client reference number. (optional)
Matter reference number. (optional)
Description of the package. (optional)
Message included when the package was sent. (optional)
Message explaining why the package was rescinded. (optional)
Reminder message for signers. (optional)
Creation time (ISO 8601 date-time).
Reminder time (ISO 8601 date-time).
Retention expiry time (ISO 8601 date-time).
Time the package was rescinded (ISO 8601).
Time the package was deleted (ISO 8601).
Deadline for signing (ISO 8601 date-time).
Last modification time (ISO 8601 date-time).
Package options.
Enable embedded signing mode.
Embed options used to customize the embedded package editor.
2.8
User can only save changes to draft packages; the user will not be able to send it.
User will not be allowed to modify package properties.
User will not be allowed to modify package verification properties.
User will not be allowed to modify package signers.
User will not be allowed to modify package documents.
User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.
The first document will be focused when the package editor is loaded instead of the package properties.
User will be redirected back to the returnUrl when they are done editing the package.
Will be included in a `state` query string parameter appended to the `returnUrl`.
Show custom brand when signing package.
1.10
Add document identifier to each page (QR code).
Allow VSR participants to review documents before a meeting via a Review Documents link added to email meeting invitation.
2.6
Allow signers to forward the signing to another email address.
4.0
Enabled to not share email addresses between signers.
2.11
Supported in the following package types:
* Concurrent (`concurrent`)
* Sequential (`Sequential`)
* Group Send (`Counterparts`)
Do not allow signers to fill AcroForm fields during signing.
3.3
Do not allow signers to modify AcroForm fields during signing.
3.6
Control how Acroform fields are flattened after signing a document.
2.6
| Value | Description |
| :----- | :----------------------------------- |
| none | Do not flatten fields |
| filled | Flatten only fields filled by signer |
| all | Flatten all fields `default` |
Override the default ink color `#0000FF` for Ink to Sign signatures and initials with a valid #-hexadecimal RGB color value.
2.10
Set preferred default mark type.
4.0
| Value | Description |
| :-------------- | :---------- |
| touch\_to\_sign | iink It |
| type\_to\_sign | Type It |
| click\_to\_sign | Accept It |
Add a retention period to the package to prevent deletion. (ISO 8601 duration)
1.11
Override system messages by message key. Each value contains an optional
`default` string and an optional `locale` map of locale codes to strings.
Values are limited to 1,024 characters and cannot contain website domains or
email addresses.
3.6
Add custom consent notice text by consent type: `signing`, `verification`, or
`video_recording`. Each value contains an optional `default` string and an
optional `locale` map of locale codes to strings. Custom text is appended to
the system notice, supports locale fallback, is limited to 1,024 characters,
and cannot contain website domains or email addresses.
4.2
Parse document for templating tags. Defaults to true.
Parse merger data templating tags. Defaults to false.
4.0
Control how unused signer tags are handled.
2.6
| Value | Description |
| :----- | :------------------------------- |
| keep | Leave unused tags in document |
| hide | Move unused tags to hidden layer |
| remove | Remove unused tags `default` |
Control which document(s) within a package have the CAC page appended to them.
3.2
| Value | Description |
| :-------------- | :---------------------------------- |
| document\_all | Append to all documents in package |
| document\_first | Append to first document in package |
| document\_last | Append to last document in package |
When enabled will add a signer identification placeholder for each signer on the CAC page.
3.2
Add a custom disclaimer to the top of the Compliance Audit Certificate.
1.10
Enabled 2FA security code.
All signers will require a valid mobile phone number to enable mobile MFA.
Enabled 2FA security passphrase.
You must also set a passphrase as part of add or update request to enabled 2FA security passphrase.
```json theme={null}
{
"options": {
"securityPassphrase": true,
...
},
"securityPassphrase": "mySecretPassphrase"
}
```
Enable all mark types.
Enabled click to sign `Accept It`.
Enabled type to sign `Type It`.
Enabled touch to sign `Ink It`.
Allows signer to use desktop mouse to draw signature via touch to sign.
Allow signers to apply their last used iink signature during a signing session. Defaults to `false`.
4.1
Automatically starts video recording after host starts meeting and first attendee joins.
Disables video recording feature preventing host from recording signing session.
Add a retention period to all package videos to prevent deletion. (ISO 8601 duration)
1.11
Share meeting details and videos with guest signers via MasterFile.
Prevent all package notifications from being sent to signers. This option will override other notify options. This option will not prevent Document Accessed (notifyAccessed) notifications if enabled.
1.10.4
Set to false to not include signed documents as attachments in executed email notifications.
2.5
Send email notification to owner to confirm package was created.
Send email notification to owner whenever a signer opens a document (limited to once every hour).
Send email notification to each signer when it is their turn to sign.
Send email notification to each signer to notify them that they are waiting their turn to sign.
Send email notification to each signer when Video Signing Room meeting is scheduled.
Include ICS compatible meeting invitation with email notification to schedule meeting date and time in recipients' calendar.
Send email notification to signer after they sign each document.
2.5
For Sequential packages, the next signer notification is only sent after the current signer has signed all of their documents.
3.3
Send email to owner to notify them when all signers have signed each document.
Don't send document executed email until all documents in the package have been fully signed.
3.3
`Counterparts` Send document executed notification TO package owner and CC signer.
1.10
Send signers fully executed document with CAC page appended to end of document.
1.10
Send signers fully executed document without CAC page appended to end of document.
1.10
Send signers separated CAC page as an additional attachment.
1.10
Allow signer to add additional fields while signing documents. Customize signerTools to control what fields the signer can add.
Allow signer to delete any templated fields while signing a document. This is default behavior for VSR and In Person package types. It is recommended to use optional fields instead for Concurrent, Sequential, and Group Send package types.
2.10
Customize signer toolbar options.
Enable sign.
Enable annotations (ink) on mobile devices.
Enable annotations (ink) on desktop.
Enable text.
Enable note.
Enable forms.
Auto highlight form fields.
Enable image.
Request Signers Geolocation while signing documents, joining VSR meetings, performing IDV, and connecting to a mobile signature pad.
Customize how Geolocation is collected.
3.6
Require geolocation to be shared before allowing the signer to continue.
Require geolocation to be shared before the signer can sign documents.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can use signature pad.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can join VSR meetings.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can verify their identity.
(`required` must also be set to `true`)
Enable custom PDF security options.
2.10
Customize PDF security options.
2.10
Allow PDF merge operations.
Allow copying PDF content.
Allow only degraded PDF printing.
Allow PDF AcroForms fields to be filled in (when formFlattening option is not set to "all").
Allow PDF annotations.
Allow PDF editing.
Allow PDF printing.
Allow screen readers.
PDF security options are enforced only when the PDF is opened in a PDF viewer that supports the PDF security settings. Not all PDF viewers support these settings.
Configure consent requirements and automatic reuse.
4.2
Require the signer to provide consent before completing a configured consent
action. Defaults to `false`.
Require consent before signing. Defaults to `true`.
Require consent before video recording in a Video Signing Room package.
Defaults to `false`.
Reuse a member's previously accepted consent when the consent type and notice
version match and the acceptance occurred within this number of days. Defaults
to `90`. Set to `0` to disable automatic reuse.
Set identity verification options.
3.2
The policy ID of the custom Identity Verification Policy to use during signer identity verification. (Custom IDV policies currently must be created by our Support Team for your organization.)
The code of one of our standard Identity Verification Policy to use during signer identity verification.
| Policy Code | Pass-To-Sign | Region | Retries |
| :--------------------------------------- | :----------: | :----: | :-----: |
| trulioo3\_document | false | Any | 2 |
| trulioo3\_document\_required | true | Any | 2 |
| trulioo3\_document\_ca\_strict | false | CA | 2 |
| trulioo3\_document\_ca\_strict\_required | true | CA | 2 |
**Pass-To-Sign** indicates whether the signer must successfully complete identity verification before they can sign their documents.
Configure the digital signature types and providers available to signers.
4.2
Map each enabled digital signature type to an ordered list of provider names.
| Signature type | Description |
| :------------- | :----------------------------- |
| `qes` | Qualified Electronic Signature |
| Value | Provider |
| :------------ | :---------- |
| `digidentity` | Digidentity |
Provider availability depends on your subscription and organization configuration.
Set package `Remind Me Later` options.
4.0
Number of days, from today, to send a reminder notification to the package owner.
Message that will be sent with the reminder notification to package owner.
Set to `true` if the package is protected by a security passphrase.
Language/locale for the package.
Time zone for package date/time presentation.
Formatting options for dates and presentation.
Locale code used for formatting. (optional)
Inherits from the package locale if not specified.
Number of signed revisions across package documents.
Total number of revisions across package documents.
Restriction type applied to the package. (optional)
Set to `true` if the package was created via the API.
Package type identifier.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Current state of the package.
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
Arbitrary external data attached to the package.
Package version or timestamp (ISO 8601).
If the package is scheduled for a meeting, the meeting details.
Unique identifier for the meeting.
Organization associated with the meeting.
Package associated with the meeting.
Meeting start time (ISO 8601 date-time).
Meeting duration (ISO 8601 duration string).
Set to `true` if the meeting is private.
Meeting type identifier.
Current state of the meeting.
| Value | Description |
| :---------- | :------------------- |
| scheduled | Scheduled meeting. |
| rescheduled | Rescheduled meeting. |
| cancelled | Cancelled meeting. |
Documents that belong to the package.
Unique identifier for the document.
Identifier of the package this document belongs to.
Unique identifier for the file associated with the document.
Auto-template identifier (if created from an auto-template).
Auto-template document identifier (if applicable).
External identifier for the document. (optional)
Order/index of the document within the package.
Document display name.
Original filename uploaded.
File extension or type identifier.
Size of the file in bytes.
Number of pages in the document.
Upload time (ISO 8601 date-time).
Last modified time (ISO 8601 date-time).
Number of signed revisions for this document.
Total number of revisions for this document.
Description of the document. (optional)
Set to `true` if a CAC (Compliance Audit Certificate) has been appended to the document.
Number of CAC pages if `cac` is `true`.
Current state of the document.
Most document states are used internally. All documents included in a returned package will always be in the open state.
| Values | Description |
| :----- | :--------------------------------------------------- |
| open | The document is open and can be interacted with. |
| failed | The document failed to process and cannot be signed. |
Revision history for the document. Typically includes one revision per signer.
ID of the document this revision belongs to.
Unique identifier for the revision.
Revision number (incrementing integer).
Identifier of the previous revision this revision replaced. (optional)
Last opened time for the revision (ISO 8601).
Signer who is associated with this revision.
Set to `true` if this revision has been signed.
Time the revision was signed (ISO 8601).
Address metadata captured on sign. (optional)
Latitude coordinate captured on sign. (optional)
Longitude coordinate captured on sign. (optional)
State of the revision (for example: signed, pending).
Signers associated with this document.
Identifier for the signer associated with the document.
Internal signer key used to map fields/tags.
Full name for the signer on this document.
Signer initials.
Email for the signer on this document.
Mobile number for the signer on this document. (optional)
Set to `true` if the signer has signed this document.
Set to `true` if this signer is next in the signing order for this document.
Template role name if the signer was created from a template role. (optional)
Signers for the package.
Unique identifier for the signer.
Package identifier the signer belongs to.
Member identifier when the signer is an organization member. (optional)
Tag associated with the signer. (optional)
When the signer record was created (ISO 8601).
Time the signer declined (if applicable).
Last update time for the signer record.
Signing order index.
Locale for the signer. (optional)
Set to `true` if signer requires CAC signing.
Set to `true` if signer requires identity verification before signing.
First name of the signer.
Last name of the signer.
Email address for the signer.
Country code for the mobile number. (optional)
Original mobile number provided.
Normalized mobile number (E.164) when available.
Message left by the signer when declining (if any).
Reason code for decline (if applicable).
Set to `true` if this signer is next in signing order across the package.
Number of revisions the signer has signed.
Number of revisions assigned to the signer.
Role of the signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Type of signer.
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
Current state of the signer.
| Value | Description |
| :------- | :-------------------------------------------------------------- |
| active | Signer that is actively participating in the signing process. |
| declined | Signer that has declined to participate in the signing process. |
| deleted | Signer that has been removed from the package. |
Signer verification status. (if any)
Identifier for the verification record.
Signer identifier associated with this verification.
Set to `true` if the signer is can sign documents after verification.
Set to `true` if the signer can join VSR after verification.
Set to `true` if the signer may retry verification on failure.
Set to `true` if the signer has successfully signed after verification.
Set to `true` if the verification is currently locked.
Number of verification attempts made.
Number of errors encountered during verification.
Whether the verification flow should continue to next step.
Whether to continue the flow when verification errors occur.
Current verification error code (if any).
Current state of the verification.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Recipients related to the package (additional recipients beyond signers).
Unique identifier for the recipient.
Identifier of the package the recipient belongs to.
Creation time for the recipient record (ISO 8601).
Last update time for the recipient record (ISO 8601).
Recipient first name.
Recipient last name.
Recipient email address.
Recipient mobile number country code. (optional)
Original recipient mobile number provided.
Normalized recipient mobile number. (optional)
Recipient locale. (optional)
Recipient type.
Current state of the recipient record.
Verification records associated with the package.
Identifier for the verification record.
Signer identifier associated with this verification.
Set to `true` if the signer is can sign documents after verification.
Set to `true` if the signer can join VSR after verification.
Set to `true` if the signer may retry verification on failure.
Set to `true` if the signer has successfully signed after verification.
Set to `true` if the verification is currently locked.
Number of verification attempts made.
Number of errors encountered during verification.
Whether the verification flow should continue to next step.
Whether to continue the flow when verification errors occur.
Current verification error code (if any).
Current state of the verification.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Consent records associated with the package.
4.2
Unique identifier for the consent record.
Consent record reused by an automatic acceptance.
Organization that owns the consent record.
Member associated with the consent.
Package associated with the consent.
Signer associated with the consent.
Identity verification associated with the consent.
Signing session associated with the consent.
Time the consent was accepted (ISO 8601 date-time).
Time the consent was declined (ISO 8601 date-time).
Time the consent was revoked (ISO 8601 date-time).
IP address from which consent was recorded.
Action used to record the consent.
| Value | Version | Description |
| :------------------------- | :------ | :------------------------------------------------------------ |
| `auto` | 4.2 | Consent was reused automatically under the configured policy. |
| `clicked_consent_button` | 4.2 | The signer accepted by selecting the consent button. |
| `clicked_decline_button` | 4.2 | The signer declined by selecting the decline button. |
| `checked_consent_checkbox` | 4.2 | The signer accepted by selecting the consent checkbox. |
| `on_behalf_of` | 4.2 | Consent was recorded on behalf of the signer. |
Base64-encoded SHA-256 version of the consent notice.
Notice presented when consent was recorded.
Default notice text.
Notice text keyed by locale code.
Consent type.
| Value | Version | Description |
| :---------------- | :------ | :---------------------------------------------- |
| `signing` | 4.2 | Consent to sign documents. |
| `verification` | 4.2 | Consent to complete identity verification. |
| `video_recording` | 4.2 | Consent to record a Video Signing Room session. |
Current consent state.
| Value | Version | Description |
| :--------- | :------ | :------------------------------------------------------------- |
| `required` | 4.2 | Consent is required and has not yet been accepted or declined. |
| `accepted` | 4.2 | Consent was accepted. |
| `declined` | 4.2 | Consent was declined. |
| `revoked` | 4.2 | Previously accepted consent was revoked. |
List of contacts created during package updates, returned when `addSignersToContacts` is set to `true` on the request.
# List
Source: https://docs.iinkedsign.com/v4/api/templates/list
POST /templates/list
Users in iinked Sign can create re-usable Templates in the UI that can be used to generate new signing Packages for workflows that are used frequently. You can get a list of the templates and use a template in the creation of a package.
## Request
You can retrieve a list of an organization's member's current templates by calling `templates/list`.
```http Request theme={null}
POST /templates/list
{
"memberId": "e4f0bce5-30fc-43c4-b9ee-364ff5b04dea",
"search": null,
"personal": true,
"shared": null,
"mostRecent": null,
"sortBy": "last_used",
"take": 100,
"skip": 0
}
```
```http Request highlight={4-6} theme={null}
GET /templates/list
{
"memberId": null,
"types": [
"auto_template"
],
"take": 100,
"skip": 0
}
```
### Body
Some filters are restricted based on the authentication method used or permissions of the organization member.
To filter templates for other members, you must use one of the following authentication methods:
* Organization API Key
* User API Key with `Sign Editor` or `Template Editor` role enabled
* Organization OAuth App
To filter templates for teams, the authenticated member must belong to the specified team.
The member ID to retrieve templates for.
The team ID to retrieve templates for.
Filter templates by folder ID.
When `true`, retrieves templates for all members in the organization.
Filter templates by search terms.
This performs a full text search on template `name`, `description`, `message`, `category`, `client number`, `matter number`, as well as signer and recipient `first name`, `last name`, `email`, `mobile number`, and `template role`.
You can use `*` as a wildcard character to perform suffix matching (e.g., `Contract*` matches any template whose name contains a word starting with "Contract").
When `true`, retrieves members personal templates only.
When `true`, retrieves organization shared templates only.
Filter templates last used within the last X number of days.
Sort results by by one of the following:
| Value | Description |
| :--------- | :---------------------------------------- |
| created | Date template was created (descending). |
| last\_used | Date template was last used (descending). |
Filter templates by collection code.
Filter templates by package type.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Filter templates by template type.
| Value | Description |
| -------------- | ------------------ |
| template | Standard template. |
| auto\_template | Auto template. |
Number of templates to return.
Number of templates to skip.
## Response
The response will contain a list of templates that match the provided filter criteria.
Array of templates returned.
Unique identifier of the organization that owns the template.
Unique identifier of the template.
Template code used to reference the template.
Unique identifier of the member that created the template.
Unique identifier of the team the template belongs to, if any.
Unique identifier of the folder that contains the template, if any.
Indicates whether the template is shared across the organization.
Timestamp when the template was created (ISO 8601 format).
Timestamp when the template was last updated (ISO 8601 format).
Timestamp when the template was last used (ISO 8601 format).
Display name of the template.
Description of the template. (optional)
Package type the template is configured for.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Template type.
| Value | Description |
| -------------- | ------------------ |
| template | Standard template. |
| auto\_template | Auto template. |
Current state of the template.
| Value | Description |
| ------- | -------------------------- |
| active | Template is active. |
| deleted | Template has been deleted. |
List of documents defined within the template.
Unique identifier for the document.
Document code for the document. (optional)
Order/index of the document within the template.
Document display name.
Original filename uploaded.
List of signers configured on the template.
Unique identifier for the signer.
Signing order index.
First name of the signer.
Last name of the signer.
Email address of the signer.
Role of the signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Template role associated to signer. (optional)
Type of the signer.
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
List of recipients configured on the template.
Unique identifier for the recipient.
First name of the recipient.
Last name of the recipient.
Email address of the recipient.
Template role associated to recipient. (optional)
Type of the recipient.
| Value | Description |
| :---- | :------------------------------------------------------------- |
| cc | Recipient that will be **CC** on package email notifications. |
| bcc | Recipient that will be **BCC** on package email notifications. |
Total number of templates that match filter criteria.
Number of templates returned per request.
Number of templates skipped.
# Signer
Source: https://docs.iinkedsign.com/v4/api/verifications/signer
GET /packages/{packageId}/signers/{signerId}/verification
You can retrieve detailed verification results for a signer by calling `/packages/{packageId}/signers/{signerId}/verification` endpoint.
If the signer has not yet started their identity verification, the `verificationId` will be an empty UUID value of `"00000000-0000-0000-0000-000000000000"` and the verification state will be set to `not_started`.
## Request
```http Request theme={null}
GET /packages/{packageId}/signers/{signerId}/verification
```
### Parameters
The unique identifier of the package the signer belongs to.
The unique identifier of the signer to retrieve verification results for.
## Response
Unique identifier for the verification.
Unique identifier for the organization.
Unique identifier for the package.
Package name.
Package type.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Unique identifier for the signer.
Signer's first name.
Signer's last name.
Signer's email address.
Time verification record was created.
Time verification record was last updated.
Two-character ISO-3166-1 country code.
Current number of failed attempts.
Current number of errors.
Set to `true` if the signer is allowed to continue with signing documents after failing identity verification.
Error code if verification is in a failed state (if any).
The current state of the signer's identity verification process.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Results of the verification record.
Unique identifier for the verification result.
Unique identifier for the verification.
Time verification result record was created.
Set to `true` if the verification result has passed.
Set to `true` if the verification result has failed and the signer can no longer retry.
Set to `true` if the verification result has expired and can no longer be completed by signer.
Dictionary of verification results and their pass/fail score.
Score mapping: -1 = missing, 0 = failed/no match, 50 = partial match, 100 = passed.
| Value | Description | Version |
| ---------------------------------------- | ---------------------------------- | ------- |
| credit\_fraud | Fraud Check | |
| credit\_six\_month\_residency | Six Month Residency Check | |
| credit\_three\_year | Three Year Credit Check | |
| document | Identification | |
| document\_confidence | Document Confidence | 3.5 |
| document\_live\_photo\_liveness | Live Selfie Liveness Detection | |
| document\_live\_photo\_match | Live Selfie Matches Document Photo | 3.5 |
| identity | Identity | |
| kba | Knowledge Based Answers | |
| security\_check\_country | Country Match | |
| security\_check\_data | Data Crosscheck Analysis | |
| security\_check\_document\_type | Document Type Match | |
| security\_check\_features | Security Feature Analysis | |
| security\_check\_live\_photo | Live Selfie Match | |
| security\_check\_session | Session Analysis | 3.5 |
| security\_check\_tampering | Tampering Analysis | |
| security\_valid\_data | Data Format Analysis | |
| security\_valid\_document | Data Analysis | |
| security\_valid\_document\_type | Document Type Analysis | |
| security\_valid\_machine\_readable\_data | Machine Readable Data Analysis | |
| security\_valid\_ocr | OCR Analysis | 3.5 |
| security\_valid\_photos | Photo Analysis | 3.5 |
Dictionary of messages associated with each score in `scores`.
Dictionary of verification input fields and their pass/fail score.
Dictionary of verification input fields and their values used to generate the results.
| Key | Label |
| -------------------------- | ----------------- |
| address | Address |
| city | City |
| credit\_details\_trulioo | Credit |
| dob\_day | DOB Day |
| dob\_month | DOB Month |
| dob\_year | DOB Year |
| document\_address | Address |
| document\_address\_2 | Address 2 |
| document\_city | City |
| document\_class | Class |
| document\_country\_code | Country |
| document\_dob\_day | Birth Day |
| document\_dob\_month | Birth Month |
| document\_dob\_year | Birth Year |
| document\_doe\_day | Expiry Day |
| document\_doe\_month | Expiry Month |
| document\_doe\_year | Expiry Year |
| document\_doi\_day | Issue Day |
| document\_doi\_month | Issue Month |
| document\_doi\_year | Issue Year |
| document\_first\_name | First Name |
| document\_full\_name | Full Name |
| document\_gender | Gender |
| document\_issuer | Issuer |
| document\_last\_name | Last Name |
| document\_middle\_name | Middle Name |
| document\_nationality | Nationality |
| document\_number | Document Number |
| document\_number\_2 | Document Number 2 |
| document\_place\_of\_birth | Place of Birth |
| document\_postal\_code | Postal Code |
| document\_subdivision | Province |
| document\_type | Document Type |
| email | Email |
| first\_name | First Name |
| full\_name | Full Name |
| last\_name | Last Name |
| last\_name\_other | Last Name (Other) |
| middle\_name | Middle Name |
| mobile\_number | Mobile Number |
| postal\_code | Postal Code |
| prefix | Prefix |
| street\_name | Street Name |
| street\_number | Street Number |
| street\_type | Street Type |
| subdivision | Province |
| unit\_number | Unit Number |
Dictionary of any additional fields and their values generated while processing the results.
May contain an error code if verification result is in a failed state.
The type of verification result.
| Value | Description |
| -------- | ------------------------------------- |
| identity | Identity verification. |
| kba | Knowledge based answers verification. |
| document | Document verification. |
The state of the verification result.
| State | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| processing | Verification result is currently being processed. |
| collected | Verification input fields have been successfully collected. The input fields will be validated by a subsequent verification step. |
| passed | Verification result has been processed and has passed. |
| failed | Verification result has been processed and has failed. |
| error | An **error** occurred while processing the verification. Check the error field for reason. |
Documents associated with the verification result.
Unique identifier for the verification document.
Unique identifier for the verification.
Time verification document record was created.
Verification document type.
| Key | Description |
| ---------------- | ---------------------------------------------------- |
| drivers\_license | Driver's License |
| health\_card | Health Card |
| identity\_card | Identity Card |
| military\_id | Military ID |
| other | Other (Returned when document type detection failed) |
| passport | Passport |
| resident\_card | Resident Card |
| travel\_document | Travel Document |
| visa | Visa |
| voter\_id | Voter ID |
Verification document image type.
| Key | Description |
| ----------- | ------------------------------------------------------------------------------ |
| live\_photo | Selfie of signer captured during live selfie process of document verification. |
| front | Front image of document captured during document verification. |
| back | Back image of document captured during document verification. |
| passport | Image of passport captured during document verification. |
URL to download document or document image from.
Document URLs returned by the verification endpoint have a lifetime of 15 minutes.
As of `3.6` images now default to `WEBP` format. You can convert images to `JPEG` by appending the following query string parameter to end of the returned URL:
`&mimeType=image/jpeg`
### Examples
```json Response (200) expandable theme={null}
{
"verificationId": "6297e62f-d49d-4f2e-8369-e24ce4316e73",
"organizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"packageId": "08aba360-4466-4463-8b4b-9585d3de4b33",
"signerId": "dff8f8cc-fe2d-428e-9a8c-bcf1a2b187ce",
"firstName": "Signer",
"lastName": "One",
"email": "signer.one@syngrafii.com",
"timeCreated": "2023-01-18T20:09:11.632Z",
"timeUpdated": "2023-01-18T20:14:05.387Z",
"countryCode": "CA",
"error": null,
"state": "passed",
"results": [
{
"verificationResultId": "faa1a005-40a8-43e1-98c8-23d6c7a54278",
"timeCreated": "2023-01-18T20:13:26.111Z",
"passed": true,
"noRetry": null,
"expired": null,
"scores": {
"document": 100,
"security_check_features": 100,
"security_check_tampering": 100,
"security_check_live_photo": 100,
"document_live_photo_liveness": 100,
"security_check_country": 100,
"security_check_document_type": 100,
"security_valid_document_type": 100,
"security_valid_document": 100,
"security_valid_data": 100,
"security_check_data": 100,
"security_valid_machine_readable_data": 100
},
"fieldResultId": null,
"fieldScores": {
"last_name": 100,
"first_name": 100
},
"fields": {
"first_name": "Signer",
"last_name": "One"
},
"data": {
"document_number": "XXXXX-XXXXX-XXXXX",
"document_number_2": "GGXXXXXXX",
"document_country_code": "CAN",
"document_issuer": "Ontario",
"document_class": "G",
"document_doi_day": "01",
"document_doi_month": "12",
"document_doi_year": "2020",
"document_doe_day": "01",
"document_doe_month": "12",
"document_doe_year": "2025",
"document_full_name": "SIGNER ONE",
"document_first_name": "SIGNER",
"document_middle_name": "",
"document_last_name": "ONE",
"document_gender": "M",
"document_dob_day": "01",
"document_dob_month": "12",
"document_dob_year": "1970",
"document_address": "1234 XXXXXXX RD",
"document_city": "XXXXXX",
"document_subdivision": "ON",
"document_postal_code": "L1X 1X1"
},
"error": null,
"type": "document",
"state": "passed",
"documents": [
{
"verificationDocumentId": "adae7fce-30a9-4986-9e11-3c9fa67cb2e6",
"timeCreated": "2023-01-18T20:12:30.3Z",
"documentType": "drivers_license",
"imageType": "front",
"url": "https://sandbox.syngrafii.com/blob/v1/verifications/documents/adae7fce-30a9-4986-9e11-3c9fa67cb2e6"
},
{
"verificationDocumentId": "1f1efa6a-c4fd-467f-a8b0-705751944e36",
"timeCreated": "2023-01-18T20:12:46.111Z",
"documentType": "drivers_license",
"imageType": "back",
"url": "https://sandbox.syngrafii.com/blob/v1/verifications/documents/1f1efa6a-c4fd-467f-a8b0-705751944e36"
},
{
"verificationDocumentId": "88a15267-7516-4f26-9de3-7964e5a7935d",
"timeCreated": "2023-01-18T20:13:24.289Z",
"documentType": "drivers_license",
"imageType": "live_photo",
"url": "https://sandbox.syngrafii.com/blob/v1/verifications/documents/88a15267-7516-4f26-9de3-7964e5a7935d"
}
]
}
]
}
```
# View
Source: https://docs.iinkedsign.com/v4/api/verifications/view
GET /verifications/{verificationId}/view
You can retrieve detailed verification results by calling `/verifications/{verificationId}/view` endpoint.
## Verification ID
First you must obtain a signer's current `verificationId` by calling `/packages/{packageId}` or `/packages/{packageId}/status` endpoints.
You can find the `verificationId` under each signer.
```json theme={null}
{
...
"signers": [
{
"signerId": "7c9b63d1-e3c0-49b0-b13a-e9a24a402fc8",
...
"verification": {
"verificationId": "f050356f-e671-4436-801b-57b9ed40cc8b",
...
}
}
],
...
}
```
See the [Verification signer API](/v4/api/verifications/signer) for more information on retrieving current signer verification results by package and signer ID.
If the signer has not yet started their identity verification, the `verificationId` will be an empty UUID value of `"00000000-0000-0000-0000-000000000000"` and the verification state will be set to `not_started`.
## Request
```http Request theme={null}
GET /verifications/{verificationId}/view
```
### Parameters
The unique identifier of the verification you want to retrieve detailed results for.
## Response
Unique identifier for the verification.
Unique identifier for the organization.
Unique identifier for the package.
Package name.
Package type.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Unique identifier for the signer.
Signer's first name.
Signer's last name.
Signer's email address.
Time verification record was created.
Time verification record was last updated.
Two-character ISO-3166-1 country code.
Current number of failed attempts.
Current number of errors.
Set to `true` if the signer is allowed to continue with signing documents after failing identity verification.
Error code if verification is in a failed state (if any).
The current state of the signer's identity verification process.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Results of the verification record.
Unique identifier for the verification result.
Unique identifier for the verification.
Time verification result record was created.
Set to `true` if the verification result has passed.
Set to `true` if the verification result has failed and the signer can no longer retry.
Set to `true` if the verification result has expired and can no longer be completed by signer.
Dictionary of verification results and their pass/fail score.
Score mapping: -1 = missing, 0 = failed/no match, 50 = partial match, 100 = passed.
| Value | Description | Version |
| ---------------------------------------- | ---------------------------------- | ------- |
| credit\_fraud | Fraud Check | |
| credit\_six\_month\_residency | Six Month Residency Check | |
| credit\_three\_year | Three Year Credit Check | |
| document | Identification | |
| document\_confidence | Document Confidence | 3.5 |
| document\_live\_photo\_liveness | Live Selfie Liveness Detection | |
| document\_live\_photo\_match | Live Selfie Matches Document Photo | 3.5 |
| identity | Identity | |
| kba | Knowledge Based Answers | |
| security\_check\_country | Country Match | |
| security\_check\_data | Data Crosscheck Analysis | |
| security\_check\_document\_type | Document Type Match | |
| security\_check\_features | Security Feature Analysis | |
| security\_check\_live\_photo | Live Selfie Match | |
| security\_check\_session | Session Analysis | 3.5 |
| security\_check\_tampering | Tampering Analysis | |
| security\_valid\_data | Data Format Analysis | |
| security\_valid\_document | Data Analysis | |
| security\_valid\_document\_type | Document Type Analysis | |
| security\_valid\_machine\_readable\_data | Machine Readable Data Analysis | |
| security\_valid\_ocr | OCR Analysis | 3.5 |
| security\_valid\_photos | Photo Analysis | 3.5 |
Dictionary of messages associated with each score in `scores`.
Dictionary of verification input fields and their pass/fail score.
Dictionary of verification input fields and their values used to generate the results.
| Key | Label |
| -------------------------- | ----------------- |
| address | Address |
| city | City |
| credit\_details\_trulioo | Credit |
| dob\_day | DOB Day |
| dob\_month | DOB Month |
| dob\_year | DOB Year |
| document\_address | Address |
| document\_address\_2 | Address 2 |
| document\_city | City |
| document\_class | Class |
| document\_country\_code | Country |
| document\_dob\_day | Birth Day |
| document\_dob\_month | Birth Month |
| document\_dob\_year | Birth Year |
| document\_doe\_day | Expiry Day |
| document\_doe\_month | Expiry Month |
| document\_doe\_year | Expiry Year |
| document\_doi\_day | Issue Day |
| document\_doi\_month | Issue Month |
| document\_doi\_year | Issue Year |
| document\_first\_name | First Name |
| document\_full\_name | Full Name |
| document\_gender | Gender |
| document\_issuer | Issuer |
| document\_last\_name | Last Name |
| document\_middle\_name | Middle Name |
| document\_nationality | Nationality |
| document\_number | Document Number |
| document\_number\_2 | Document Number 2 |
| document\_place\_of\_birth | Place of Birth |
| document\_postal\_code | Postal Code |
| document\_subdivision | Province |
| document\_type | Document Type |
| email | Email |
| first\_name | First Name |
| full\_name | Full Name |
| last\_name | Last Name |
| last\_name\_other | Last Name (Other) |
| middle\_name | Middle Name |
| mobile\_number | Mobile Number |
| postal\_code | Postal Code |
| prefix | Prefix |
| street\_name | Street Name |
| street\_number | Street Number |
| street\_type | Street Type |
| subdivision | Province |
| unit\_number | Unit Number |
Dictionary of any additional fields and their values generated while processing the results.
May contain an error code if verification result is in a failed state.
The type of verification result.
| Value | Description |
| -------- | ------------------------------------- |
| identity | Identity verification. |
| kba | Knowledge based answers verification. |
| document | Document verification. |
The state of the verification result.
| State | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| processing | Verification result is currently being processed. |
| collected | Verification input fields have been successfully collected. The input fields will be validated by a subsequent verification step. |
| passed | Verification result has been processed and has passed. |
| failed | Verification result has been processed and has failed. |
| error | An **error** occurred while processing the verification. Check the error field for reason. |
Documents associated with the verification result.
Unique identifier for the verification document.
Unique identifier for the verification.
Time verification document record was created.
Verification document type.
| Key | Description |
| ---------------- | ---------------------------------------------------- |
| drivers\_license | Driver's License |
| health\_card | Health Card |
| identity\_card | Identity Card |
| military\_id | Military ID |
| other | Other (Returned when document type detection failed) |
| passport | Passport |
| resident\_card | Resident Card |
| travel\_document | Travel Document |
| visa | Visa |
| voter\_id | Voter ID |
Verification document image type.
| Key | Description |
| ----------- | ------------------------------------------------------------------------------ |
| live\_photo | Selfie of signer captured during live selfie process of document verification. |
| front | Front image of document captured during document verification. |
| back | Back image of document captured during document verification. |
| passport | Image of passport captured during document verification. |
URL to download document or document image from.
Document URLs returned by the verification endpoint have a lifetime of 15 minutes.
As of `3.6` images now default to `WEBP` format. You can convert images to `JPEG` by appending the following query string parameter to end of the returned URL:
`&mimeType=image/jpeg`
### Examples
```json Response (200) expandable theme={null}
{
"verificationId": "6297e62f-d49d-4f2e-8369-e24ce4316e73",
"organizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"packageId": "08aba360-4466-4463-8b4b-9585d3de4b33",
"signerId": "dff8f8cc-fe2d-428e-9a8c-bcf1a2b187ce",
"firstName": "Signer",
"lastName": "One",
"email": "signer.one@syngrafii.com",
"timeCreated": "2023-01-18T20:09:11.632Z",
"timeUpdated": "2023-01-18T20:14:05.387Z",
"countryCode": "CA",
"error": null,
"state": "passed",
"results": [
{
"verificationResultId": "faa1a005-40a8-43e1-98c8-23d6c7a54278",
"timeCreated": "2023-01-18T20:13:26.111Z",
"passed": true,
"noRetry": null,
"expired": null,
"scores": {
"document": 100,
"security_check_features": 100,
"security_check_tampering": 100,
"security_check_live_photo": 100,
"document_live_photo_liveness": 100,
"security_check_country": 100,
"security_check_document_type": 100,
"security_valid_document_type": 100,
"security_valid_document": 100,
"security_valid_data": 100,
"security_check_data": 100,
"security_valid_machine_readable_data": 100
},
"fieldResultId": null,
"fieldScores": {
"last_name": 100,
"first_name": 100
},
"fields": {
"first_name": "Signer",
"last_name": "One"
},
"data": {
"document_number": "XXXXX-XXXXX-XXXXX",
"document_number_2": "GGXXXXXXX",
"document_country_code": "CAN",
"document_issuer": "Ontario",
"document_class": "G",
"document_doi_day": "01",
"document_doi_month": "12",
"document_doi_year": "2020",
"document_doe_day": "01",
"document_doe_month": "12",
"document_doe_year": "2025",
"document_full_name": "SIGNER ONE",
"document_first_name": "SIGNER",
"document_middle_name": "",
"document_last_name": "ONE",
"document_gender": "M",
"document_dob_day": "01",
"document_dob_month": "12",
"document_dob_year": "1970",
"document_address": "1234 XXXXXXX RD",
"document_city": "XXXXXX",
"document_subdivision": "ON",
"document_postal_code": "L1X 1X1"
},
"error": null,
"type": "document",
"state": "passed",
"documents": [
{
"verificationDocumentId": "adae7fce-30a9-4986-9e11-3c9fa67cb2e6",
"timeCreated": "2023-01-18T20:12:30.3Z",
"documentType": "drivers_license",
"imageType": "front",
"url": "https://sandbox.syngrafii.com/blob/v1/verifications/documents/adae7fce-30a9-4986-9e11-3c9fa67cb2e6"
},
{
"verificationDocumentId": "1f1efa6a-c4fd-467f-a8b0-705751944e36",
"timeCreated": "2023-01-18T20:12:46.111Z",
"documentType": "drivers_license",
"imageType": "back",
"url": "https://sandbox.syngrafii.com/blob/v1/verifications/documents/1f1efa6a-c4fd-467f-a8b0-705751944e36"
},
{
"verificationDocumentId": "88a15267-7516-4f26-9de3-7964e5a7935d",
"timeCreated": "2023-01-18T20:13:24.289Z",
"documentType": "drivers_license",
"imageType": "live_photo",
"url": "https://sandbox.syngrafii.com/blob/v1/verifications/documents/88a15267-7516-4f26-9de3-7964e5a7935d"
}
]
}
]
}
```
# Delete
Source: https://docs.iinkedsign.com/v4/api/videos/delete
POST /packages/{packageId}/videos/delete
You can delete all the videos or a specific video for a given package by calling the `/packages/{packageId}/videos/delete` endpoint.
Please note that this will mark the video for permanent deletion from the iinked Sign platform and you should only do so if you have downloaded or no longer need the video.
## Request
```http Request theme={null}
POST /packages/videos/delete
{
"packageId": "c603079c-2dc7-4af7-8c2e-dc992662621c",
"meetingVideoId": "4c512b8a-c1ad-47da-ae22-5a61115505e3"
}
```
### Body
Unique identifier for the package to be deleted.
Unique identifier for the specific meeting video to be deleted.
If not provided, all package videos will be deleted.
## Response
Unique identifier of the package associated with the deleted videos.
List of meeting videos deleted from the package.
Unique identifier for the video.
Shared identifier for the video.
Identifier of the meeting the video belongs to.
Identifier of the meeting session.
External system identifier for the video (if available).
External storage identifier for the video (if available).
Creation time (ISO 8601 date-time).
Retention expiry time (ISO 8601 date-time).
Deletion time (ISO 8601 date-time).
Video duration (ISO 8601 duration).
Size of the video in bytes.
Source of the video.
Type of video.
| Value | Description |
| :---- | :------------------------ |
| video | Standard video recording. |
Current state of the video.
| Value | Description |
| :------- | :------------------------------------------------------------------------------ |
| started | Video recording session is currently active. |
| stopped | Video recording session ended successfully. |
| queued | Video recording is waiting to download. |
| failed | Video recording failed to download because of an error. |
| archived | Video recording has been successfully downloaded and is available for playback. |
| deleted | Video recording has been permanently removed. |
Temporary URL to download or playback the video.
Expires based on `timeUrlExpires`.
Expiration time for the temporary URL (ISO 8601 date-time).
## Examples
```json Response (200) theme={null}
{
"packageId": "c603079c-2dc7-4af7-8c2e-dc992662621c",
"videos": [
{
"meetingVideoId": "4c512b8a-c1ad-47da-ae22-5a61115505e3",
"meetingId": "0f2f4065-3d07-4fd5-96e8-13b3f77a7c9d",
"timeCreated": "2019-08-20T18:57:33.541Z",
"timeRetention": null,
"timeDeleted": "2019-08-20T18:58:02.2596573Z",
"duration": "PT6S",
"size": 484524,
"type": "video",
"state": "deleted",
"url": null,
"timeUrlExpires": null
}
]
}
```
# List
Source: https://docs.iinkedsign.com/v4/api/videos/list
GET /packages/{packageId}/videos
You can retrieve the list of videos associated with a package by calling the `/packages/{packageId}/videos` endpoint.
The response will include one or more video URLs that can be used to download or playback the video.
The video URL will expire based on the value of `video.timeUrlExpires` (currently 24 hours).
The call to `/packages/{packageId}` endpoint will also include videos URLs under `meetings[].sessions[].videos[]`.
See the [Packages get API](/v4/api/packages/get) for more information.
## Request
```http Request theme={null}
GET /packages/{packageId}/videos
```
### Parameters
Unique identifier of the package to retrieve videos for.
## Response
Unique identifier of the package videos were recorded for.
List of meeting videos associated with the package.
Unique identifier for the video.
Shared identifier for the video.
Identifier of the meeting the video belongs to.
Identifier of the meeting session.
External system identifier for the video (if available).
External storage identifier for the video (if available).
Creation time (ISO 8601 date-time).
Retention expiry time (ISO 8601 date-time).
Deletion time (ISO 8601 date-time).
Video duration (ISO 8601 duration).
Size of the video in bytes.
Source of the video.
Type of video.
| Value | Description |
| :---- | :------------------------ |
| video | Standard video recording. |
Current state of the video.
| Value | Description |
| :------- | :------------------------------------------------------------------------------ |
| started | Video recording session is currently active. |
| stopped | Video recording session ended successfully. |
| queued | Video recording is waiting to download. |
| failed | Video recording failed to download because of an error. |
| archived | Video recording has been successfully downloaded and is available for playback. |
| deleted | Video recording has been permanently removed. |
Temporary URL to download or playback the video.
Expires based on `timeUrlExpires`.
Expiration time for the temporary URL (ISO 8601 date-time).
## Response examples
```json Response (200) highlight={5, 11, 15, 21} theme={null}
{
"packageId": "26dc68b2-e8be-4594-9a27-8fc6db91f6fc",
"videos": [
{
"meetingVideoId": "919a16f5-7ada-44ff-9dc4-37a20fe4e4c4",
"timeCreated": "2019-07-15T16:53:44.342Z",
"duration": "PT5M12S",
"size": 4402007,
"type": "video",
"state": "archived",
"url": "https://syngrafii.com/video/xxxx?access=yyyy",
"timeUrlExpires": "2019-08-22T19:05:54.8535047Z"
},
{
"meetingVideoId": "5dac6b3a-a61c-4094-bdab-0b073436c0a9",
"timeCreated": "2019-07-15T16:58:58.219Z",
"duration": "PT2M7S",
"size": 2505995,
"type": "video",
"state": "archived",
"url": "https://syngrafii.com/video/xxxx?access=yyyy",
"timeUrlExpires": "2019-08-22T19:05:54.8535047Z"
}
]
}
```
```json Response (packages/{packageId}) expandable highlight={22, 28, 32, 38} theme={null}
{
"packageId": "26dc68b2-e8be-4594-9a27-8fc6db91f6fc",
"name": "Signing",
"timeCreated": "2019-07-15T15:03:41Z",
"type": "video_closing_room",
"state": "open",
"meetings": [
{
"meetingId": "91dbac93-f7c3-4ff1-932c-684b439c6af4",
"timeStart": "2019-07-15T15:15:00Z",
"duration": "PT1H",
"participants": [...],
"sessions": [
{
"meetingSessionId": "f85a4fa1-b173-40d6-a047-53238d69f34a",
"timeStarted": "2019-07-15T16:53:28.316Z",
"timeEnded": "2019-07-15T17:56:42.983Z",
"state": "ended",
"participants": [...],
"videos": [
{
"meetingVideoId": "919a16f5-7ada-44ff-9dc4-37a20fe4e4c4",
"timeCreated": "2019-07-15T16:53:44.342Z",
"duration": "PT5M12S",
"size": 4402007,
"type": "video",
"state": "archived",
"url": "https://syngrafii.com/video/xxxx?access=yyyy",
"timeUrlExpires": "2019-08-22T19:05:54.8535047Z"
},
{
"meetingVideoId": "5dac6b3a-a61c-4094-bdab-0b073436c0a9",
"timeCreated": "2019-07-15T16:58:58.219Z",
"duration": "PT2M7S",
"size": 2505995,
"type": "video",
"state": "archived",
"url": "https://syngrafii.com/video/xxxx?access=yyyy",
"timeUrlExpires": "2019-08-22T19:05:54.8535047Z"
}
]
}
]
}
],
"documents": [...],
"signers": [...]
}
```
# Authentication
Source: https://docs.iinkedsign.com/v4/authentication
## Methods
The iinked Sign API supports two authentication methods, depending on how you are integrating:
* **OAuth 2.0** – For integrations that access data on behalf of your customers
* **API Keys** – For server-to-server access to your own organization’s data
Choose the method that matches your use case.
## OAuth 2.0 (Accessing Customer Accounts)
Use **OAuth 2.0** when you are building an integration that connects to **other users’ accounts**.
### When to Use OAuth
* You are a third-party developer building an app or integration
* Your app connects to multiple customer accounts
* Each customer authorizes your app individually
* You need scoped, permission-based access
See the [OAuth workflow guide](/v4/oauth) for more information.
iinked Sign access tokens are obtained through the OAuth 2.0 authorization process.
**Request Header**
```http theme={null}
Authorization: Bearer
```
## API Keys (Accessing Your Own Organization)
Use an **API key** when accessing data that belongs only to your own organization.
### When to Use an API Key
* Internal tools or backend services
* No third-party user authorization required
* Accessing only your organization’s data
iinked Sign API Keys are available in your iinked Sign account under `Settings` > `Integration` > `API Keys`.
**Request Header**
```http theme={null}
api_key:
```
## Datacenters
## Sandbox instances
### US
API endpoint: `https://sandbox.syngrafii.com/api/v1`\
API key management: [https://sandbox.syngrafii.com/integration](https://sandbox.syngrafii.com/integration)
### EU
API endpoint: `https://sandbox.syngrafii.eu/api/v1`\
API key management: [https://sandbox.syngrafii.eu/integration](https://sandbox.syngrafii.eu/integration)
## Production instances
### US
API endpoint: `https://sign.syngrafii.com/api/v1`\
API key management: [https://sign.syngrafii.com/integration](https://sign.syngrafii.com/integration)
### CA
API endpoint: `https://sign.syngrafii.ca/api/v1`\
API key management: [https://sign.syngrafii.ca/integration](https://sign.syngrafii.ca/integration)
### EU
API endpoint: `https://sign.syngrafii.eu/api/v1`\
API key management: [https://sign.syngrafii.eu/integration](https://sign.syngrafii.eu/integration)
## Private instances
API endpoint: `https://yourinstance.syngrafii.com/api/v1`\
API key management: `https://yourinstance.syngrafii.com/integration`
Replace `yourinstance` with the subdomain of your private instance.
# Auto templates
Source: https://docs.iinkedsign.com/v4/guides/auto-templates
Learn how to use auto templates to streamline your workflow and enhance productivity.
## Overview
Auto templates in iinked Sign allow users to create document templates that can be automatically detected and
applied to a document when creating a new signing package. This feature helps streamline the signing process by predefining
templated fields for commonly used documents within your organization.
You can also manually apply an auto template when creating packages via the API by specifying the `autoTemplateCode` for any document.
Using auto templates is especially useful when your packages contain documents that can vary, because you can choose which auto template to apply to each document individually.
## Steps
To apply an auto template to a document when creating a package, you need to obtain the `autoTemplateCode` for the desired template.
You can find this code in the auto template editor within iinked Sign. It appears in the `Auto Template Document` panel under each document.
You can also retrieve a list of auto templates by calling the `templates/list` endpoint and filtering the results to only include auto templates.
```http Request highlight={4-6} theme={null}
GET /templates/list
{
"memberId": null,
"types": [
"auto_template"
],
"take": 100,
"skip": 0
}
```
See the [Templates list API](/v4/api/templates/list) for more information.
Once you have the `autoTemplateCode`, you can create a new package by calling the `packages/add` endpoint and
specifying the `autoTemplateCode` for each document.
```http Request highlight={8,17} theme={null}
POST /packages/add
{
"name": "From Auto Template Code",
"type": "concurrent",
"state": "open",
"signers": [
{
"templateRole": "Signer 1",
"firstName": "Signer",
"lastName": "One",
"email": "signer@example.com",
"mobileNumber": null
}
],
"documents": [
{
"autoTemplateCode": "agreements:agreement123",
"fileName": "agreement.pdf",
"fileId": "{{file_id}}"
}
]
}
```
You can also use the special `auto` value for the `autoTemplateCode` field. This instructs iinked Sign to automatically
detect and apply any matching auto template based on the document name or content.
```http Request highlight={8,17} theme={null}
POST /packages/add
{
"name": "From Auto Template Code",
"type": "concurrent",
"state": "open",
"signers": [
{
"templateRole": "Signer 1",
"firstName": "Signer",
"lastName": "One",
"email": "signer@example.com",
"mobileNumber": null
}
],
"documents": [
{
"autoTemplateCode": "auto",
"fileName": "agreement.pdf",
"fileId": "{{file_id}}"
}
]
}
```
Alternatively, you can specify the `autoTemplateId` and `autoTemplateDocumentId` directly for more precise control.
```http Request highlight={8,17-18} theme={null}
POST /packages/add
{
"name": "From Auto Template Code",
"type": "concurrent",
"state": "open",
"signers": [
{
"templateRole": "Signer 1",
"firstName": "Signer",
"lastName": "One",
"email": "signer@example.com",
"mobileNumber": null
}
],
"documents": [
{
"autoTemplateId": "{{auto_template_id}}",
"autoTemplateDocumentId": "{{auto_template_document_id}}",
"fileName": "agreement.pdf",
"fileId": "{{file_id}}"
}
]
}
```
# Data formats
Source: https://docs.iinkedsign.com/v4/guides/data-formats
TypeScript notation is used to help define data types and structures throughout the API reference documentation.
## Date
Dates conform to ISO 8601 and are UTC based. Example:
```
2021-12-31T10:00:00Z
```
## Duration
Durations conform to ISO 8601. Example:
```
PT1HM30 // 1 hour and 30 minutes
```
# Embed editor
Source: https://docs.iinkedsign.com/v4/guides/embed-editor
Learn how to embed the package editor into your web application.
## Overview
The embed package editor feature allows you to integrate our package editor directly into your web application.
This provides a seamless experience for users, enabling them to modify and template packages before they are sent without leaving your platform.
## Package `state`
When embedding the package editor, it is recommended to set the package `state` to either `add` or `draft`.
### Add `add`
By creating the package in an `add` state the package editor will guide the user through the package properties and templating the documents just like the native add package experience.
If you plan on updating an existing package and displaying the embedded package editor again you should set the state to `add` in your call to `packages/update`.
If you do not set the state to `add` during the update, the package will automatically transition into a `draft` state.
If the package has already been sent the state can no longer be transitioned back to `add`.
### Draft `draft`
If you are adding all the signers and documents or disabling the editing of the package properties,
then creating the package in a `draft` state with `focusTemplating` embed option is the preferred approach.
## Steps
When you want to embed the package editor, you have to create a package with `generateEditLink` and the `embedded` package option set to `true`.
```http Request highlight={6,8} theme={null}
POST /packages/add
{
"name": "Embedded Package Editor",
"type": "concurrent",
"state": "draft",
"generateEditLink": true,
"options": {
"embedded": true,
"embed": {
"focusTemplating": true
}
},
"signers": [
{
"firstName": "signer",
"lastName": "one",
"email": "signer.one@example.com"
}
],
"documents": [
{
"fileName": "document.pdf",
"fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
}
]
}
```
```json Response highlight={5} theme={null}
{
"package": {
...
"editLink": {
"link": "https://sign.syngrafii.com/link/6iC4sCyjRaMTm2FcMjwIVA"
},
...
}
}
```
#### Embed options
You can customize the embedded package editor experience by setting additional `embed` options.
Enable embedded signing mode.
Embed options used to customize the embedded package editor.
2.8
User can only save changes to draft packages; the user will not be able to send it.
User will not be allowed to modify package properties.
User will not be allowed to modify package verification properties.
User will not be allowed to modify package signers.
User will not be allowed to modify package documents.
User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.
The first document will be focused when the package editor is loaded instead of the package properties.
User will be redirected back to the returnUrl when they are done editing the package.
Will be included in a `state` query string parameter appended to the `returnUrl`.
To embed the package edtior in an iframe, you need to use the `editLink.link` provided in the add package response or by calling the [Packages link API](/v4/api/links/edit) endpoint directly.
```html theme={null}
```
If you are embedding existing packages consider generating a new edit link before embedding as they **expire after 60 minutes**.
When embedding the package editor, you may want to handle certain events such as when the package is sent by the user.
You can achieve this by listening for messages from the iframe.
```javascript theme={null}
window.addEventListener("message", (event) => {
// Validate origin
if (event.origin !== "https://sign.syngrafii.com" || !event.data) return;
// Handle action
switch (event.data.action) {
case "package_close":
// User has closed the package editor. You should continue with your workflow.
break;
case "package_send":
// User has sent the package and closed the package editor. You should continue with your workflow.
break;
case "session_expired":
// User session has expired. The package editor will show an Expired Session message
break;
}
}, false);
```
See the [Embed messaging guide](/v4/guides/embed-messaging) for more information.
## Redirecting
If your workflow does not allow for embedding via `iframe` you can optionally redirect your users to the package edit link
and have it redirect back to your site by setting the `options.embed.returnUrl` to a valid URL during the call to add package.
```http Request highlight={6,10-11} theme={null}
POST /packages/add
{
"name": "Embed Package Edtitor",
"type": "concurrent",
"state": "draft",
"generateEditLink": true,
"options": {
"embed": {
"focusTemplating": true,
"returnUrl": "https://example.com/your-return-url",
"returnState": "your-state"
}
},
"signers": [
{
"firstName": "signer",
"lastName": "one",
"email": "signer.one@example.com"
}
],
"documents": [
{
"fileName": "document.pdf",
"fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
}
]
}
```
# Embed messaging
Source: https://docs.iinkedsign.com/v4/guides/embed-messaging
Learn how to handle messages sent from an embedded signing or package editor.
## Overview
When embedding the package editor or package signing, the embedded frame will send messages to the parent window that can be used to control
your workflow and help with debugging during your integration.
## Handling embed messages
To handle messages sent from the embedded frame, you need to listen for the `message` event on the `window` object.
The event object contains information about the message, including the action being performed.
```javascript theme={null}
window.addEventListener("message", (event) => {
// Validate origin
if (event.origin !== "https://sign.syngrafii.com" || !event.data) return;
// Handle action
switch (event.data.action) {
case "package_close":
// User has closed the package editor. You should continue with your workflow.
break;
case "package_send":
// User has sent the package and closed the package editor. You should continue with your workflow.
break;
case "session_expired":
// User session has expired. The package editor will show an Expired Session message
break;
}
}, false);
```
You should always validate the origin of the message before processing it to ensure it comes from a trusted source.
## Embed message
The source of the message, which can be used to customize your workflow.
| Source | Description |
| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| syngrafii-app | Message was sent from the `Package Editor` or `Video Signing Room` app. |
| syngrafii-sign-app | Message was sent from the `Sign` app. The `Sign` app is also embedded in the `Video Signing Room` app, so you can receive messages from both sources. |
| syngrafii-embed | This source is used to **send** `embed_position` messages to `Video Signing Room` embedded signings. |
The action being performed.
| Action | Description |
| :------------------- | :--------------------------------------------------------------------------------------------------------------- |
| package\_add | User has added a new package. |
| package\_cancel | User has cancelled any changes to the package. They are still in the package editor. |
| package\_close | User has closed the package editor. You should continue with your workflow. |
| package\_open | The package has been opened by the package editor. |
| package\_save | User has saved any changes to the package. They are still in the package editor. |
| package\_send | User has sent the package and closed the package editor. You should continue with your workflow. |
| meeting\_end | Host has ended VSR meeting session. |
| meeting\_joining | User is joining VSR meeting session. |
| meeting\_join | User has joined VSR meeting session. |
| meeting\_start | Host has started VSR meeting session. |
| signing\_changed | User has modified signing; you can use this to track dirty state of signing and prevent navigation. |
| signing\_close | User has closed signing and was redirected to /notsent page. |
| signing\_finalize | User has finalized current document. |
| signing\_ignore | User has ignored save changes warning dialog. |
| signing\_next | User has opened next document for signing. |
| signing\_open | User has opened document for signing. |
| signing\_return | User has completed or closed signing and was redirected back to packages list. |
| signing\_return\_url | User has completed or closed signing and was redirected back to returnUrl. |
| signing\_save | User has saved signing progress; you can use this to track dirty state of signing and allow navigation. |
| signing\_sent | User has completed signing all documents and was redirected to /sent page. |
| session\_expired | User session has expired. The package editor will show an Expired Session message. |
| session\_expiring | User session is about to expire due to inactivity. They will be presented with a dialog to extend their session. |
| session\_extended | User session was extended by user. |
Additional data related to the action being performed. The structure of this object may vary depending on the action.
Indicates whether the action failed.
The error code if the action failed. This field is only present when `failed` is `true`.
See the [Errors guide](/v4/guides/errors) for more information.
# Embed signing
Source: https://docs.iinkedsign.com/v4/guides/embed-signing
Learn how to embed the signing experience into your web application.
## Overview
The Embed Signing feature allows you to integrate the document signing process directly into your web application. This provides a seamless experience for users, enabling them to sign documents without leaving your platform.
## Steps
When you want to embed the signing experience, you have to create a package with `generateSignerLinks` and the `embedded` package option set to `true`.
```http Request highlight={6,8} theme={null}
POST /packages/add
{
"name": "Embedded Package Signing",
"type": "concurrent",
"state": "open",
"generateSignerLinks": true,
"options": {
"embedded": true
},
"signers": [
{
"firstName": "signer",
"lastName": "one",
"email": "signer.one@example.com"
}
],
"documents": [
{
"fileName": "document.pdf",
"fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
}
]
}
```
```json Response highlight={8} theme={null}
{
"package": {
...
"signers": [
{
...
"signLink": {
"link": "https://sign.syngrafii.com/link/mzLzlN5zECs2SlS_VJ-njg"
},
...
}
],
...
}
}
```
To embed the signing or VSR experience in an iframe, you need to use the `signLink.link` URL provided in the add package response or by calling the [`packages/{packageId}/link/sign/{signerId}`](/v4/api/links/sign) endpoint directly.
```html theme={null}
```
Make sure to set the `allow` attribute on the iframe to enable necessary permissions like `geolocation` access.
```html theme={null}
```
Make sure to set the `allow` attribute on the iframe to enable necessary permissions like `geolocation`, `camera`, `microphone`, and `display-capture` access.
#### JavaScript for VSR host embedding
Embedding a video signing room for a **host** requires additional JavaScript to send the position of the iframe within the parent window. Without this information the screen share video will not be correctly cropped when shared with other signers.
```javascript VSR Host Embed Script theme={null}
```
When embedding the signing experience, you may want to handle certain events such as when the signing is completed or any errors occur. You can achieve this by listening for messages from the iframe.
```javascript theme={null}
window.addEventListener("message", (event) => {
// Validate origin
if (event.origin !== "https://sign.syngrafii.com" || !event.data) return;
// Handle action
switch (event.data.action) {
case "signing_sent":
// User has completed signing all documents and was redirected to /sent page.
break;
case "signing_close":
// User has closed signing and was redirected to /notsent page.
break;
case "session_expired":
// User session has expired due to inactivity
break;
}
}, false);
```
See the [Embed messaging guide](/v4/guides/embed-messaging) for more information.
# Errors
Source: https://docs.iinkedsign.com/v4/guides/errors
## HTTP status codes
| Code | Title | Description |
| ---: | ----------------- | --------------------------------------------------------------------------------------------------------------- |
| 200 | OK | The request has successfully been processed. |
| 400 | Bad Request | The request could not be processed because of an invalid request. |
| 403 | Forbidden | The user or API Key does not have permission to access the requested resource. |
| 404 | Not Found | The requested resource was not found. |
| 429 | Too Many Requests | Too many requests over a short period of time have been made to the server from the same IP address or API Key. |
| 500 | Server Error | An unexpected server error has occurred. |
### Examples
```json theme={null}
{
"error": "package_invalid_type",
"message": "Valid Package 'type' is required."
}
```
```json theme={null}
{
"error": "package_not_found",
"message": "The Package was not found or you do not have permission to access the Package."
}
```
## Common error patterns
Common errors such as data length, range, or type will be returned with a dynamic error code that follows these patterns.
| Error pattern | Meaning |
| -------------------------------- | --------------------------------------------------------------------------------------------------- |
| `{type}_not_found` | **Not Found**: The requested resource was not found. |
| `{type}_not_authorized` | **Not Authorized**: The current user or API Key is not authorized to access the requested resource. |
| `{type}_invalid_{error}` | **Invalid**: The request is invalid. |
| `{type}_exception_{error}` | **Exception**: An exception occurred while processing the request. |
| `{type}_feature_{error}` | **Feature**: The current organization's subscription does not have the required feature enabled. |
| `{type}_not_safe_{propertyName}` | **Not Safe**: The property contains data considered unsafe to store or share with other users. |
| `{type}_length_{propertyName}` | **Invalid Length**: The property data length is too short or too long. |
| `{type}_range_{propertyName}` | **Invalid Range**: The property data value is outside its allowed range. |
## Package errors
| Error | Description |
| :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| package\_add\_no\_documents | At least one document is required to add package in `open` state. |
| package\_add\_no\_signers | At least one signer is required to add package in `open` state. |
| package\_delete\_retention | Package is under a retention policy and cannot be deleted. |
| package\_duplicate\_recipients | One or more recipients have the same email address. |
| package\_duplicate\_recipients\_signer | One or more recipients have the same email address as a signer. |
| package\_duplicate\_signers | One or more signers have the same email address. |
| package\_duplicate\_signers\_host | One or more signers have the same email address as the host. |
| package\_duplicate\_witnesses\_signer | One or more witnesses have the same email address as a signer. |
| package\_exception | An unexpected error has occurred while processing the Package. Please contact iinked Sign Support for further assistance. |
| package\_exception\_cancel\_not\_open | Package is no longer in a open state and cannot be cancelled. |
| package\_exception\_send\_no\_documents | Package requires at least one document before sending to signers. |
| package\_exception\_send\_not\_draft | Package is no longer in a draft state and cannot be sent. |
| package\_exception\_send\_owner\_deleted | Package owner has been deleted and can no longer be sent. |
| package\_exception\_sign\_not\_open | Package is no longer available for signing. |
| package\_exception\_sign\_owner\_deleted | Package is no longer available for signing. |
| package\_exception\_update\_not\_updatable | You can no longer update this package. |
| package\_exception\_update\_package\_type\_not\_updatable | You can no longer update the package type. |
| package\_export\_forbidden | |
| package\_feature\_ds | You must upgrade your subscription to use digital signatures in a package. |
| package\_feature\_ds\_digidentity | You must upgrade your subscription to use Digidentity digital signatures in a package. |
| package\_feature\_package\_type | You must upgrade your subscription to create a Package. |
| package\_feature\_witness | You must upgrade your subscription to include witnesses in a package. |
| package\_invalid\_date | The package's sign-by date must be in the future. |
| package\_invalid\_meeting | The package's meeting date must be in the future. |
| package\_invalid\_recipient | Package owner cannot be added as a recipient. |
| package\_invalid\_search | Your search contains invalid characters. |
| package\_invalid\_security\_code\_signer\_mobile\_number | All signers require a mobile number to enable Text Message Multi-Factor Authentication. |
| package\_invalid\_security\_passphrase | You must provide a valid security passphrase. |
| package\_invalid\_time\_zone | You must provide a valid time zone. |
| package\_link\_not\_generated | Failed to generate the requested package link. |
| package\_locked | Package is currently being updated by another member. |
| package\_modification\_limit\_exceeded | This package has exceeded the modification limit and can no longer be updated. |
| package\_no\_host | Package must have one Signer assigned 'host' role. |
| package\_no\_signers | |
| package\_not\_authorized | The Package was not found or you are not authorized to access the Package. |
| package\_not\_authorized\_add | You are not authorized to add packages. |
| package\_not\_authorized\_state | You are not authorized to add packages in '' state. |
| package\_not\_found | The Package was not found or you are not authorized to access the Package. |
| package\_not\_safe\_message | 'Message' cannot contain any website domains or email addresses while subscription is under a trial. |
| package\_notification\_exception\_link\_text | You must provide 'linkText' when including a 'link' in the notification. |
| package\_notification\_link\_text | |
| package\_one\_host | There can only be one host. |
| package\_options\_digital\_signature\_require\_cac\_none | |
| package\_options\_digital\_signature\_require\_flattening\_none | |
| package\_options\_invalid\_enhancedPrivacy | '' cannot be enabled for this package type. |
| package\_options\_message\_not\_safe | The system message '' cannot contain any website domains or email addresses. |
| package\_options\_message\_not\_safe\_trial | The system message '' cannot contain any website domains or email addresses while subscription is under a trial. |
| package\_options\_notice\_not\_safe | A consent notice '' cannot contain any website domains or email addresses. |
| package\_options\_notice\_not\_safe\_on\_trial | A consent notice '' cannot contain any website domains or email addresses while subscription is under a trial. |
| package\_options\_notice\_not\_safe\_trial | |
| package\_options\_require\_consent | When CAC is set to `none`, Require Consent must be enabled and must require signing or video recording. |
| package\_options\_securityCode\_not\_allowed\_on\_trial | Multi-Factor Authentication is not available while your account is on trial. |
| package\_rescind\_not\_open | |
| package\_review\_forbidden | You can no longer review documents for this package. |
| package\_send\_invalid\_state | The package cannot be sent in its current state. |
| package\_send\_no\_documents | The package must contain at least one document before it can be sent. |
| package\_send\_not\_ready | Package cannot be sent, add at least one document or enable identity verification for a signer. |
| package\_update\_delete\_host | Host cannot be deleted from a package. |
| package\_update\_delete\_signer\_not\_found | Signer does not exist and cannot be deleted from package. |
| package\_update\_no\_signers | At least one signer is required after updating a package. |
| package\_verification\_not\_supported | Identity verification is not supported for this package type. |
## Document errors
| Error | Description |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------- |
| document\_exception | An unexpected error has occurred while processing the Document. Please contact iinked Sign Support for further assistance. |
| document\_not\_authorized | The Document was not found or you are not authorized to access the Document. |
| document\_not\_found | The Document was not found or you are not authorized to access the Document. |
## Signer errors
| Error | Description |
| :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| signer\_exception | An unexpected error has occurred while processing the Document Signer. Please contact iinked Sign Support for further assistance. |
| signer\_forward\_invalid\_email | A Signer with the provided email address already exists in the Package. |
| signer\_invalid\_email\_exists | A Document Signer already exists with the provided email address. |
| signer\_invalid\_mobile\_number\_exists | A Document Signer already exists with the provided mobile number. |
| signer\_invalid\_package\_started | You cannot add a Signer to a Signing Package that has already been started. |
| signer\_invalid\_role | The Signer Role is invalid for the Package Type. |
| signer\_location\_required | You are required to share your location before you can continue. |
| signer\_lockout | You are temporarily locked out of this document. Try again later. |
| signer\_not\_authorized | The Document Signer was not found or is longer authorized to access the Document. |
| signer\_not\_found | The Document Signer was not found or is no longer authorized to access the Document. |
| signer\_security\_code\_challenge | You must provide verification code sent to your mobile device to access the Package. |
| signer\_security\_not\_authorized | |
| signer\_security\_passphrase\_challenge | You must provide secret passphrase to access the Package. |
| signer\_witness\_not\_allowed | Signer Witness is not allowed for this package type |
## Form errors
| Error | Description |
| :--------------------------------------- | :-------------------------------------------------------------- |
| form\_exactly\_one\_form\_signer | A single signer must be designated with the 'form' type. |
| form\_exception\_create | We were not able to start your signing. Please try again later. |
| form\_exception\_create\_already\_signer | You are already a secondary signer or recipient on this form. |
| form\_invalid\_package\_type | The selected package type is not compatible with forms. |
| form\_not\_authorized | |
| form\_not\_available | The requested signing form is no longer active. |
## Template errors
| Error | Description |
| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------- |
| template\_code\_exists | The template code is already associated with an existing template. |
| template\_code\_reserved | This template code is exclusively designated for global templates. Please select an alternative template code. |
| template\_document\_code\_exists | Each document must have a unique document code. |
| template\_forward\_signing\_not\_authorized | You are not authorized to enable Forward Signing. |
| template\_not\_authorized | The Template was not found or you are not authorized to access the Template. |
| template\_recipient\_duplicate\_template\_role | All recipient role names must be unique in a template. |
| template\_signer\_duplicate\_template\_role | All signer role names must be unique in a template. |
## File errors
| Error | Description |
| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| file\_conversion\_failed | We were not able to convert the file '' to PDF. Try exporting it as a PDF from the application directly. |
| file\_conversion\_invalid\_page\_count | The file cannot be converted as it's pages exceed the maximum number of pages supported. |
| file\_conversion\_max\_size\_exceeded | Converted PDF file size has exceeded the maximum file size of . |
| file\_conversion\_not\_supported | Conversion to PDF is not supported for the uploaded file ''. |
| file\_exception | |
| file\_exception\_form\_fields | While saving your document we were unable to update one or more form fields. Please try again or contact support. |
| file\_exception\_merge\_tags | An unexpected error occurred while processing the file for 'merge' tags. |
| file\_exception\_metadata\_annotation | |
| file\_exception\_pdf\_annotation | |
| file\_exception\_template\_tags | An unexpected error occurred while processing the file for 'template' tags. |
| file\_invalid | Invalid file (). |
| file\_invalid\_custom\_field\_anchor | |
| file\_invalid\_custom\_field\_tag | |
| file\_invalid\_data | Invalid file. |
| file\_invalid\_empty | Invalid file. File is empty. |
| file\_invalid\_external\_file\_id | Invalid external file 'fileExternalId'. |
| file\_invalid\_external\_id\_exists | A file already exists with an 'externalId' of ''. |
| file\_invalid\_file\_id | Invalid internal file 'fileId'. |
| file\_invalid\_not\_found | The file '' is invalid or no longer exists. |
| file\_invalid\_url | Invalid external file 'url'. |
| file\_not\_authorized | You are not authorized to add files. |
| file\_not\_supported | File contains features that are not supported and cannot be processed. |
| file\_not\_supported\_acro\_form | File contains an unsupported or invalid PDF Form and cannot be processed. |
| file\_not\_supported\_io\_error | PDF Error |
| file\_not\_supported\_pdf\_error | PDF Error |
| file\_not\_supported\_xfa | File contains an unsupported PDF Form (Dynamic XFA) and cannot be processed. |
| file\_password\_protected | File is password protected and cannot be processed. |
| file\_pdf\_scan\_exception | PDF scanning error. Could not scan pdf properties and text content. |
# External data
Source: https://docs.iinkedsign.com/v4/guides/external-data
Learn how to attach external data to your signing packages to streamline integration.
## Overview
You can attach external data to signing packages and documents to help integrate with your existing systems. This allows you to associate your internal identifiers or metadata with the packages and documents managed through our API.
## Attaching external data to packages
When creating a signing package, you can attach external data to it using the `externalData` field in the add package request.
This data can be any set of JSON-serializable key-value pairs and will be stored with the package.
```http Request highlight={18-21} theme={null}
POST /packages/add
{
"name": "New Package",
"type": "concurrent",
"signers": [
{
"firstName": "Signer",
"lastName": "One",
"email": "signer.one@example.com"
}
],
"documents": [
{
"fileName": "document.pdf",
"fileId": "51400d7a-4f34-4844-9138-46a365130f97"
}
],
"externalData": {
"internalId": "12345",
"customerId": "67890"
},
"returnPackage": false
}
```
When you call future package-related endpoints, such as retrieving package details or checking the package status, the `externalData` field will be included in the response.
```http Request theme={null}
GET /packages/{packageId}/status
```
```json Response highlight={4-7} theme={null}
{
"packageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
...
"externalData": {
"internalId": "12345",
"customerId": "67890"
}
}
```
Package related webhooks will also include the `externalData` field in their payloads, allowing you to access this information during webhook processing.
```json Payload highlight={3-6} theme={null}
{
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"externalData": {
"internalId": "12345",
"customerId": "67890"
},
"action": "package_add",
"eventId": "e9b8fe63-4a19-4446-bd6e-cb34b72b411e",
"eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
"eventTime": "2022-02-23T20:19:28.9357901Z"
}
```
## Attaching external ID to documents
You can also attach an external ID to individual documents within a package using the `externalId` query parameter when uploading files.
```http Request highlight={1} theme={null}
POST /files/upload?externalId=doc12345
Content-Type: multipart/form-data
Content-Disposition: form-data; filename="document.pdf"
```
```json Response highlight={5} theme={null}
{
"files": [
{
"fileId": "5997903d-2975-4c71-84d4-536255529b66",
"externalId": "doc12345",
"name": "document.pdf",
"fileName": "document.pdf",
"type": "temporary"
}
]
}
```
When you later retrieve package details, the `externalId` will be included in the response.
```http Request theme={null}
GET /packages/{packageId}/status
```
```json Response highlight={7} theme={null}
{
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
...
"documents": [
{
"documentId": "ad8eac67-94e9-481b-a799-7396b447b8eb",
"externalId": "doc12345",
"fileName": "document.pdf",
...
}
]
}
```
# Package options
Source: https://docs.iinkedsign.com/v4/guides/package-options
Learn how to configure signing package options to enhance your integration.
## Overview
When creating a signing package, you can configure various package options to tailor the signing experience to your needs. These options include settings for reminders, expiration, authentication, and more.
See the [Package options reference](/v4/reference/package-options/package-options) for more information.
## Defaults
You can manage the default package options for your entire organization under `Settings` > `Signing Defaults`. These defaults will apply to all packages unless overridden at the package level through package options.
## Consent
Release 4.2 adds package-level consent controls. Enable consent with `consentOptions.required`, then select the actions that require consent.
```json theme={null}
{
"options": {
"cac": "none",
"consentOptions": {
"required": true,
"requiredSigning": true,
"requiredVideoRecording": false,
"autoAcceptPolicyDays": 90
}
}
}
```
`required` defaults to `false`, `requiredSigning` defaults to `true`, `requiredVideoRecording` defaults to `false`, and `autoAcceptPolicyDays` defaults to `90`.
When `cac` is `none`, consent must be enabled for signing or supported video
recording. Video recording consent is only available for Video Signing Room
packages.
`autoAcceptPolicyDays` lets a member reuse a previously accepted consent when the consent type and notice version are unchanged. Set it to `0` to require a new acceptance each time.
### Custom consent notices
Use `notices` to append custom text to the system notice for `signing`, `verification`, or `video_recording`. Provide a default value and optional locale-specific values.
```json theme={null}
{
"options": {
"notices": {
"signing": {
"default": "I agree to use an electronic signature.",
"locale": {
"fr": "J'accepte d'utiliser une signature electronique.",
"es": "Acepto usar una firma electronica.",
"de": "Ich stimme der Verwendung einer elektronischen Signatur zu."
}
}
}
}
}
```
Custom notice values are limited to 1,024 characters and cannot contain website domains or email addresses. Locale lookup uses the exact locale, then its language, then the default value.
## Digital signatures
Release 4.2 adds digital signature provider configuration. Map each enabled signature type to one or more providers.
```json theme={null}
{
"options": {
"cac": "none",
"formFlattening": "none",
"consentOptions": {
"required": true,
"requiredSigning": true
},
"digitalSignatures": {
"signatureTypes": {
"qes": ["digidentity"]
}
}
}
}
```
The supported signature type is `qes` (Qualified Electronic Signature). Digital signatures require signing consent, `cac` set to `none`, and `formFlattening` set to `none` or omitted. Signature types and providers must also be enabled for your subscription and organization.
## Geolocation
When creating a signing package, you can enable geolocation tracking to capture the signer's location during the signing process.
Request Signers Geolocation while signing documents, joining VSR meetings, performing IDV, and connecting to a mobile signature pad.
Customize how Geolocation is collected.
3.6
Require geolocation to be shared before allowing the signer to continue.
Require geolocation to be shared before the signer can sign documents.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can use signature pad.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can join VSR meetings.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can verify their identity.
(`required` must also be set to `true`)
## Multi-Factor Authentication (MFA)
You can enhance the security of your signing packages by enabling Multi-Factor Authentication (MFA) for signers. This adds an extra layer of verification during the signing process.
Enabled 2FA security code.
All signers will require a valid mobile phone number to enable mobile MFA.
Enabled 2FA security passphrase.
You must also set a passphrase as part of add or update request to enabled 2FA security passphrase.
```json theme={null}
{
"options": {
"securityPassphrase": true,
...
},
"securityPassphrase": "mySecretPassphrase"
}
```
## Signatures
You can customize signature options to control how signers sign the documents.
Override the default ink color `#0000FF` for Ink to Sign signatures and initials with a valid #-hexadecimal RGB color value.
2.10
Set preferred default mark type.
4.0
Enable all mark types.
Enabled click to sign `Accept It`.
Enabled type to sign `Type It`.
Enabled touch to sign `Ink It`.
Allows signer to use desktop mouse to draw signature via touch to sign.
Allow signers to apply their last used iink signature during a signing session. Defaults to `false`.
4.1
## Video Signing Room
When creating a Video Signing Room (VSR) package, you can configure specific options to enhance the VSR experience.
Automatically starts video recording after host starts meeting and first attendee joins.
Disables video recording feature preventing host from recording signing session.
Add a retention period to all package videos to prevent deletion. (ISO 8601 duration)
Share meeting details and videos with guest signers via MasterFile.
Send email notification to each signer when Video Signing Room meeting is scheduled.
Include ICS compatible meeting invitation with email notification to schedule meeting date and time in recipients' calendar.
# Signing
Source: https://docs.iinkedsign.com/v4/guides/sign
Learn how to create and send a signing package to signers.
## Overview
This guide will walk you through the process of sending documents to one or more signers for their signatures using our API.
## Steps
First, upload the documents that need to be signed. You can upload multiple documents in various formats such as PDF, DOCX, etc.
```http Request theme={null}
POST /files/upload
Content-Type: multipart/form-data
Content-Disposition: form-data; filename="document.pdf"
Content-Type: application/pdf
```
```json Response theme={null}
{
"fileId": "51400d7a-4f34-4844-9138-46a365130f97",
"name": "document.pdf",
"timeCreated": "2025-11-06T16:07:16.1913089Z",
"fileName": "document.pdf",
"type": "temporary"
}
```
Make sure to store the returned `fileId` for use in next steps.
See the [Files upload API](/v4/api/files/upload) for more information.
Next, create a signing package by providing details such as the package name, description, sign by date, signers, and documents.
```http Request highlight={16} theme={null}
POST /packages/add
{
"name": "New Package",
"timeSignBy": "2025-12-31T23:59:59Z",
"type": "concurrent",
"signers": [
{
"firstName": "Signer",
"lastName": "One",
"email": "signer.one@example.com"
}
],
"documents": [
{
"fileName": "document.pdf",
"fileId": "51400d7a-4f34-4844-9138-46a365130f97"
}
],
"returnPackage": false
}
```
Make sure you reference the correct `fileId` obtained from the document upload step.
```json Response theme={null}
{
"packageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"package": null,
}
```
Make sure to store the returned `packageId` for use in next steps.
See the [Packages add API](/v4/api/packages/add) for more information.
You can check the status of the package at any time using the package ID.
This step is useful for tracking the progress of the signing process if you are not using [webhooks](/v4/guides/webhooks).
```http Request highlight={3} theme={null}
GET /packages/{packageId}/status
```
```json Response theme={null}
{
"packageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "New Package",
"type": "concurrent",
"state": "executed",
"documents": [
{
"documentId": "f3223ba8-ed0e-44eb-bee3-e99b03ff1b1f",
"revisions": [
{
"revisionId": "4ee3d092-a390-4459-b5e1-753575d66af9",
"signerId": "30d4193b-81d6-463e-a861-4e272c324991"
}
]
}
],
"signers": [
{
"signerId": "30d4193b-81d6-463e-a861-4e272c324991",
"firstName": "signer",
"lastName": "one",
"email": "signer.one@syngrafii.com"
}
]
}
```
The `state` field indicates the current status of the package. Once all signers have signed their documents, the state will be `executed`.
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
See the [Packages status API](/v4/api/packages/status) for more information.
After all signers have completed signing, you can download the signed documents.
```http Request theme={null}
GET /packages/{packageId}/documents/{documentId}/pdf/executed/download
```
Use the package status endpoint from the previous step to retrieve the document IDs of the signed documents to download.
See the [Packages download API](/v4/api/packages/download) for more information.
# Identity verification (IDV)
Source: https://docs.iinkedsign.com/v4/guides/sign-idv
Learn how to create a signing package with identity verification (IDV) enabled.
## Overview
Identity verification can be enabled when adding a package by setting the required identity verification `policyCode`
and enabling the `verify` option on each signer that requires their identity to be verified.
Identity verification policies must be enabled on your account before they can be used in signing packages.
[Request IDV to be enabled on your account](https://sign.syngrafii.ca/form/VAJZ2rNRpkeuoKJ2a_h4Uw)
## Policies
| Policy Code | Pass-To-Sign | Region | Retries |
| :--------------------------------------- | :----------: | :----: | :-----: |
| trulioo3\_document | false | Any | 2 |
| trulioo3\_document\_required | true | Any | 2 |
| trulioo3\_document\_ca\_strict | false | CA | 2 |
| trulioo3\_document\_ca\_strict\_required | true | CA | 2 |
**Pass-To-Sign** indicates whether the signer must successfully complete identity verification before they can sign their documents.
## Add package with IDV
To create a signing package with identity verification enabled:
Set the `verificationOptions.policyCode` to the desired verification policy under package `options`.
Set the `verify` property to `true` for each signer that needs to complete identity verification.
```http Request highlight={9,17} theme={null}
POST /packages/add
{
"name": "New Package with IDV",
"type": "concurrent",
"state": "open",
"options": {
"verificationOptions": {
"policyId": null,
"policyCode": "trulioo3_document"
}
},
"signers": [
{
"firstName": "signer",
"lastName": "one",
"email": "signer.one@syngrafii.com",
"verify": true
}
],
"documents": [
{
"fileName": "document.pdf",
"fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
}
]
}
```
See the [Packages add API](/v4/api/packages/add) for more information.
## Signer experience
When the signer opens the signing session, they will be prompted to complete the identity verification process before they can proceed to sign the documents. The verification process will follow the rules defined in the selected verification policy.
## Verification status
You can check the identity verification status of each signer by calling the `/packages/{packageId}/status` endpoint. The signer's verification `state` and `verificationId` will be included in the response.
```json Response highlight={8-9} theme={null}
{
"packageId": "08aba360-4466-4463-8b4b-9585d3de4b33",
...
"signers": [
{
"signerId": "dff8f8cc-fe2d-428e-9a8c-bcf1a2b187ce",
"verification": {
"verificationId": "6297e62f-d49d-4f2e-8369-e24ce4316e73",
"state": "passed"
}
}
]
}
```
See the [Packages status API](/v4/api/packages/status) for more information.
## Verification results
You can retrieve detailed verification results for a signer by calling `/packages/{packageId}/signers/{signerId}/verification` endpoint.
```json Response theme={null}
{
"verificationId": "6297e62f-d49d-4f2e-8369-e24ce4316e73",
"packageId": "08aba360-4466-4463-8b4b-9585d3de4b33",
"signerId": "dff8f8cc-fe2d-428e-9a8c-bcf1a2b187ce",
"state": "passed",
"results": [
...
]
}
```
The verification results provide detailed information about the identity verification process, including any documents submitted and their verification outcomes.
See the [Verifications signer API](/v4/api/verifications/signer) for more information.
# Links
Source: https://docs.iinkedsign.com/v4/guides/sign-links
Learn how to create and utilize package signing links.
## Overview
When adding or updating a package you can set `generateSignerLinks` to `true` and return signer links. Signer links are URLs that allow signers to sign packages or join VSR meetings.
You can utilize these links to create custom integrations, for example, sending them via email, SMS, or embedding them in your own applications.
## Request
```http Request highlight={6} theme={null}
POST /packages/add
{
"name": "New Package with Links",
"type": "concurrent",
"state": "open",
"generateSignerLinks": true,
},
"signers": [
{
"firstName": "signer",
"lastName": "one",
"email": "signer.one@syngrafii.com"
}
],
"documents": [
{
"fileName": "document.pdf",
"fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
}
]
}
```
Links can be generated when calling [`packages/add`](/v4/api/packages/add), [`packages/update`](/v4/api/packages/update) , or [`packages/{packageId}/link/edit`](/v4/api/links/edit) and [`packages/{packageId}/link/sign/{signerId}`](/v4/api/links/sign) API endpoints.
When you add a package with `generateSignerLinks` set to `true`, subsequent requests to update the package will also return new signer links. You can override this behavior by setting `generateSignerLinks` to `false` in the `packages/update` request.
## Response
A signing link will automatically take the signer to the next unsigned document or IDV if enabled.
```json Response theme={null}
{
"package": {
...
"signers": [
{
...
"signLink": "https://sign.syngrafii.com/link/abcdef123456"
...
}
],
...
}
}
```
A VSR meeting link will automatically take the participant to the VSR meeting room lobby.
```json Response theme={null}
{
"package": {
...
"signers": [
{
...
"meetingLink": "https://sign.syngrafii.com/link/abcdef123456"
...
}
],
...
}
}
```
An edit link allows you to embed our [package editor](/v4/guides/embed-editor) experience within an iframe in your application.
If you set `embedded` to `true` in the package options when adding or updating a package, the edit link will be included in the response.
```json Response theme={null}
{
"package": {
...
"editLink": {
"link": "https://sign.syngrafii.com/link/abcdef123456"
},
...
}
}
```
You can also generate a new edit link for an existing package by calling the [Packages link API](/v4/api/links/edit) endpoint:
```http Request theme={null}
POST /packages/{packageId}/link/edit
```
## Linking
To link to a signing package or VSR meeting, you can use the `signLink` or `meetingLink` URL provided in the package details. This link will take the user directly to the signing experience for their documents.
```html theme={null}
Sign Document
```
```html theme={null}
Join Meeting
```
## Redirecting
During add package you can optionally specify a `returnUrl` and `returnState` for each signer. When a signer completes the signing process, they will be redirected back to your application using the specified `returnUrl` and optional `returnState`.
```http Request highlight={6,12-13} theme={null}
POST /packages/add
{
"name": "New Package with Return URL",
"type": "concurrent",
"state": "open",
"generateSignerLinks": true,
"signers": [
{
"firstName": "signer",
"lastName": "one",
"email": "signer.one@syngrafii.com",
"returnUrl": "https://example.com/thank-you",
"returnState": "some-state"
}
],
"documents": [
{
"fileName": "document.pdf",
"fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
}
]
}
```
### Return parameters
When the signer is redirected back to your application, the following parameters will be included in the query string:
The package ID of the signing package.
The signer ID of the signer.
When `true`, indicates that the signing process was completed successfully.
The value of `returnState` if provided when adding the signer.
## Embedding
You can also embed the signing experience directly into your application using an **iframe**. This allows users to sign documents without leaving your site.
View the [Embed signing guide](/v4/guides/embed-signing) for more information.
## Lifetime
Signing links are valid until the signing package becomes executed, rescinded, expired, or deleted. They will expire within 24 hours of their sign by date.
Meeting links will allow hosts and signers to still join the VSR lobby for up to 7 days after it is executed. They will expire 7 days after the scheduled meeting start time.
When updating a signer's:
* **Email address** => all existing signer links will be invalidated.
* **Mobile number** => all existing mobile signer links will be invalidated.
It is recommended that you update any existing links you might have stored from previous requests to ensure signer links remain valid.
# Qualified Electronic Signatures (QES)
Source: https://docs.iinkedsign.com/v4/guides/sign-qes
Learn how to create a signing package with Qualified Electronic Signatures (QES).
## Overview
A Qualified Electronic Signature (QES) uses a qualified digital certificate issued by a Trusted Service Provider. Enable QES when adding a package by configuring `options.digitalSignatures.signatureTypes`.
Digital signatures and the selected QES provider must be enabled for your
subscription and organization before you can use them in a signing package.
## Providers
The following QES providers are supported:
| Value | Provider |
| :------------ | :---------- |
| `digidentity` | Digidentity |
Use the serialized provider values shown in the table when configuring the request.
## Add a package with QES
Set `options.digitalSignatures.signatureTypes.qes` to an ordered array of enabled providers. QES also requires signing consent, `cac` set to `none`, and `formFlattening` set to `none` or omitted.
QES is currently supported only for packages using the `Sequential` signing
workflow.
The final signature completed by each signer on a document is automatically
converted to a digital signature.
```http Request highlight={7-17} theme={null}
POST /packages/add
{
"name": "New Package with QES",
"type": "Sequential",
"state": "open",
"options": {
"cac": "none",
"formFlattening": "none",
"consentOptions": {
"required": true,
"requiredSigning": true
},
"digitalSignatures": {
"signatureTypes": {
"qes": ["digidentity"]
}
}
},
"signers": [
{
"firstName": "Signer",
"lastName": "One",
"email": "signer.one@example.com"
}
],
"documents": [
{
"fileName": "document.pdf",
"fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
}
]
}
```
See the [Packages add API](/v4/api/packages/add) and [digital signature options reference](/v4/reference/package-options/digital-signature-options) for the complete request contract.
## Signer experience
After the signer completes all documents in the package, they are prompted to authorize the QES through the selected provider. QES authorization is the final step in the signing session.
## Check signing status
Call `/packages/{packageId}/status` to monitor the package. A revision's `isSigned` property becomes `true` after that signer completes the revision. The document and package `isExecuted` properties become `true` after all required signers complete the signing workflow.
```http Request theme={null}
GET /packages/{packageId}/status
```
```json Response highlight={3,7,12} theme={null}
{
"packageId": "08aba360-4466-4463-8b4b-9585d3de4b33",
"isExecuted": true,
"documents": [
{
"documentId": "d3386e4e-d5db-41f0-82ad-d3427fe57495",
"isExecuted": true,
"revisions": [
{
"revisionId": "6fcf36b4-ce54-45b9-8892-ce2d92a7e669",
"signerId": "dff8f8cc-fe2d-428e-9a8c-bcf1a2b187ce",
"isSigned": true
}
]
}
]
}
```
See the [Packages status API](/v4/api/packages/status) for the complete response.
## View the QES result
After the document is executed, download its executed PDF. The PDF contains the applied QES and certificate information for validation in a compatible PDF viewer.
```http Request theme={null}
GET /packages/{packageId}/documents/{documentId}/pdf/executed/download
```
See the [Packages download API](/v4/api/packages/download) for more information.
# Template data
Source: https://docs.iinkedsign.com/v4/guides/template-data
Learn how to pre-populate template fields to automate your document templating.
## Overview
When creating or updating a signing package from a template, you can pre-populate template fields with specific data.
This allows for greater automation and customization of your document templates, ensuring that the generated documents contain
the necessary information without requiring manual input during the signing process.
## Steps
When adding a package, you can pre-populate templated fields in your documents by passing along template data values.
This feature requires you to assign unique **data IDs** to each of the templated fields you want to set through our `template editor` or `templating tags`.
Currently only `text` and text `multiline` fields are supported.
### Template editor
Manually assign data IDs using the template editor in iinked Sign by selecting a field and setting the **Data ID** property in the field settings.
### Templating tags
Alternatively, if you template your documents via templating tags, you can assign data IDs using the appropriate `id` tagging syntax.
```plaintext theme={null}
{{s_1:text:id_text1}}
{{s_1:multiline:id_multiline1}}
```
See the [Template tags guide](/v4/guides/template-tagging/introduction) for more information.
When creating or updating a signing package using the `packages/add` or `packages/update` endpoints, you can pre-populate template fields by including the `templateData` object with each document in your request.
Populate the `templateData` field of each document with a set of key/value pairs, with the key being the unique **data ID** value you assigned to your templated field.
In the example below, the template requires a **text** field with a data ID of `text1`, and a text **multiline** field with a data ID of `multiline1`
```http Request highlight={28-31} theme={null}
POST /packages/add
{
"type": "concurrent",
"state": "open",
"name": "From Template with Data",
"templateId": "{{template_id}}",
"signers": [
{
"templateRole": "Signer 1",
"firstName": "Signer",
"lastName": "One",
"email": "{{signer_1_email}}",
"mobileNumber": null
}
],
"recipients": [
{
"templateRole": "Recipient 1",
"firstName": "Recipient",
"lastName": "One",
"email": "{{recipient_1_email}}",
"mobileNumber": null
}
],
"documents": [
{
"templateDocumentId": "{{template_document_1_id}}",
"templateData": {
"text1": "Set Text Field Value",
"multiline1": "Set Multiline Field Value Line 1\nSet Multiline Field Value Line 2"
}
}
]
}
```
After the signers have signed their documents and the package has been finalized you can retrieve the values of all fields in the
package by calling the `/package/{packageId}/data` endpoint.
```http Request theme={null}
GET /packages/{package_id}/data
```
```json Response expandable theme={null}
{
"packageId": "27acf4e5-8fef-4370-aea8-96c8c41fa6c2",
"name": "Template Data Example",
"type": "Sequential",
"state": "open",
"documents": [
{
"documentId": "f1c3d1a6-0430-4d0c-8140-2e33aead12d5",
"packageId": "27acf4e5-8fef-4370-aea8-96c8c41fa6c2",
"name": null,
"fileName": "tags-data-id.pdf",
"state": "open",
"data": [
{
"id": "signer_1-text_1",
"dataId": "text1",
"signerId": "093bdc63-7e6c-450f-a423-7b294ad0901a",
"source": "template",
"type": "text",
"value": "text1-value-xxx",
"pageNumber": 1
},
{
"id": "signer_1-text_2",
"dataId": "text2",
"signerId": "093bdc63-7e6c-450f-a423-7b294ad0901a",
"source": "template",
"type": "text",
"value": "text2-value-yyy",
"pageNumber": 1
},
{
"id": "signer_1-text_3",
"dataId": "text3",
"signerId": "093bdc63-7e6c-450f-a423-7b294ad0901a",
"source": "template",
"type": "text",
"value": "text3-value-zzz",
"pageNumber": 1
},
{
"id": "signer_1-multiline_2",
"dataId": "multiline1",
"signerId": "093bdc63-7e6c-450f-a423-7b294ad0901a",
"source": "template",
"type": "multiline",
"value": "multiline1-value-xxx multiline1-value-yyy",
"pageNumber": 1
},
{
"id": "signer_2-text_4",
"dataId": "text4",
"signerId": "7d9c2386-8979-4f1f-afd9-2a51eb4a3193",
"source": "template",
"type": "text",
"value": "text4-value-xxx",
"pageNumber": 1
},
{
"id": "signer_2-text_5",
"dataId": "text5",
"signerId": "7d9c2386-8979-4f1f-afd9-2a51eb4a3193",
"source": "template",
"type": "text",
"value": "text5-value-yyy",
"pageNumber": 1
}
]
}
]
}
```
# Custom tags
Source: https://docs.iinkedsign.com/v4/guides/template-tagging/custom-tags
Learn about how to create and use custom template tags in your documents.
## Overview
Custom template tags are a powerful feature that allow you to add your organization's custom fields to your documents as tags.
## Custom tag syntax
Unlike standard template tags, which are enclosed in double braces `{{tag}}`, custom template tags are enclosed in triple braces `{{{tag}}}`.
```handlebars theme={null}
{{{signer_1:customtag}}}
```
## Creating custom tags
You can create custom tags in your iinked Sign account by navigating to the `Custom Fields` section in the settings menu.
1. Go to your iinked Sign settings page.
2. Select `Custom Fields` from the left panel.
3. Click on `New Custom Field` and fill in the required details.
* Set `Access` to `Organization`.
* Set `Auto Field` to `Custom Tag`.
* Set `Custom Tag Name` to a unique tag name.
* Optionally, configure other settings such as validation, default value, or size.
4. Save the custom field.
5. Copy the custom tag you created (e.g., `{{{s_1:customtag}}}`) and insert it into your document where you want the custom field to appear.
Use the `Custom Tag Preview` feature in the `Custom Fields` editor to copy your custom tag accurately.
Custom tag names must be unique within your organization to avoid conflicts. The name should be alphanumeric and not contain spaces or any special characters including dashes or underscores.
## Examples
### Custom text field
To create a custom text field for signer 1 with the custom tag name `mytext`, use the following syntax:
```handlebars theme={null}
{{{s_1:mytext}}}
```
### Custom radio field
To create a custom radio button field for signer 1 with the custom tag name `myradio`, use the following syntax:
```handlebars theme={null}
{{{s_1:myradio.1}}} Option 1
{{{s_1:myradio.2}}} Option 2
{{{s_1:myradio.3}}} Option 3
```
### Custom checkbox field
To create a custom checkbox field for signer 1 with the custom tag name `mycheckbox`, use the following syntax:
```handlebars theme={null}
{{{s_1:mycheckbox.1}}} I agree to the terms and conditions.
```
# Date formats
Source: https://docs.iinkedsign.com/v4/guides/template-tagging/date-formats
Learn about the various date format options available for date-related template tags.
## Overview
For date-related tags, you can specify the date format by appending a format to the date tag as follows:
```handlebars theme={null}
{{s_:date_}}
```
| Option | Long | Short | Output (en-CA) |
| ----------------- | ----------------------------- | ------------------ | ------------------ |
| Date `default` | `{{s_#:date}}` | `{{s_#:d}}` | 2022-11-21 |
| Date Time | `{{s_#:date_datetime}}` | `{{s_#:d_dt}}` | 2022-11-21 2:25 PM |
| Time | `{{s_#:date_time}}` | `{{s_#:d_t}}` | 2:25 PM |
| Time Long | `{{s_#:date_timelong}}` | `{{s_#:d_tl}}` | 2:25:50 PM |
| Day | `{{s_#:date_day}}` | `{{s_#:d_dy}}` | 21 |
| Day With Suffix | `{{s_#:date_daywithsuffix}}` | `{{s_#:date_dws}}` | 21st |
| Day Of Week | `{{s_#:date_dayofweek}}` | `{{s_#:d_dow}}` | Monday |
| Day Of Week Short | `{{s_#:date_dayofweekshort}}` | `{{s_#:d_dows}}` | Mon |
| Month | `{{s_#:date_month}}` | `{{s_#:d_m}}` | 11 |
| Month Short | `{{s_#:date_monthshort}}` | `{{s_#:d_ms}}` | Nov |
| Month Long | `{{s_#:date_monthlong}}` | `{{s_#:d_ml}}` | November |
| Year | `{{s_#:date_year}}` | `{{s_#:d_y}}` | 2022 |
| Year Short | `{{s_#:date_yearshort}}` | `{{s_#:d_ys}}` | 22 |
| Year Month | `{{s_#:date_yearmonth}}` | `{{s_#:d_ym}}` | November 2022 |
# Introduction
Source: https://docs.iinkedsign.com/v4/guides/template-tagging/introduction
Learn how to use template tags to help automate your document templating.
## What are template tags?
Template tags are placeholders within your documents that are automatically replaced with fields when creating or updating a signing package.
This allows for greater flexibility and automation in document templating, as you can create documents with template tags
that adapt to different contexts and user inputs.
## Tag syntax
Template tags are defined directly in your documents using double curly braces `{{ }}` and can include various parameters to customize their behavior.
For example, a simple template tag for a text field might look like this:
```handlebars theme={null}
{{signer_1:text}}
```
When the document is processed, this tag will be replaced with a text field for the first signer.
## Structure
Template tags generally follow this structure:
```handlebars theme={null}
{{signer_:[_][_]...}}
```
## Signer identifiers
| Signer identifier | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `signer_host` | Specifies the host of a **Video Signing Room** or **In Person** signing package. |
| `signer_1` | Specifies the first signer. |
| `signer_2` | Specifies the second signer. |
| `signer_tag` | Specifies the signer assigned the user-defined `tag` identifier. See [Signer tags](/v4/guides/template-tagging/signer-tags). |
| ... | ... |
When a signer has a user-defined signer tag, that value takes precedence over the generated number or host identifier.
# Signer tags
Source: https://docs.iinkedsign.com/v4/guides/template-tagging/signer-tags
Learn how to associate template tags with signers using user-defined identifiers.
## Overview
Signer tags let you associate document template tags with signers using meaningful identifiers instead of their position in the signing order. Set the `signerTag` property for a signer when you call `POST /packages/add`, then use the same identifier in the document's template tags.
For example, a signer with a `signerTag` value of `buyer` is associated with these template tags:
```handlebars long theme={null}
{{signer_buyer:signature_1}}
```
```handlebars short theme={null}
{{s_buyer:sig_1}}
```
The user-defined identifier replaces the signer's generated numeric or host identifier. For example, use `signer_buyer` rather than `signer_1` for a signer whose `signerTag` is `buyer`.
If you omit `signerTag`, iinked Sign generates the signer identifier based on the package type and signing order. Generated identifiers include `signer_1` and `signer_host`.
## Choose signer tag values
Use a unique, lowercase value without underscores for each signer. Template tag identifiers are read as lowercase, and underscores separate parts of the template tag syntax.
For example, use `buyer` and `seller` as the `signerTag` values, then add `signer_buyer` and `signer_seller` template tags to the document.
## Add a package with signer tags
Before adding the package, insert template tags that use the user-defined signer identifiers into the document. For example:
```handlebars theme={null}
Buyer signature: {{signer_buyer:signature_1}}
Seller signature: {{signer_seller:signature_1}}
```
Upload the document, then call `POST /packages/add`. Set each signer's `signerTag` to the identifier used in the document:
```http Request theme={null}
POST /packages/add
{
"name": "Purchase Agreement",
"type": "sequential",
"signers": [
{
"signerTag": "buyer",
"firstName": "Jamie",
"lastName": "Buyer",
"email": "jamie.buyer@example.com"
},
{
"signerTag": "seller",
"firstName": "Alex",
"lastName": "Seller",
"email": "alex.seller@example.com"
}
],
"documents": [
{
"fileName": "purchase-agreement.pdf",
"fileId": "d29e25e0-624b-4adb-b118-19c4d0125e5e"
}
]
}
```
When iinked Sign processes the document, fields using `signer_buyer` are assigned to Jamie Buyer and fields using `signer_seller` are assigned to Alex Seller.
# Tag options
Source: https://docs.iinkedsign.com/v4/guides/template-tagging/tag-options
Learn about the various options available for template tags.
## Overview
Template tags can be customized using various options to control their behavior and appearance.
These options are specified within the tag syntax and can include properties such as size, alignment, position, validation, default values, and more.
## Options syntax
Options are specified within the template tag using key-value pairs separated by underscores.
There are two syntaxes for specifying options, some options use the `option__` syntax, while others use the `_` syntax.
### `option__`
```handlebars long theme={null}
{{signer_:_:option__}}
```
### `_`
```handlebars long theme={null}
{{s_:_:_}}
```
## PDF units
Many tag options use PDF units for measurements. In PDF units, 1 inch is equal to 72 units.
A standard letter-size document (8.5 x 11 inches) is therefore 612 x 792 PDF units.
## Options
### Optional
The `optional` option allows you to specify whether a tag field is optional or required.
```handlebars long theme={null}
{{signer_1:text_1:option_optional}}
```
```handlebars short theme={null}
{{s_1:text_1:o_opt}}
```
### Width
The `width` option allows you to set the width of the tag field in PDF units.
```handlebars long theme={null}
{{signer_1:text_1:option_width_200}}
```
```handlebars short theme={null}
{{s_1:text_1:o_w_200}}
```
### Height
The `height` option allows you to set the height of the tag field in PDF units.
```handlebars long theme={null}
{{signer_1:text_1:option_height_50}}
```
```handlebars short theme={null}
{{s_1:text_1:o_h_50}}
```
### Font size
The `font_size` option allows you to set the font size of the text within the tag field.
```handlebars long theme={null}
{{signer_1:text_1:option_fontsize_12}}
```
```handlebars short theme={null}
{{s_1:text_1:o_fs_12}}
```
### Align
The `align` option allows you to align the tag field to the left , center, or right within its designated area.
```handlebars long theme={null}
{{signer_1:text_1:option_align_left}}
```
```handlebars short theme={null}
{{s_1:text_1:o_a_l}}
```
```handlebars long theme={null}
{{signer_1:text_1:option_align_center}}
```
```handlebars short theme={null}
{{s_1:text_1:o_a_c}}
```
```handlebars long theme={null}
{{signer_1:text_1:option_align_right}}
```
```handlebars short theme={null}
{{s_1:text_1:o_a_r}}
```
## Size
The `size` option allows you to set the size of the tag field (width and height) in PDF units
```handlebars long theme={null}
{{signer_1:text_1:size_(200,50)}}
```
```handlebars short theme={null}
{{s_1:text_1:sz_(200,50)}}
```
## Offset
The `offset` option allows you to set the position offset of the tag field in PDF units.
Useful for fine-tuning the placement of the tag field, such as `radio` or `checkbox`, within the document.
Positive values move the field right and down, while negative values move it left and up.
```handlebars long theme={null}
{{signer_1:text_1:offset_10x-40)}}
```
```handlebars short theme={null}
{{s_1:text_1:f_10x-40)}}
```
## Value
The `value` option allows you to set a default value for the tag field.
When using default values that contain spaces or special characters, ensure to properly encode them using an URL encoder to avoid parsing issues.
Default `value` can currently be set for `text`, `multiline`, `radio`, and `checkbox` tags.
```handlebars long theme={null}
{{signer_1:text_1:value_DefaultText}}
```
```handlebars short theme={null}
{{s_1:text_1:v_DefaultText}}
```
```handlebars long theme={null}
{{signer_1:multiline_1:value_Default%20multiline%20text.}}
```
```handlebars short theme={null}
{{s_1:multi_1:v_Default%20multiline%20text.}}
```
Set a default value of radio `1.1` to `true` (selected).
```handlebars long theme={null}
{{signer_1:radio_1}}
{{radio_1.1:value_true}}
{{radio_1.2}}
{{radio_1.3}}
```
```handlebars short theme={null}
{{s_1:r_1}}
{{r_1.1:v_true}}
{{r_1.2}}
{{r_1.3}}
```
Set a default value of checkbox `1.1` to `true` (checked).
```handlebars long theme={null}
{{signer_1:checkbox_1.1:value_true}}
```
```handlebars short theme={null}
{{s_1:c_1.1:v_true}}
```
## Data ID
The `dataid` option allows you to assign a custom data identifier to the tag field for easier reference.
```handlebars long theme={null}
{{signer_1:text_1:dataid_customID123}}
```
```handlebars short theme={null}
{{s_1:text_1:id_customID123}}
```
See the [Templating data guide](/v4/guides/template-data) for more information.
# Tags
Source: https://docs.iinkedsign.com/v4/guides/template-tagging/tags
Learn about the various template tags available for document templating.
## Signature
Signature tags are used to indicate where a signer should place their signature within the document.
```handlebars long theme={null}
{{signer_1:signature_1}}
```
```handlebars short theme={null}
{{s_1:sig_1}}
```
```handlebars long theme={null}
{{signer_1:signature_1_name}}
```
```handlebars short theme={null}
{{s_1:sig_1_name}}
```
```handlebars long theme={null}
{{signer_1:signature_1_email}}
```
```handlebars short theme={null}
{{s_1:sig_1_email}}
```
```handlebars long theme={null}
{{signer_1:signature_1_date}}
```
```handlebars short theme={null}
{{s_1:sig_1_date}}
```
## Initials
Initials tags are used to indicate where a signer should place their initials within the document.
```handlebars long theme={null}
{{signer_1:initials_1}}
```
```handlebars short theme={null}
{{s_1:init_1}}
```
```handlebars long theme={null}
{{signer_1:initials_1_name}}
```
```handlebars short theme={null}
{{s_1:init_1_name}}
```
```handlebars long theme={null}
{{signer_1:initials_1_email}}
```
```handlebars short theme={null}
{{s_1:init_1_email}}
```
```handlebars long theme={null}
{{signer_1:initials_1_date}}
```
```handlebars short theme={null}
{{s_1:init_1_date}}
```
## Text
Text tags are used to indicate where a signer should enter text within the document.
```handlebars long theme={null}
{{signer_1:text_1}}
```
```handlebars short theme={null}
{{s_1:text_1}}
```
## Multiline
Multiline tags are used to indicate where a signer should enter multiple lines of text within the document.
```handlebars long theme={null}
{{signer_1:multiline_1}}
```
```handlebars short theme={null}
{{s_1:multi_1}}
```
## Date picker
Date picker tags are used to indicate where a signer should enter a date within the document.
```handlebars long theme={null}
{{signer_1:datepicker_1}}
```
```handlebars short theme={null}
{{s_1:dp_1}}
```
## Radio
Radio tags are used to indicate where a signer should select an option from a set of radio buttons within the document.
Radio groups must have unique tag IDs (across all signers) within the document to function correctly.
The radio group tag is optional. If not specified, the radio buttons will function as a group by default based on their tag IDs.
A signer must select one of the radio buttons in the group unless the radio button group is marked as optional.
The radio group tag does not render a visible field in the document. It is only used to define the grouping behavior of the associated radio buttons.
### Radio group (optional)
Radio group tags are used to customize the behavior of a set of radio buttons within the document.
```handlebars long theme={null}
{{signer_1:radio_1}}
```
```handlebars short theme={null}
{{s_1:r_1}}
```
```handlebars long theme={null}
{{signer_1:radio_1:option_optional}}
```
```handlebars short theme={null}
{{s_1:r_1:o_opt}}
```
### Radio button
```handlebars long theme={null}
{{signer_1:radio_1.1}}
```
```handlebars short theme={null}
{{s_1:r_1.1}}
```
### Examples
When combining the radio group tag with a radio button tag, the syntax looks like this:
```handlebars long theme={null}
{{signer_1:radio_1:option_optional}}
{{radio_1.1}}
{{radio_1.2}}
{{radio_1.3}}
```
```handlebars short theme={null}
{{s_1:r_1:o_opt}}
{{r_1.1}}
{{r_1.2}}
{{r_1.3}}
```
```handlebars long theme={null}
{{signer_2:radio_2}}
{{radio_2.1}}
{{radio_2.2}}
{{radio_2.3}}
```
```handlebars short theme={null}
{{s_2:r_2}}
{{r_2.1}}
{{r_2.2}}
{{r_2.3}}
```
The radio button tags will inherit the signer from the radio group tag and do not need to specify the signer again.
## Checkbox
Checkbox tags are used to indicate where a signer should select a checkbox within the document.
Checkbox groups must have unique tag IDs (across all signers) within the document to function correctly.
The checkbox group tag is optional. If not specified, the checkboxes will function as a group by default based on their tag IDs.
The checkbox group tag does not render a visible field in the document. It is only used to define the grouping behavior of the associated checkboxes.
### Checkbox group (optional)
Checkbox group tags are used to customize the behavior of a set of checkboxes within the document.
```handlebars long theme={null}
{{signer_1:checkbox_1}}
```
```handlebars short theme={null}
{{s_1:c_1}}
```
You can use the `validate_required` property to make at least two checkboxes in the group required.
```handlebars long theme={null}
{{signer_1:checkbox_1:validate_required_2}}
```
```handlebars short theme={null}
{{s_1:c_1:vd_req_2}}
```
### Checkbox
```handlebars long theme={null}
{{signer_1:checkbox_1.1}}
```
```handlebars short theme={null}
{{s_1:c_1.1}}
```
### Examples
When combining the checkbox group tag with a checkbox tag, the syntax looks like this:
```handlebars long theme={null}
{{signer_1:checkbox_1:validate_required_2}}
{{checkbox_1.1}}
{{checkbox_1.2}}
{{checkbox_1.3}}
```
```handlebars short theme={null}
{{s_1:c_1:vd_req_2}}
{{c_1.1}}
{{c_1.2}}
{{c_1.3}}
```
```handlebars long theme={null}
{{signer_2:checkbox_2}}
{{checkbox_2.1}}
{{checkbox_2.2}}
{{checkbox_2.3}}
```
```handlebars short theme={null}
{{s_2:c_2}}
{{c_2.1}}
{{c_2.2}}
{{c_2.3}}
```
## Image
Image tags are used to indicate where a signer should upload an image within the document.
```handlebars long theme={null}
{{signer_1:image_1}}
```
```handlebars short theme={null}
{{s_1:img_1}}
```
## Document properties
You can use template tags to insert document properties such as the package or document name.
```handlebars long theme={null}
{{document:packageName}}
```
```handlebars short theme={null}
{{doc:packageName}}
```
```handlebars long theme={null}
{{document:name}}
```
```handlebars short theme={null}
{{doc:name}}
```
```handlebars long theme={null}
{{document:date}}
```
```handlebars short theme={null}
{{doc:d}}
```
## Signer properties
You can also use template tags to insert signer properties such as name and email.
```handlebars long theme={null}
{{signer_1:name}}
```
```handlebars short theme={null}
{{s_1:name}}
```
```handlebars long theme={null}
{{signer_1:email}}
```
```handlebars short theme={null}
{{s_1:email}}
```
```handlebars long theme={null}
{{signer_1:date}}
```
```handlebars short theme={null}
{{s_1:d}}
```
# Templates
Source: https://docs.iinkedsign.com/v4/guides/templates
Learn how to use templates when creating packages.
## Overview
Users in iinked Sign can create reusable templates in the UI to quickly generate new signing packages for frequently used workflows.
You can retrieve a list of available templates and apply a template when creating a package.
## Steps
You can retrieve a list of an organization members current templates by calling `templates/list` endpoint.
```http Request theme={null}
GET /templates/list
{
"memberId": "e4f0bce5-30fc-43c4-b9ee-364ff5b04dea",
"sortBy": "last_used",
"take": 100,
"skip": 0
}
```
See the [Templates list API](/v4/api/templates/list) for more information.
### Manually getting template details
If you know the template you want to use, you can manually copy the `template ID` and `signer roles` from iinked Sign by navigating to the Templates section, selecting a template, and copying the ID from the URL and the roles from the editor.
Once you have the template ID and signer roles, you can create a new package by calling the `packages/add` endpoint and setting the `templateId`.
### Documents
All documents associated with the template will be included in the package. You can add additional documents by including them in the `documents` array.
#### Replacing documents
If you want to replace a document with a different file (e.g., a new version), upload the new file and add it to the `documents` array,
setting either `templateDocumentId` or `name` to that of the template document you want to replace.
This will swap out the document in the package while retaining all templated fields.
### Signers
Associate template signers by setting the `templateSignerId` or `templateRole` for each signer in the `signers` array.
### Recipients
Associate template recipients by setting the `templateRecipientId` or `templateRole` for each recipient in the `recipients` array.
```http Request highlight={5,9,18} theme={null}
POST /packages/add
{
"name": "From Template",
"type": "concurrent",
"templateId": "{{template_id}}",
"state": "open",
"signers": [
{
"templateRole": "Signer 1",
"firstName": "Signer",
"lastName": "One",
"email": "{{signer_1_email}}",
"mobileNumber": null
}
],
"recipients": [
{
"templateRole": "Recipient 1",
"firstName": "Recipient",
"lastName": "One",
"email": "{{recipient_1_email}}",
"mobileNumber": null
}
],
"documents": []
}
```
```http Request highlight={5,9,18} theme={null}
POST /packages/add
{
"name": "From Template",
"type": "concurrent",
"templateId": "{{template_id}}",
"state": "open",
"signers": [
{
"templateSignerId": "{{template_signer_1_id}}",
"firstName": "Signer",
"lastName": "One",
"email": "{{signer_1_email}}",
"mobileNumber": null
}
],
"recipients": [
{
"templateRecipientId": "{{template_recipient_1_id}}",
"firstName": "Recipient",
"lastName": "One",
"email": "{{recipient_1_email}}",
"mobileNumber": null
}
],
"documents": []
}
```
```http Request highlight={5,9,18,27} theme={null}
POST /packages/add
{
"name": "From Template",
"type": "concurrent",
"templateId": "{{template_id}}",
"state": "open",
"signers": [
{
"templateSignerId": "{{template_signer_1_id}}",
"firstName": "Signer",
"lastName": "One",
"email": "{{signer_1_email}}",
"mobileNumber": null
}
],
"recipients": [
{
"templateRecipientId": "{{template_recipient_1_id}}",
"firstName": "Recipient",
"lastName": "One",
"email": "{{recipient_1_email}}",
"mobileNumber": null
}
],
"documents": [
{
"templateDocumentId": "{{template_document_1_id}}",
"fileName": "agreement-2.pdf",
"fileId": "{{file_id}}"
}
]
}
```
```http Request highlight={5,9,18,27} theme={null}
POST /packages/add
{
"name": "From Template",
"type": "concurrent",
"templateId": "{{template_id}}",
"state": "open",
"signers": [
{
"templateRole": "Signer 1",
"firstName": "Signer",
"lastName": "One",
"email": "{{signer_1_email}}",
"mobileNumber": null
}
],
"recipients": [
{
"templateRole": "Recipient 1",
"firstName": "Recipient",
"lastName": "One",
"email": "{{recipient_1_email}}",
"mobileNumber": null
}
],
"documents": [
{
"name": "Agreement",
"fileName": "agreement-2.pdf",
"fileId": "{{file_id}}"
}
]
}
```
# Webhooks guide
Source: https://docs.iinkedsign.com/v4/guides/webhooks
Learn how to set up and use webhooks to automatically download executed documents.
## Overview
Webhooks allow your application to receive real-time notifications about events that occur within our system, such as when a document is signed or a package is fully executed.
This guide will walk you through the process of subscribing to webhooks to automatically download signed documents.
## Steps
Follow the [Webhooks setup guide](/v4/webhooks/setup).
When a webhook event occurs, our system will send a POST request to your specified endpoint with details about the event.
When a package is fully executed, all documents signed by all signers, you will receive a webhook event with the following payload:
```json Payload highlight={2,3} theme={null}
{
"action": "package_executed",
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"externalData": null,
"eventId": "0ea12600-85bc-46dd-af85-f82f621c1abc",
"eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
"eventTime": "2022-02-23T20:20:15.9714327Z"
}
```
When a document is fully executed, signed by all signers, you will receive a webhook event with the following payload:
```json Payload highlight={2,3} theme={null}
{
"action": "document_executed",
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"documentId": "73f34799-c3a2-49e3-aa5f-33b0c2c1f111",
"externalId": null,
"eventId": "8977f701-480a-4a5d-9bad-87d87fe38447",
"eventTime": "2022-02-23T20:20:15.9021584Z"
}
```
When a document is signed by a signer, you will receive a webhook event with the following payload:
```json Payload highlight={2,3} theme={null}
{
"action": "document_signed",
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"documentId": "73f34799-c3a2-49e3-aa5f-33b0c2c1f111",
"revisionId": "ecaac2dc-8fe2-48fd-b3d5-74646435b1d2",
"signerId": "d5397c13-5dcf-4574-b94b-5addf95c91df",
"nextSignerId": "f700fdfa-b493-467e-b30d-7eb17e2bb769",
"externalId": null,
"eventId": "f3a27f18-b892-4c4d-8ffa-81f2f459017f",
"eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
"eventTime": "2022-02-23T20:19:56.8208742Z"
}
```
Depending on your application's needs, you can handle these events accordingly. For example, when you receive a `package_executed` event,
you can trigger the download of all executed documents in that package.
You can set `externalData` at the package level when creating a package to help correlate webhook events with your internal records.
You can also set an `externalId` at the document level when uploading files to add to a package.
See the [External data guide](/v4/guides/external-data) for more information.
To ensure that incoming webhook requests are legitimate, you should verify the signature included in the `X-Syngrafii-Signature` header of each request.
View the [Webhooks verification guide](/v4/webhooks/setup#verify-webhooks) for detailed instructions on how to verify webhook signatures.
Once you receive a webhook event you want to act on, such as the `package_executed` webhook event,
call the [Packages status API](/v4/api/packages/status) endpoint to get the list of documents in the package.
```http Request theme={null}
GET /packages/{packageId}/status
```
```json Response highlight={7} theme={null}
{
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
...
"state": "executed",
"documents": [
{
"documentId": "73f34799-c3a2-49e3-aa5f-33b0c2c1f111",
...
}
],
...
}
```
After confirming that the package is fully executed, you can use the [Packages download API](/v4/api/packages/download) endpoint to download all executed documents in the package.
Use the package status response to determine all the document IDs to download.
#### Download PDFs
```http Request theme={null}
GET /packages/{packageId}/documents/{documentId}/pdf/executed/download
```
```http Request theme={null}
GET /packages/{packageId}/documents/{documentId}/pdf/cac/download
```
```http Request theme={null}
GET /masterfiles/{packageId}/pdf/download
```
See the [MasterFile download API](/v4/api/masterfile/download) for more information on downloading MasterFiles.
# Workflows
Source: https://docs.iinkedsign.com/v4/guides/workflows
Learn about the different signing workflows supported by the iinked Sign platform.
## Overview
The iinked Sign platform supports multiple signing workflows to accommodate various business needs. Each workflow is designed to optimize the signing process for different scenarios, ensuring a seamless experience for both senders and signers.
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
### Concurrent
Send the documents to recipients for signing in any order. Each recipient will sign the same copy of the document.
constant: `concurrent`
### Sequential
Send the documents to recipients following a defined order of signing. Each recipient will sign the same copy of the document and will be notified when it is their turn.
constant: `Sequential`
### Group Send
Send a copy of each document to a group of recipients at once. Each signer gets their own version of the document to sign.
constant: `Counterpart`
### Video Signing Room (VSR)
Schedule an online meeting with one or more signers where you can share and record the signing session via video conferencing.
constant: `video_closing_room`
### In Person
Maintain ownership of the documents while securing single use signatures from signers in a shared screen session. Signers will not receive a link to the document but will instead be sent a link to a signature pad during the screen share session.
constant: `Live Session`
# Introduction
Source: https://docs.iinkedsign.com/v4/introduction
## Overview
**iinked Sign by Syngrafii** is a secure, flexible, and scalable electronic signature platform designed to streamline document workflows for businesses of all sizes. With robust API capabilities, iinked Sign enables seamless integration into your applications, allowing you to automate signature requests, manage documents, and track signing status with ease.
## Key features
* Easy integration via RESTful API
* Secure document storage and management
* Comprehensive audit trails
* Multiple signing workflows
* Sequential
* Concurrent
* Group
* In Person
* Video Signing Room (VSR)
* Identity Verification (IDV)
# OAuth 2.0
Source: https://docs.iinkedsign.com/v4/oauth
Get started integrating your OAuth App with iinked Sign via our OAuth 2.0 authorization code flow.
## Requesting your client ID and secret
The first step is to request a client id and secret for one of our sandbox instances so that you can get started. We require that you provide one or more redirect URL(s) for the authorization redirect callback to your application.
[**Complete Request Form (iinked Sign)**](https://sign.syngrafii.com/form/D-qcgcvtTEqAJhJm9w47jQ)
You can request multiple redirect URLs to be whitelisted. HTTPS is required.
**Redirect URL Examples**
If you would like to use Postman's built in OAuth 2.0 authorization during development:
[https://oauth.pstmn.io/v1/callback](https://oauth.pstmn.io/v1/callback) (default)
It is also common to include localhost during development:
[https://localhost/auth/syngrafii](https://localhost/auth/syngrafii) (example)
Once you have your client id and secret, you can contact [support@syngrafi.com](mailto:support@syngrafi.com) directly to open a ticket and request any additional changes.
## Authorization code flow
iinked Sign provides an OAuth 2.0 authorization code flow [**(RFC 6749, Section 4.1)**](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1) with optional PKCE support.
### Authorizing your application
Direct your user to the `connect/authorize` URL with the following query parameters:
```http Authorize URL theme={null}
https://sandbox.syngrafii.com/connect/authorize
```
Use `code` as a response type.
Your OAuth App client id.
One of the redirect URLs you provided when requesting your OAuth App client id and secret. Contact [support@syngrafii.com](mailto:support@syngrafii.com) if you need to modify your redirect URL(s).
For most integrations request `profile offline_access organization`. If you support OpenID Connect include `openid` to also receive an `id_token` (for example: `profile openid offline_access organization`).
A value returned with the callback to help maintain state between the request and callback and to help prevent CSRF attacks. (optional)
When using OpenID Connect, provide a nonce to help prevent replay attacks. (optional)
Prompt options to influence the authorization user experience. See values below.
| Value | Description |
| ------- | ------------------------------------------------------------------------------------------- |
| consent | Require the user to consent to the requested scopes even if they have previously consented. |
| login | Require the user to login again even if they are already authenticated. |
(Required when using PKCE) Code challenge value.
(Required when using PKCE) Code challenge method (for example: `S256`).
```http Authorize URL Example theme={null}
https://sandbox.syngrafii.com/connect/authorize?client_id=my-client-id&redirect_uri=https%3A%2F%2Flocalhost%3A44319%2Fauth%2Fsyngrafii&response_type=code&scope=profile%20openid%20offline_access%20organization
```
The user will then be prompted to authorize access for your application, once they have authorized the access, they will be redirected back to your application using the provided redirect\_uri query parameter.
If the user had previously authorized your application, they will automatically be redirected back to your application.
### Retrieving tokens
The callback to your application will contain a code query parameter and state query parameter if one was provided with the original request. You must use this code to retrieve your tokens by making a POST request to the connect/token endpoint.
```http POST theme={null}
Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded
https://sandbox.syngrafii.com/connect/token
```
client\_id:client\_secret must be Base64 Encoded
Use `authorization_code` as the grant type.
The authorization `code` returned to your callback. Use this to exchange for tokens.
(Only required if the Authorization header is not provided) Your client\_id.
(Only required if the Authorization header is not provided) Your client\_secret.
```json Response theme={null}
{
"access_token": "XXXX…",
"refresh_token": "YYYY…",
"id_token": "ZZZZ…",
"token_type": "Bearer",
"expires_in": 1800,
"scope": "profile openid offline_access organization"
}
```
Can be used to call the iinked Sign API as the user. This token has a short lifetime (see `expires_in`).
Can be used to request a new `access_token`. The refresh token has a long lifetime and will be renewed with each request. Requires the `offline_access` scope.
A JWT that contains the user's profile claims. Returned when `openid` scope is requested.
### Using an access token
You can now make requests to the iinked Sign API by adding the access token to Authorization header as a Bearer token.
iinked Sign access tokens are obtained through the OAuth 2.0 authorization process.
**Request Header**
```http theme={null}
Authorization: Bearer
```
### Refreshing an access token
The access token has a short lifetime and must be refreshed by making another POST request to the connect/token endpoint and passing the refresh token.
```http POST theme={null}
Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/x-www-form-urlencoded
https://sandbox.syngrafii.com/connect/token
```
client\_id:client\_secret must be Base64 Encoded
| Request Parameter | Description |
| ----------------- | ------------------------------------------------------------------------------- |
| grant\_type | Use **refresh\_token** as grant type. |
| refresh\_token | Use the **refresh\_token** returned from the last call. |
| client\_id | (Only if **Authorization** header is **not** provided) Your **client\_id.** |
| client\_secret | (Only if **Authorization** header is **not** provided) Your **client\_secret.** |
**Single Use Refresh Tokens**
iinked Sign has implemented single use Refresh Tokens. When refreshing the access token, a new refresh token will be returned along with the access token. It is important to replace the previous refresh token with the new one as they will expire 60 seconds after they have been redeemed. This 60 second leeway helps reduce any concurrency issues within your application that may result in using the current refresh token at the same time.
**Rolling Refresh Tokens**
When a new refresh token is returned, its lifetime will be also be renewed. Therefore, reauthorization will only be required when applications have not been used for several months.
## Implementation
### Common workflow
- Store refresh token
- Cache access token
- Set event notification callback
api/v1/events/endpoints/set (if required)
- Sync organization and members
api/v1/organizations/info (if required)
- Get from cache
-
If expired / not cached
- Get new tokens using refresh token
- Store new refresh token
- Cache new access token
Call api/v1/packages/add to add a package.
See the [Packages add API](/v4/api/packages/add) for more information.
### Mapping event notifications
If you set an event notification callback endpoint for the organization, you will be notified as packages progress through their signing workflows. To map those events to a specific package you will need to store the organizationId, memberId, and packageId returned from the **api/v1/packages/add** API call.
See the [Webhooks setup guide](/v4/webhooks/setup) for more information.
## OAuth configuration
| OAuth Endpoints | sandbox.syngrafii.com used for examples |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authority (OpenID) | `https://sandbox.syngrafii.com`
`https://sandbox.syngrafii.com/.well-known/openid-configuration`
`https://sandbox.syngrafii.com/.well-known/jwks` |
| Authorize | `https://sandbox.syngrafii.com/connect/authorize` |
| Token | `https://sandbox.syngrafii.com/connect/token` |
| Revoke | `https://sandbox.syngrafii.com/connect/revoke` |
| User Info | `https://sandbox.syngrafii.com/connect/userinfo` |
#### Response types
| Response Type | Description |
| ------------- | ----------------------- |
| code | Authorization Code Flow |
#### Scopes
| Scope | Description |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| profile | Request access to user's profile. |
| openid | Request that an id\_token is returned containing the user's profile. |
| offline\_access | Request that a refresh\_token is returned that can be stored and used to request new access tokens. |
| organization | Request access to the organization. Can access profiles and add packages for all organization members. Can also set a callback URL to receive event notifications from the organization. User must be an Organization Administrator to authorize this request. |
| member | Request access to the organization member. Can only add packages for this member. |
#### Claims
| Claim | Source / Description |
| -------------------------------------- | ---------------------------------------------------- |
| id\_token or connect/userinfo endpoint | Returned from id\_token or connect/userinfo endpoint |
| sub | Subject |
| email | Email address |
| given\_name | Given name |
| family\_name | Family name |
| s:organization | Organization ID |
| s:member | Member ID |
# Quickstart
Source: https://docs.iinkedsign.com/v4/quickstart
## Overview
Welcome to the Syngrafii iinked Sign API Quickstart guide! This guide will help you get started with sending a package for signing using the iinked Sign API in just a few simple steps.
## Prerequisites
* [Sandbox](/v4/sandbox) account with an active subscription
## Steps
* **Log in** to your account.
* Navigate to `Settings` > `Integration` > `API Keys`.
* Provide a name, click `Add`, and save your API key securely.
You require an active subscription to create API keys.
* Open Postman and create a new request.
* Set the request type to `POST`.
* Enter the request URL: `https://sandbox.syngrafii.com/api/v1/packages/add`.
* In the `Authorization` tab, select `API Key`:
* Key: `api_key`
* Value: `{{api_key}}`
* Add to: `Header`
* In the `Body` tab, select `raw` and choose `JSON` from the dropdown.
```http Request theme={null}
POST /packages/add
{
"name": "My First Package",
"signers": [
{
"firstName": "{{first_name}}",
"lastName": "{{last_name}}",
"email": "{{email}}"
}
],
"documents": [
{
"fileName": "agreement.pdf",
"fileUrl": "{{file_url}}"
}
]
}
```
In production it is recommended to upload files using the [Files upload API](/v4/api/files/upload) and reference them by `fileId` instead of `fileUrl`.
* Open email and click on the `Sign` link.
## Postman collection
Explore our Postman collection for additional examples to help you get started.
[![Run In Postman]()
](https://app.getpostman.com/run-collection/9887219-755c9366-b66d-4472-b184-6aed858e00d1?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D9887219-755c9366-b66d-4472-b184-6aed858e00d1%26entityType%3Dcollection%26workspaceId%3D1c60312b-f96b-4117-ad4f-c5a5ff2c9017)
# Document
Source: https://docs.iinkedsign.com/v4/reference/documents/document
Unique identifier for the document.
Identifier of the package this document belongs to.
Unique identifier for the file associated with the document.
Auto-template identifier (if created from an auto-template).
Auto-template document identifier (if applicable).
External identifier for the document. (optional)
Order/index of the document within the package.
Document display name.
Original filename uploaded.
File extension or type identifier.
Size of the file in bytes.
Number of pages in the document.
Upload time (ISO 8601 date-time).
Last modified time (ISO 8601 date-time).
Number of signed revisions for this document.
Total number of revisions for this document.
Description of the document. (optional)
Set to `true` if a CAC (Compliance Audit Certificate) has been appended to the document.
Number of CAC pages if `cac` is `true`.
Current state of the document.
Most document states are used internally. All documents included in a returned package will always be in the open state.
| Values | Description |
| :----- | :--------------------------------------------------- |
| open | The document is open and can be interacted with. |
| failed | The document failed to process and cannot be signed. |
Revision history for the document. Typically includes one revision per signer.
ID of the document this revision belongs to.
Unique identifier for the revision.
Revision number (incrementing integer).
Identifier of the previous revision this revision replaced. (optional)
Last opened time for the revision (ISO 8601).
Signer who is associated with this revision.
Set to `true` if this revision has been signed.
Time the revision was signed (ISO 8601).
Address metadata captured on sign. (optional)
Latitude coordinate captured on sign. (optional)
Longitude coordinate captured on sign. (optional)
State of the revision (for example: signed, pending).
Signers associated with this document.
Identifier for the signer associated with the document.
Internal signer key used to map fields/tags.
Full name for the signer on this document.
Signer initials.
Email for the signer on this document.
Mobile number for the signer on this document. (optional)
Set to `true` if the signer has signed this document.
Set to `true` if this signer is next in the signing order for this document.
Template role name if the signer was created from a template role. (optional)
# Document revision
Source: https://docs.iinkedsign.com/v4/reference/documents/document-revision
ID of the document this revision belongs to.
Unique identifier for the revision.
Revision number (incrementing integer).
Identifier of the previous revision this revision replaced. (optional)
Last opened time for the revision (ISO 8601).
Signer who is associated with this revision.
Set to `true` if this revision has been signed.
Time the revision was signed (ISO 8601).
Address metadata captured on sign. (optional)
Latitude coordinate captured on sign. (optional)
Longitude coordinate captured on sign. (optional)
State of the revision (for example: signed, pending).
# Document signer
Source: https://docs.iinkedsign.com/v4/reference/documents/document-signer
Identifier for the signer associated with the document.
Internal signer key used to map fields/tags.
Full name for the signer on this document.
Signer initials.
Email for the signer on this document.
Mobile number for the signer on this document. (optional)
Set to `true` if the signer has signed this document.
Set to `true` if this signer is next in the signing order for this document.
Template role name if the signer was created from a template role. (optional)
# Document states
Source: https://docs.iinkedsign.com/v4/reference/documents/document-states
Most document states are used internally. All documents included in a returned package will always be in the open state.
| Values | Description |
| :----- | :--------------------------------------------------- |
| open | The document is open and can be interacted with. |
| failed | The document failed to process and cannot be signed. |
# Document status
Source: https://docs.iinkedsign.com/v4/reference/documents/document-status
Unique identifier for the package.
Unique identifier for the document.
Unique identifier for the file associated with the document.
External system identifier for the document, if available.
Name of the document.
File name of the document.
Order of the document in the package.
Set to `true` if document has been signed by all signers.
List of revisions for the document.
Unique identifier for the package.
Unique identifier for the document.
Unique identifier for the revision.
Unique identifier for the signer.
Link for signer to sign their revision of document.
Set to `true` if signer is next signer in sequential signing.
Set to `true` if signer has signed their revision of document.
# Revision status
Source: https://docs.iinkedsign.com/v4/reference/documents/revision-status
Unique identifier for the package.
Unique identifier for the document.
Unique identifier for the revision.
Unique identifier for the signer.
Link for signer to sign their revision of document.
Set to `true` if signer is next signer in sequential signing.
Set to `true` if signer has signed their revision of document.
# Embed actions
Source: https://docs.iinkedsign.com/v4/reference/embed/embed-actions
| Action | Description |
| :------------------- | :--------------------------------------------------------------------------------------------------------------- |
| package\_add | User has added a new package. |
| package\_cancel | User has cancelled any changes to the package. They are still in the package editor. |
| package\_close | User has closed the package editor. You should continue with your workflow. |
| package\_open | The package has been opened by the package editor. |
| package\_save | User has saved any changes to the package. They are still in the package editor. |
| package\_send | User has sent the package and closed the package editor. You should continue with your workflow. |
| meeting\_end | Host has ended VSR meeting session. |
| meeting\_joining | User is joining VSR meeting session. |
| meeting\_join | User has joined VSR meeting session. |
| meeting\_start | Host has started VSR meeting session. |
| signing\_changed | User has modified signing; you can use this to track dirty state of signing and prevent navigation. |
| signing\_close | User has closed signing and was redirected to /notsent page. |
| signing\_finalize | User has finalized current document. |
| signing\_ignore | User has ignored save changes warning dialog. |
| signing\_next | User has opened next document for signing. |
| signing\_open | User has opened document for signing. |
| signing\_return | User has completed or closed signing and was redirected back to packages list. |
| signing\_return\_url | User has completed or closed signing and was redirected back to returnUrl. |
| signing\_save | User has saved signing progress; you can use this to track dirty state of signing and allow navigation. |
| signing\_sent | User has completed signing all documents and was redirected to /sent page. |
| session\_expired | User session has expired. The package editor will show an Expired Session message. |
| session\_expiring | User session is about to expire due to inactivity. They will be presented with a dialog to extend their session. |
| session\_extended | User session was extended by user. |
# Embed sources
Source: https://docs.iinkedsign.com/v4/reference/embed/embed-source
| Source | Description |
| :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| syngrafii-app | Message was sent from the `Package Editor` or `Video Signing Room` app. |
| syngrafii-sign-app | Message was sent from the `Sign` app. The `Sign` app is also embedded in the `Video Signing Room` app, so you can receive messages from both sources. |
| syngrafii-embed | This source is used to **send** `embed_position` messages to `Video Signing Room` embedded signings. |
# File types
Source: https://docs.iinkedsign.com/v4/reference/files/file-types
| Value | Description |
| :-------- | :----------------------------------------------------------------------------------------- |
| temporary | The file will be stored temporarily and deleted if not added to a package within 24 hours. |
# Locales
Source: https://docs.iinkedsign.com/v4/reference/locales
| Value | Description |
| :---- | :---------- |
| en | English |
| fr | français |
| de | Deutsch |
| es | Español |
# Access history actions
Source: https://docs.iinkedsign.com/v4/reference/masterfiles/masterfile-access-history-actions
| Value | Description |
| :-------------------- | :------------------------------------------------------------------------------- |
| access\_challenged | Signer was issued MFA challenge |
| access\_failed | Signer failed MFA attempt |
| access\_lockout | Signer failed MFA attempt multiple times in a row and was temporarily locked out |
| document\_opened | Signer opened document |
| meeting\_joined | Signer joined VSR meeting |
| mobile\_started | Signer started mobile signature pad session |
| session\_started | Signer started signing session |
| verification\_started | Signer started verification session |
# Access history types
Source: https://docs.iinkedsign.com/v4/reference/masterfiles/masterfile-access-history-types
| Value | Description |
| :----------- | :---------------------------------- |
| meeting | VSR meeting access history |
| mobile | Mobile signature pad access history |
| security | MFA access history |
| session | Signing session access history |
| verification | Verification session access history |
# Log types
Source: https://docs.iinkedsign.com/v4/reference/masterfiles/masterfile-log-types
| Value | Description |
| :------------------------------ | :------------------------------------------------- |
| document\_opened | Document opened |
| document\_saved | Document saved |
| document\_finalized | Document finalized |
| page\_enter | Page entered |
| page\_exit | Page exited |
| field\_annotation\_add | Annotation field added (free form ink annotations) |
| field\_checkbox\_check | Checkbox field checked |
| field\_checkbox\_uncheck | Checkbox field unchecked |
| field\_date\_add | Date field added |
| field\_date\_delete | Date field deleted |
| field\_digitalsignature\_add | Digital Signature field added |
| field\_digitalsignature\_delete | Digital Signature field deleted |
| field\_dropdown\_delete | Dropdown field deleted |
| field\_dropdown\_select | Dropdown field selected |
| field\_image\_add | Image field added |
| field\_image\_delete | Image field deleted |
| field\_initials\_add | Initials added |
| field\_initials\_delete | Initials deleted |
| field\_radio\_select | Radio field selected |
| field\_signature\_add | Signature field added |
| field\_signature\_delete | Signature field deleted |
| field\_stamp\_add | Stamp field added |
| field\_text\_add | Text field added |
| field\_text\_delete | Text field deleted |
# Notification templates
Source: https://docs.iinkedsign.com/v4/reference/masterfiles/masterfile-notification-templates
| Value | Description |
| :---------------------------- | :------------------------------------------------------------------- |
| document\_accessed | Document was opened by signer |
| document\_executed | Document was executed by all signers |
| document\_executed\_all | All documents were executed by all signers |
| document\_next | Next signer in a sequential signing |
| document\_reminder | Reminder to sign document(s) |
| document\_signed | Document signed by signer |
| mobile\_link | Link to open mobile signature pad |
| package\_cancelled | Signing package was cancelled |
| package\_executed | Signing package was executed by all signers |
| package\_masterfile\_link | MasterFile link was requested and sent to signer's email address |
| package\_meeting | VSR meeting was scheduled |
| package\_meeting\_cancelled | VSR meeting was cancelled |
| package\_notification | Custom signing package notification was sent to signer |
| package\_notification\_failed | Delivery failure notification sent to package owner |
| package\_review\_link | Package review link was requested and sent to signer's email address |
| package\_sign | Signing package sign document(s) request sent to signer |
| package\_updated | Signing package has been updated |
| security\_code | MFA security code has been sent to signer's mobile number |
| verification\_completed | Signer completed IDV |
| verification\_failed | Signer failed IDV |
| verification\_link | Link to open IDV |
# Notification types
Source: https://docs.iinkedsign.com/v4/reference/masterfiles/masterfile-notification-types
| Value | Description |
| :---- | :----------------- |
| email | Email notification |
| sms | SMS notification |
# History types
Source: https://docs.iinkedsign.com/v4/reference/masterfiles/masterfile-package-history-types
| Value | Description |
| :----------------------------------------------- | :------------------------------------------------------------------------------------------- |
| document\_added | Document was added |
| document\_deleted | Document was deleted |
| document\_regen | Document was regenerated after changes |
| document\_regen\_signed | Signed document was regenerated after changes requiring signer(s) to sign the document again |
| document\_updated | Document was modified |
| document\_updated\_template | Document template was updated |
| document\_updated\_template\_annotation\_added | Package owner added annotation to document |
| document\_updated\_template\_annotation\_deleted | Package owner deleted annotation from document |
| document\_updated\_template\_annotation\_updated | Package owner updated annotation in document |
| master\_file\_exported | MasterFile was exported by organization member |
| meeting\_added | VSR meeting was scheduled |
| meeting\_deleted | VSR meeting was cancelled |
| meeting\_updated | VSR meeting was updated |
| meeting\_video\_deleted | VSR video was deleted |
| package\_added | Package was added |
| package\_deleted | Package was deleted |
| package\_passphrase | MFA passphrase was added to package |
| package\_sent | Package was sent to signer |
| package\_updated | Package was updated |
| recipient\_added | Recipient was added |
| recipient\_deleted | Recipient was deleted |
| recipient\_updated | Recipient was updated |
| signer\_added | Signer was added |
| signer\_deleted | Signer was deleted |
| signer\_updated | Signer was updated |
| verification\_viewed | Verification was viewed by organization member |
# Consent options
Source: https://docs.iinkedsign.com/v4/reference/package-options/consent-options
Require the signer to provide consent before completing a configured consent
action. Defaults to `false`.
Require consent before signing. Defaults to `true`.
Require consent before video recording in a Video Signing Room package.
Defaults to `false`.
Reuse a member's previously accepted consent when the consent type and notice
version match and the acceptance occurred within this number of days. Defaults
to `90`. Set to `0` to disable automatic reuse.
# Digital signature options
Source: https://docs.iinkedsign.com/v4/reference/package-options/digital-signature-options
Map each enabled digital signature type to an ordered list of provider names.
| Signature type | Description |
| :------------- | :----------------------------- |
| `qes` | Qualified Electronic Signature |
| Value | Provider |
| :------------ | :---------- |
| `digidentity` | Digidentity |
Provider availability depends on your subscription and organization configuration.
# Geolocation options
Source: https://docs.iinkedsign.com/v4/reference/package-options/geo-location-options
Require geolocation to be shared before allowing the signer to continue.
Require geolocation to be shared before the signer can sign documents.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can use signature pad.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can join VSR meetings.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can verify their identity.
(`required` must also be set to `true`)
# Embed options
Source: https://docs.iinkedsign.com/v4/reference/package-options/package-embed-options
User can only save changes to draft packages; the user will not be able to send it.
User will not be allowed to modify package properties.
User will not be allowed to modify package verification properties.
User will not be allowed to modify package signers.
User will not be allowed to modify package documents.
User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.
The first document will be focused when the package editor is loaded instead of the package properties.
User will be redirected back to the returnUrl when they are done editing the package.
Will be included in a `state` query string parameter appended to the `returnUrl`.
# Package options
Source: https://docs.iinkedsign.com/v4/reference/package-options/package-options
Enable embedded signing mode.
Embed options used to customize the embedded package editor.
2.8
User can only save changes to draft packages; the user will not be able to send it.
User will not be allowed to modify package properties.
User will not be allowed to modify package verification properties.
User will not be allowed to modify package signers.
User will not be allowed to modify package documents.
User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.
The first document will be focused when the package editor is loaded instead of the package properties.
User will be redirected back to the returnUrl when they are done editing the package.
Will be included in a `state` query string parameter appended to the `returnUrl`.
Show custom brand when signing package.
1.10
Add document identifier to each page (QR code).
Allow VSR participants to review documents before a meeting via a Review Documents link added to email meeting invitation.
2.6
Allow signers to forward the signing to another email address.
4.0
Enabled to not share email addresses between signers.
2.11
Supported in the following package types:
* Concurrent (`concurrent`)
* Sequential (`Sequential`)
* Group Send (`Counterparts`)
Do not allow signers to fill AcroForm fields during signing.
3.3
Do not allow signers to modify AcroForm fields during signing.
3.6
Control how Acroform fields are flattened after signing a document.
2.6
| Value | Description |
| :----- | :----------------------------------- |
| none | Do not flatten fields |
| filled | Flatten only fields filled by signer |
| all | Flatten all fields `default` |
Override the default ink color `#0000FF` for Ink to Sign signatures and initials with a valid #-hexadecimal RGB color value.
2.10
Set preferred default mark type.
4.0
| Value | Description |
| :-------------- | :---------- |
| touch\_to\_sign | iink It |
| type\_to\_sign | Type It |
| click\_to\_sign | Accept It |
Add a retention period to the package to prevent deletion. (ISO 8601 duration)
1.11
Override system messages by message key. Each value contains an optional
`default` string and an optional `locale` map of locale codes to strings.
Values are limited to 1,024 characters and cannot contain website domains or
email addresses.
3.6
Add custom consent notice text by consent type: `signing`, `verification`, or
`video_recording`. Each value contains an optional `default` string and an
optional `locale` map of locale codes to strings. Custom text is appended to
the system notice, supports locale fallback, is limited to 1,024 characters,
and cannot contain website domains or email addresses.
4.2
Parse document for templating tags. Defaults to true.
Parse merger data templating tags. Defaults to false.
4.0
Control how unused signer tags are handled.
2.6
| Value | Description |
| :----- | :------------------------------- |
| keep | Leave unused tags in document |
| hide | Move unused tags to hidden layer |
| remove | Remove unused tags `default` |
Control which document(s) within a package have the CAC page appended to them.
3.2
| Value | Description |
| :-------------- | :---------------------------------- |
| document\_all | Append to all documents in package |
| document\_first | Append to first document in package |
| document\_last | Append to last document in package |
When enabled will add a signer identification placeholder for each signer on the CAC page.
3.2
Add a custom disclaimer to the top of the Compliance Audit Certificate.
1.10
Enabled 2FA security code.
All signers will require a valid mobile phone number to enable mobile MFA.
Enabled 2FA security passphrase.
You must also set a passphrase as part of add or update request to enabled 2FA security passphrase.
```json theme={null}
{
"options": {
"securityPassphrase": true,
...
},
"securityPassphrase": "mySecretPassphrase"
}
```
Enable all mark types.
Enabled click to sign `Accept It`.
Enabled type to sign `Type It`.
Enabled touch to sign `Ink It`.
Allows signer to use desktop mouse to draw signature via touch to sign.
Allow signers to apply their last used iink signature during a signing session. Defaults to `false`.
4.1
Automatically starts video recording after host starts meeting and first attendee joins.
Disables video recording feature preventing host from recording signing session.
Add a retention period to all package videos to prevent deletion. (ISO 8601 duration)
1.11
Share meeting details and videos with guest signers via MasterFile.
Prevent all package notifications from being sent to signers. This option will override other notify options. This option will not prevent Document Accessed (notifyAccessed) notifications if enabled.
1.10.4
Set to false to not include signed documents as attachments in executed email notifications.
2.5
Send email notification to owner to confirm package was created.
Send email notification to owner whenever a signer opens a document (limited to once every hour).
Send email notification to each signer when it is their turn to sign.
Send email notification to each signer to notify them that they are waiting their turn to sign.
Send email notification to each signer when Video Signing Room meeting is scheduled.
Include ICS compatible meeting invitation with email notification to schedule meeting date and time in recipients' calendar.
Send email notification to signer after they sign each document.
2.5
For Sequential packages, the next signer notification is only sent after the current signer has signed all of their documents.
3.3
Send email to owner to notify them when all signers have signed each document.
Don't send document executed email until all documents in the package have been fully signed.
3.3
`Counterparts` Send document executed notification TO package owner and CC signer.
1.10
Send signers fully executed document with CAC page appended to end of document.
1.10
Send signers fully executed document without CAC page appended to end of document.
1.10
Send signers separated CAC page as an additional attachment.
1.10
Allow signer to add additional fields while signing documents. Customize signerTools to control what fields the signer can add.
Allow signer to delete any templated fields while signing a document. This is default behavior for VSR and In Person package types. It is recommended to use optional fields instead for Concurrent, Sequential, and Group Send package types.
2.10
Customize signer toolbar options.
Enable sign.
Enable annotations (ink) on mobile devices.
Enable annotations (ink) on desktop.
Enable text.
Enable note.
Enable forms.
Auto highlight form fields.
Enable image.
Request Signers Geolocation while signing documents, joining VSR meetings, performing IDV, and connecting to a mobile signature pad.
Customize how Geolocation is collected.
3.6
Require geolocation to be shared before allowing the signer to continue.
Require geolocation to be shared before the signer can sign documents.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can use signature pad.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can join VSR meetings.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can verify their identity.
(`required` must also be set to `true`)
Enable custom PDF security options.
2.10
Customize PDF security options.
2.10
Allow PDF merge operations.
Allow copying PDF content.
Allow only degraded PDF printing.
Allow PDF AcroForms fields to be filled in (when formFlattening option is not set to "all").
Allow PDF annotations.
Allow PDF editing.
Allow PDF printing.
Allow screen readers.
PDF security options are enforced only when the PDF is opened in a PDF viewer that supports the PDF security settings. Not all PDF viewers support these settings.
Configure consent requirements and automatic reuse.
4.2
Require the signer to provide consent before completing a configured consent
action. Defaults to `false`.
Require consent before signing. Defaults to `true`.
Require consent before video recording in a Video Signing Room package.
Defaults to `false`.
Reuse a member's previously accepted consent when the consent type and notice
version match and the acceptance occurred within this number of days. Defaults
to `90`. Set to `0` to disable automatic reuse.
Set identity verification options.
3.2
The policy ID of the custom Identity Verification Policy to use during signer identity verification. (Custom IDV policies currently must be created by our Support Team for your organization.)
The code of one of our standard Identity Verification Policy to use during signer identity verification.
| Policy Code | Pass-To-Sign | Region | Retries |
| :--------------------------------------- | :----------: | :----: | :-----: |
| trulioo3\_document | false | Any | 2 |
| trulioo3\_document\_required | true | Any | 2 |
| trulioo3\_document\_ca\_strict | false | CA | 2 |
| trulioo3\_document\_ca\_strict\_required | true | CA | 2 |
**Pass-To-Sign** indicates whether the signer must successfully complete identity verification before they can sign their documents.
Configure the digital signature types and providers available to signers.
4.2
Map each enabled digital signature type to an ordered list of provider names.
| Signature type | Description |
| :------------- | :----------------------------- |
| `qes` | Qualified Electronic Signature |
| Value | Provider |
| :------------ | :---------- |
| `digidentity` | Digidentity |
Provider availability depends on your subscription and organization configuration.
Set package `Remind Me Later` options.
4.0
Number of days, from today, to send a reminder notification to the package owner.
Message that will be sent with the reminder notification to package owner.
# PDF security options
Source: https://docs.iinkedsign.com/v4/reference/package-options/pdf-security-options
Allow PDF merge operations.
Allow copying PDF content.
Allow only degraded PDF printing.
Allow PDF AcroForms fields to be filled in (when formFlattening option is not set to "all").
Allow PDF annotations.
Allow PDF editing.
Allow PDF printing.
Allow screen readers.
PDF security options are enforced only when the PDF is opened in a PDF viewer that supports the PDF security settings. Not all PDF viewers support these settings.
# Reminder options
Source: https://docs.iinkedsign.com/v4/reference/package-options/reminder-options
Number of days, from today, to send a reminder notification to the package owner.
Message that will be sent with the reminder notification to package owner.
# Signer tools
Source: https://docs.iinkedsign.com/v4/reference/package-options/signer-tools
Enable sign.
Enable annotations (ink) on mobile devices.
Enable annotations (ink) on desktop.
Enable text.
Enable note.
Enable forms.
Auto highlight form fields.
Enable image.
# Consent
Source: https://docs.iinkedsign.com/v4/reference/packages/consent
Unique identifier for the consent record.
Consent record reused by an automatic acceptance.
Organization that owns the consent record.
Member associated with the consent.
Package associated with the consent.
Signer associated with the consent.
Identity verification associated with the consent.
Signing session associated with the consent.
Time the consent was accepted (ISO 8601 date-time).
Time the consent was declined (ISO 8601 date-time).
Time the consent was revoked (ISO 8601 date-time).
IP address from which consent was recorded.
Action used to record the consent.
| Value | Version | Description |
| :------------------------- | :------ | :------------------------------------------------------------ |
| `auto` | 4.2 | Consent was reused automatically under the configured policy. |
| `clicked_consent_button` | 4.2 | The signer accepted by selecting the consent button. |
| `clicked_decline_button` | 4.2 | The signer declined by selecting the decline button. |
| `checked_consent_checkbox` | 4.2 | The signer accepted by selecting the consent checkbox. |
| `on_behalf_of` | 4.2 | Consent was recorded on behalf of the signer. |
Base64-encoded SHA-256 version of the consent notice.
Notice presented when consent was recorded.
Default notice text.
Notice text keyed by locale code.
Consent type.
| Value | Version | Description |
| :---------------- | :------ | :---------------------------------------------- |
| `signing` | 4.2 | Consent to sign documents. |
| `verification` | 4.2 | Consent to complete identity verification. |
| `video_recording` | 4.2 | Consent to record a Video Signing Room session. |
Current consent state.
| Value | Version | Description |
| :--------- | :------ | :------------------------------------------------------------- |
| `required` | 4.2 | Consent is required and has not yet been accepted or declined. |
| `accepted` | 4.2 | Consent was accepted. |
| `declined` | 4.2 | Consent was declined. |
| `revoked` | 4.2 | Previously accepted consent was revoked. |
# Meeting
Source: https://docs.iinkedsign.com/v4/reference/packages/meeting
Unique identifier for the meeting.
Organization associated with the meeting.
Package associated with the meeting.
Meeting start time (ISO 8601 date-time).
Meeting duration (ISO 8601 duration string).
Set to `true` if the meeting is private.
Meeting type identifier.
Current state of the meeting.
| Value | Description |
| :---------- | :------------------- |
| scheduled | Scheduled meeting. |
| rescheduled | Rescheduled meeting. |
| cancelled | Cancelled meeting. |
# Meeting types
Source: https://docs.iinkedsign.com/v4/reference/packages/meeting-types
| Value | Description |
| :------ | :---------------------------------------------------------------------- |
| signing | Scheduled Video Signing Room meeting where participants sign documents. |
# Package
Source: https://docs.iinkedsign.com/v4/reference/packages/package
Unique identifier for the package.
Unique identifier for the organization that owns the package.
Identifier for the member who created/owns the package.
Team identifier associated with the package. (optional)
Folder identifier where the package is stored. (optional)
Set to `true` if the package is shared.
Current scheduled meeting ID for the package (if applicable).
ID of the template the package was created from (if applicable).
ID of the form the package was created from (if applicable).
ID of the API key used to create the package (if created via API key).
Display name of the package.
Category for the package. (optional)
Client reference number. (optional)
Matter reference number. (optional)
Description of the package. (optional)
Message included when the package was sent. (optional)
Message explaining why the package was rescinded. (optional)
Reminder message for signers. (optional)
Creation time (ISO 8601 date-time).
Reminder time (ISO 8601 date-time).
Retention expiry time (ISO 8601 date-time).
Time the package was rescinded (ISO 8601).
Time the package was deleted (ISO 8601).
Deadline for signing (ISO 8601 date-time).
Last modification time (ISO 8601 date-time).
Package options.
Enable embedded signing mode.
Embed options used to customize the embedded package editor.
2.8
User can only save changes to draft packages; the user will not be able to send it.
User will not be allowed to modify package properties.
User will not be allowed to modify package verification properties.
User will not be allowed to modify package signers.
User will not be allowed to modify package documents.
User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.
The first document will be focused when the package editor is loaded instead of the package properties.
User will be redirected back to the returnUrl when they are done editing the package.
Will be included in a `state` query string parameter appended to the `returnUrl`.
Show custom brand when signing package.
1.10
Add document identifier to each page (QR code).
Allow VSR participants to review documents before a meeting via a Review Documents link added to email meeting invitation.
2.6
Allow signers to forward the signing to another email address.
4.0
Enabled to not share email addresses between signers.
2.11
Supported in the following package types:
* Concurrent (`concurrent`)
* Sequential (`Sequential`)
* Group Send (`Counterparts`)
Do not allow signers to fill AcroForm fields during signing.
3.3
Do not allow signers to modify AcroForm fields during signing.
3.6
Control how Acroform fields are flattened after signing a document.
2.6
| Value | Description |
| :----- | :----------------------------------- |
| none | Do not flatten fields |
| filled | Flatten only fields filled by signer |
| all | Flatten all fields `default` |
Override the default ink color `#0000FF` for Ink to Sign signatures and initials with a valid #-hexadecimal RGB color value.
2.10
Set preferred default mark type.
4.0
| Value | Description |
| :-------------- | :---------- |
| touch\_to\_sign | iink It |
| type\_to\_sign | Type It |
| click\_to\_sign | Accept It |
Add a retention period to the package to prevent deletion. (ISO 8601 duration)
1.11
Override system messages by message key. Each value contains an optional
`default` string and an optional `locale` map of locale codes to strings.
Values are limited to 1,024 characters and cannot contain website domains or
email addresses.
3.6
Add custom consent notice text by consent type: `signing`, `verification`, or
`video_recording`. Each value contains an optional `default` string and an
optional `locale` map of locale codes to strings. Custom text is appended to
the system notice, supports locale fallback, is limited to 1,024 characters,
and cannot contain website domains or email addresses.
4.2
Parse document for templating tags. Defaults to true.
Parse merger data templating tags. Defaults to false.
4.0
Control how unused signer tags are handled.
2.6
| Value | Description |
| :----- | :------------------------------- |
| keep | Leave unused tags in document |
| hide | Move unused tags to hidden layer |
| remove | Remove unused tags `default` |
Control which document(s) within a package have the CAC page appended to them.
3.2
| Value | Description |
| :-------------- | :---------------------------------- |
| document\_all | Append to all documents in package |
| document\_first | Append to first document in package |
| document\_last | Append to last document in package |
When enabled will add a signer identification placeholder for each signer on the CAC page.
3.2
Add a custom disclaimer to the top of the Compliance Audit Certificate.
1.10
Enabled 2FA security code.
All signers will require a valid mobile phone number to enable mobile MFA.
Enabled 2FA security passphrase.
You must also set a passphrase as part of add or update request to enabled 2FA security passphrase.
```json theme={null}
{
"options": {
"securityPassphrase": true,
...
},
"securityPassphrase": "mySecretPassphrase"
}
```
Enable all mark types.
Enabled click to sign `Accept It`.
Enabled type to sign `Type It`.
Enabled touch to sign `Ink It`.
Allows signer to use desktop mouse to draw signature via touch to sign.
Allow signers to apply their last used iink signature during a signing session. Defaults to `false`.
4.1
Automatically starts video recording after host starts meeting and first attendee joins.
Disables video recording feature preventing host from recording signing session.
Add a retention period to all package videos to prevent deletion. (ISO 8601 duration)
1.11
Share meeting details and videos with guest signers via MasterFile.
Prevent all package notifications from being sent to signers. This option will override other notify options. This option will not prevent Document Accessed (notifyAccessed) notifications if enabled.
1.10.4
Set to false to not include signed documents as attachments in executed email notifications.
2.5
Send email notification to owner to confirm package was created.
Send email notification to owner whenever a signer opens a document (limited to once every hour).
Send email notification to each signer when it is their turn to sign.
Send email notification to each signer to notify them that they are waiting their turn to sign.
Send email notification to each signer when Video Signing Room meeting is scheduled.
Include ICS compatible meeting invitation with email notification to schedule meeting date and time in recipients' calendar.
Send email notification to signer after they sign each document.
2.5
For Sequential packages, the next signer notification is only sent after the current signer has signed all of their documents.
3.3
Send email to owner to notify them when all signers have signed each document.
Don't send document executed email until all documents in the package have been fully signed.
3.3
`Counterparts` Send document executed notification TO package owner and CC signer.
1.10
Send signers fully executed document with CAC page appended to end of document.
1.10
Send signers fully executed document without CAC page appended to end of document.
1.10
Send signers separated CAC page as an additional attachment.
1.10
Allow signer to add additional fields while signing documents. Customize signerTools to control what fields the signer can add.
Allow signer to delete any templated fields while signing a document. This is default behavior for VSR and In Person package types. It is recommended to use optional fields instead for Concurrent, Sequential, and Group Send package types.
2.10
Customize signer toolbar options.
Enable sign.
Enable annotations (ink) on mobile devices.
Enable annotations (ink) on desktop.
Enable text.
Enable note.
Enable forms.
Auto highlight form fields.
Enable image.
Request Signers Geolocation while signing documents, joining VSR meetings, performing IDV, and connecting to a mobile signature pad.
Customize how Geolocation is collected.
3.6
Require geolocation to be shared before allowing the signer to continue.
Require geolocation to be shared before the signer can sign documents.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can use signature pad.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can join VSR meetings.
(`required` must also be set to `true`)
Require geolocation to be shared before the signer can verify their identity.
(`required` must also be set to `true`)
Enable custom PDF security options.
2.10
Customize PDF security options.
2.10
Allow PDF merge operations.
Allow copying PDF content.
Allow only degraded PDF printing.
Allow PDF AcroForms fields to be filled in (when formFlattening option is not set to "all").
Allow PDF annotations.
Allow PDF editing.
Allow PDF printing.
Allow screen readers.
PDF security options are enforced only when the PDF is opened in a PDF viewer that supports the PDF security settings. Not all PDF viewers support these settings.
Configure consent requirements and automatic reuse.
4.2
Require the signer to provide consent before completing a configured consent
action. Defaults to `false`.
Require consent before signing. Defaults to `true`.
Require consent before video recording in a Video Signing Room package.
Defaults to `false`.
Reuse a member's previously accepted consent when the consent type and notice
version match and the acceptance occurred within this number of days. Defaults
to `90`. Set to `0` to disable automatic reuse.
Set identity verification options.
3.2
The policy ID of the custom Identity Verification Policy to use during signer identity verification. (Custom IDV policies currently must be created by our Support Team for your organization.)
The code of one of our standard Identity Verification Policy to use during signer identity verification.
| Policy Code | Pass-To-Sign | Region | Retries |
| :--------------------------------------- | :----------: | :----: | :-----: |
| trulioo3\_document | false | Any | 2 |
| trulioo3\_document\_required | true | Any | 2 |
| trulioo3\_document\_ca\_strict | false | CA | 2 |
| trulioo3\_document\_ca\_strict\_required | true | CA | 2 |
**Pass-To-Sign** indicates whether the signer must successfully complete identity verification before they can sign their documents.
Configure the digital signature types and providers available to signers.
4.2
Map each enabled digital signature type to an ordered list of provider names.
| Signature type | Description |
| :------------- | :----------------------------- |
| `qes` | Qualified Electronic Signature |
| Value | Provider |
| :------------ | :---------- |
| `digidentity` | Digidentity |
Provider availability depends on your subscription and organization configuration.
Set package `Remind Me Later` options.
4.0
Number of days, from today, to send a reminder notification to the package owner.
Message that will be sent with the reminder notification to package owner.
Set to `true` if the package is protected by a security passphrase.
Language/locale for the package.
Time zone for package date/time presentation.
Formatting options for dates and presentation.
Locale code used for formatting. (optional)
Inherits from the package locale if not specified.
Number of signed revisions across package documents.
Total number of revisions across package documents.
Restriction type applied to the package. (optional)
Set to `true` if the package was created via the API.
Package type identifier.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Current state of the package.
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
Arbitrary external data attached to the package.
Package version or timestamp (ISO 8601).
If the package is scheduled for a meeting, the meeting details.
Unique identifier for the meeting.
Organization associated with the meeting.
Package associated with the meeting.
Meeting start time (ISO 8601 date-time).
Meeting duration (ISO 8601 duration string).
Set to `true` if the meeting is private.
Meeting type identifier.
Current state of the meeting.
| Value | Description |
| :---------- | :------------------- |
| scheduled | Scheduled meeting. |
| rescheduled | Rescheduled meeting. |
| cancelled | Cancelled meeting. |
Documents that belong to the package.
Unique identifier for the document.
Identifier of the package this document belongs to.
Unique identifier for the file associated with the document.
Auto-template identifier (if created from an auto-template).
Auto-template document identifier (if applicable).
External identifier for the document. (optional)
Order/index of the document within the package.
Document display name.
Original filename uploaded.
File extension or type identifier.
Size of the file in bytes.
Number of pages in the document.
Upload time (ISO 8601 date-time).
Last modified time (ISO 8601 date-time).
Number of signed revisions for this document.
Total number of revisions for this document.
Description of the document. (optional)
Set to `true` if a CAC (Compliance Audit Certificate) has been appended to the document.
Number of CAC pages if `cac` is `true`.
Current state of the document.
Most document states are used internally. All documents included in a returned package will always be in the open state.
| Values | Description |
| :----- | :--------------------------------------------------- |
| open | The document is open and can be interacted with. |
| failed | The document failed to process and cannot be signed. |
Revision history for the document. Typically includes one revision per signer.
ID of the document this revision belongs to.
Unique identifier for the revision.
Revision number (incrementing integer).
Identifier of the previous revision this revision replaced. (optional)
Last opened time for the revision (ISO 8601).
Signer who is associated with this revision.
Set to `true` if this revision has been signed.
Time the revision was signed (ISO 8601).
Address metadata captured on sign. (optional)
Latitude coordinate captured on sign. (optional)
Longitude coordinate captured on sign. (optional)
State of the revision (for example: signed, pending).
Signers associated with this document.
Identifier for the signer associated with the document.
Internal signer key used to map fields/tags.
Full name for the signer on this document.
Signer initials.
Email for the signer on this document.
Mobile number for the signer on this document. (optional)
Set to `true` if the signer has signed this document.
Set to `true` if this signer is next in the signing order for this document.
Template role name if the signer was created from a template role. (optional)
Signers for the package.
Unique identifier for the signer.
Package identifier the signer belongs to.
Member identifier when the signer is an organization member. (optional)
Tag associated with the signer. (optional)
When the signer record was created (ISO 8601).
Time the signer declined (if applicable).
Last update time for the signer record.
Signing order index.
Locale for the signer. (optional)
Set to `true` if signer requires CAC signing.
Set to `true` if signer requires identity verification before signing.
First name of the signer.
Last name of the signer.
Email address for the signer.
Country code for the mobile number. (optional)
Original mobile number provided.
Normalized mobile number (E.164) when available.
Message left by the signer when declining (if any).
Reason code for decline (if applicable).
Set to `true` if this signer is next in signing order across the package.
Number of revisions the signer has signed.
Number of revisions assigned to the signer.
Role of the signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Type of signer.
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
Current state of the signer.
| Value | Description |
| :------- | :-------------------------------------------------------------- |
| active | Signer that is actively participating in the signing process. |
| declined | Signer that has declined to participate in the signing process. |
| deleted | Signer that has been removed from the package. |
Signer verification status. (if any)
Identifier for the verification record.
Signer identifier associated with this verification.
Set to `true` if the signer is can sign documents after verification.
Set to `true` if the signer can join VSR after verification.
Set to `true` if the signer may retry verification on failure.
Set to `true` if the signer has successfully signed after verification.
Set to `true` if the verification is currently locked.
Number of verification attempts made.
Number of errors encountered during verification.
Whether the verification flow should continue to next step.
Whether to continue the flow when verification errors occur.
Current verification error code (if any).
Current state of the verification.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Recipients related to the package (additional recipients beyond signers).
Unique identifier for the recipient.
Identifier of the package the recipient belongs to.
Creation time for the recipient record (ISO 8601).
Last update time for the recipient record (ISO 8601).
Recipient first name.
Recipient last name.
Recipient email address.
Recipient mobile number country code. (optional)
Original recipient mobile number provided.
Normalized recipient mobile number. (optional)
Recipient locale. (optional)
Recipient type.
Current state of the recipient record.
Verification records associated with the package.
Identifier for the verification record.
Signer identifier associated with this verification.
Set to `true` if the signer is can sign documents after verification.
Set to `true` if the signer can join VSR after verification.
Set to `true` if the signer may retry verification on failure.
Set to `true` if the signer has successfully signed after verification.
Set to `true` if the verification is currently locked.
Number of verification attempts made.
Number of errors encountered during verification.
Whether the verification flow should continue to next step.
Whether to continue the flow when verification errors occur.
Current verification error code (if any).
Current state of the verification.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Consent records associated with the package.
4.2
Unique identifier for the consent record.
Consent record reused by an automatic acceptance.
Organization that owns the consent record.
Member associated with the consent.
Package associated with the consent.
Signer associated with the consent.
Identity verification associated with the consent.
Signing session associated with the consent.
Time the consent was accepted (ISO 8601 date-time).
Time the consent was declined (ISO 8601 date-time).
Time the consent was revoked (ISO 8601 date-time).
IP address from which consent was recorded.
Action used to record the consent.
| Value | Version | Description |
| :------------------------- | :------ | :------------------------------------------------------------ |
| `auto` | 4.2 | Consent was reused automatically under the configured policy. |
| `clicked_consent_button` | 4.2 | The signer accepted by selecting the consent button. |
| `clicked_decline_button` | 4.2 | The signer declined by selecting the decline button. |
| `checked_consent_checkbox` | 4.2 | The signer accepted by selecting the consent checkbox. |
| `on_behalf_of` | 4.2 | Consent was recorded on behalf of the signer. |
Base64-encoded SHA-256 version of the consent notice.
Notice presented when consent was recorded.
Default notice text.
Notice text keyed by locale code.
Consent type.
| Value | Version | Description |
| :---------------- | :------ | :---------------------------------------------- |
| `signing` | 4.2 | Consent to sign documents. |
| `verification` | 4.2 | Consent to complete identity verification. |
| `video_recording` | 4.2 | Consent to record a Video Signing Room session. |
Current consent state.
| Value | Version | Description |
| :--------- | :------ | :------------------------------------------------------------- |
| `required` | 4.2 | Consent is required and has not yet been accepted or declined. |
| `accepted` | 4.2 | Consent was accepted. |
| `declined` | 4.2 | Consent was declined. |
| `revoked` | 4.2 | Previously accepted consent was revoked. |
# Sort by
Source: https://docs.iinkedsign.com/v4/reference/packages/package-filter-sort
```http theme={null}
POST /packages/list
{
...
"sortBy": "sign_by"
...
}
```
| Value | Description |
| :------------------ | :--------------------------------------------------- |
| created | Date package was created (descending). |
| last\_modified | Date package was last modified (descending). |
| reminder | Date of scheduled reminder (descending). |
| signed | Date package was signed by last signer (descending). |
| sign\_by | Date package is to be signed by (descending). |
| sign\_by\_ascending | Date package is to be signed by (ascending). |
# Package states
Source: https://docs.iinkedsign.com/v4/reference/packages/package-states
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
# Package status
Source: https://docs.iinkedsign.com/v4/reference/packages/package-status
Unique identifier for the package.
Unique identifier for the organization.
Unique identifier for the member who owns the package.
Name of the package.
Date by which the package should be signed (ISO 8601 format).
Type of the package.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Current state of the package.
New package states may be added in future releases. It is recommended that you always validate your integration against the sandbox before new releases are deployed into production.
Release 4.0 introduces two new package states, `executed` and `expired`. In 3.6 both executed and expired packages were in an `open` state.
| Value | Version | Description |
| :-------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| draft | 1.0 | Package will be added in a draft state. Notifications will not be sent to the signer(s). You must call the send API, or the package owner must manually send the package from within iinked Sign. |
| open | 1.0 | The package will be ready for signing, and notifications will be sent to the signer(s) if enabled. |
| executed | 4.0 | The package has been fully executed by all signers. |
| expired | 4.0 | The package was not signed by the sign by date and has now expired. VSR packages will expire 7 days after their scheduled meeting date. |
| rescinded | 3.5 | The package was rescinded and is no longer available for signing. |
| select | 3.6 | Use the select state only when the package will be opened in the **embedded package editor** and you want the workflow to prompt the user to choose a package type. Packages in the select state will be automatically deleted if not converted to draft or open within 24 hours. |
| add | 2.9 | Use the add state only when the package will be opened in the **embedded package editor** and you want the workflow to function as if you're creating a new package, rather than editing an existing one. Packages in the add state will be automatically deleted if not converted to draft or open within 24 hours. |
External data associated with the package.
Set to `true` if all documents have been signed by all signers.
List of documents in the package.
Unique identifier for the package.
Unique identifier for the document.
Unique identifier for the file associated with the document.
External system identifier for the document, if available.
Name of the document.
File name of the document.
Order of the document in the package.
Set to `true` if document has been signed by all signers.
List of revisions for the document.
Unique identifier for the package.
Unique identifier for the document.
Unique identifier for the revision.
Unique identifier for the signer.
Link for signer to sign their revision of document.
Set to `true` if signer is next signer in sequential signing.
Set to `true` if signer has signed their revision of document.
List of signers for the package.
Unique identifier for the signer.
First name of the signer.
Last name of the signer.
Email address of the signer.
Mobile number of the signer.
Order of the signer in the signing process.
List of signing links for the signer.
Token for the signing link.
Unique identifier for the package.
Unique identifier for the document.
Unique identifier for the revision.
Name of document.
Link for signer to sign their revision of document.
Time link expires (ISO 8601 format).
Link type.
Set to `true` if signer is next signer in sequential signing.
Set to `true` if signer has signed their revision of document.
# Package types
Source: https://docs.iinkedsign.com/v4/reference/packages/package-types
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
# Sandbox
Source: https://docs.iinkedsign.com/v4/sandbox
## Overview
The Sandbox environment allows you to test and experiment with the iinked Sign API without affecting your production data. This is a safe space to explore the API's capabilities and understand how to integrate it into your applications.
## Request access
Visit [iinkedSign.com/api-request](https://iinkedsign.com/api-request) to request access to the Sandbox environment. Once your request is approved, you will receive instructions on how to set up your sandbox account.
## Sandbox instances
### US
API endpoint: `https://sandbox.syngrafii.com/api/v1`\
API key management: [https://sandbox.syngrafii.com/integration](https://sandbox.syngrafii.com/integration)
### EU
API endpoint: `https://sandbox.syngrafii.eu/api/v1`\
API key management: [https://sandbox.syngrafii.eu/integration](https://sandbox.syngrafii.eu/integration)
# Document accessed
Source: https://docs.iinkedsign.com/v4/webhooks/events/document-accessed
Fired when a document within a package has been **opened** by the next signer.
## Example
```json Payload theme={null}
{
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"documentId": "73f34799-c3a2-49e3-aa5f-33b0c2c1f111",
"revisionId": "ecaac2dc-8fe2-48fd-b3d5-74646435b1d2",
"signerId": "d5397c13-5dcf-4574-b94b-5addf95c91df",
"externalId": null,
"action": "document_accessed",
"eventId": "9ee08c2e-05a7-4cfd-8e95-9e631c885174",
"eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
"eventTime": "2022-02-23T20:19:48.3908675Z"
}
```
# Document executed
Source: https://docs.iinkedsign.com/v4/webhooks/events/document-executed
Fired when a document within a package has been **signed by all signers**.
* Download the executed document and add it to your system
* Update the state of document within your system
## Example
```json Payload theme={null}
{
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"documentId": "73f34799-c3a2-49e3-aa5f-33b0c2c1f111",
"externalId": null,
"action": "document_executed",
"eventId": "8977f701-480a-4a5d-9bad-87d87fe38447",
"eventTime": "2022-02-23T20:20:15.9021584Z"
}
```
# Document next
Source: https://docs.iinkedsign.com/v4/webhooks/events/document-next
Fired when document is now ready for signing by the next signer.
* In a sequential package you can use this event to handle any custom workflow logic required for the next signer
This event does not get sent for first signer.
## Example
```json Payload theme={null}
{
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"documentId": "73f34799-c3a2-49e3-aa5f-33b0c2c1f111",
"signerId": "f700fdfa-b493-467e-b30d-7eb17e2bb769",
"externalId": null,
"action": "document_next",
"eventId": "68d4457e-7148-4c01-9556-d1f5e733c5ef",
"eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
"eventTime": "2022-02-23T20:19:56.8243719Z"
}
```
# Document signed
Source: https://docs.iinkedsign.com/v4/webhooks/events/document-signed
Fired when a document within a package has been **signed by the next signer**.
* Download the current document (in Sequential signing will not contain all signatures unless last signer) and add it to your system
* Update the state of the document for the signer within your system
## Example
```json Payload theme={null}
{
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"documentId": "73f34799-c3a2-49e3-aa5f-33b0c2c1f111",
"revisionId": "ecaac2dc-8fe2-48fd-b3d5-74646435b1d2",
"signerId": "d5397c13-5dcf-4574-b94b-5addf95c91df",
"nextSignerId": "f700fdfa-b493-467e-b30d-7eb17e2bb769",
"externalId": null,
"action": "document_signed",
"eventId": "f3a27f18-b892-4c4d-8ffa-81f2f459017f",
"eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
"eventTime": "2022-02-23T20:19:56.8208742Z"
}
```
# Notification status
Source: https://docs.iinkedsign.com/v4/webhooks/events/notification-status
When a notification has been sent you will receive one or more events as its delivery is being processed such as `submitted` followed by `delivered` or `failed`.
Private instances configured with an SMTP server will only receive the `submitted` event unless the failure occurs while sending.
## Example
```json Payload theme={null}
{
"notificationId": "1ad50d25-5d04-4e11-b1f0-8078b22986ce",
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"documentId": null,
"template": "package_sign",
"type": "email",
"state": "submitted",
"action": "notification_status",
"eventId": "60c25aef-19d7-40f1-b428-d049aa549450",
"eventTime": "2022-02-23T20:19:31.540923Z"
}
```
| Value | Description |
| :---- | :------------------------------ |
| email | Notification was sent via email |
| sms | Notification was sent via SMS |
| Value | Description |
| :-------- | :-------------------------------------- |
| submitted | Notification was submitted for delivery |
| delivered | Notification was delivered successfully |
| failed | Notification delivery failed |
| Value | Description |
| :---------------------------- | :---------------------------------------------------------------------------- |
| package\_cancelled | Notification that a package has been cancelled |
| package\_created | Notification that a package has been created |
| package\_declined | Notification that a package has been declined |
| package\_executed | Notification that a package has been executed |
| package\_export\_failed | Notification that a package export has failed |
| package\_forwarded | Notification that a package has been forwarded |
| package\_future\_reminder | Reminder notification for a package |
| package\_masterfile\_link | Notification containing a link to the package masterfile |
| package\_meeting | Notification for a package meeting |
| package\_meeting\_cancelled | Notification that a package meeting has been cancelled |
| package\_notification | General notification related to a package |
| package\_notification\_failed | Notification that a package notification failed |
| package\_rescinded | Notification that a package has been rescinded |
| package\_review\_link | Notification containing a link to review the package |
| package\_sign | Notification to sign a package |
| package\_sign\_witness | Notification to sign a package with a witness |
| package\_updated | Notification that a package has been updated |
| document\_accessed | Notification that a document has been accessed |
| document\_executed | Notification that a document has been executed |
| document\_executed\_all | Notification that a document has been executed by all signers |
| document\_next | Notification that a document is next to be signed |
| document\_reminder | Reminder notification to sign a document |
| document\_signed | Notification that a document has been signed |
| document\_signer\_link | Notification containing a link for the signer to sign the document |
| mobile\_link | Notification contains a link to open the signature pad on a mobile device |
| verification\_completed | Notification that identity verification has been completed |
| verification\_failed | Notification that identity verification has failed |
| verification\_first | Notification that identity verification is required before signing or meeting |
| verification\_link | Notification containing a link to complete identity verification |
# Package add
Source: https://docs.iinkedsign.com/v4/webhooks/events/package-add
Fired when a new package is created.
* Useful to monitor packages added directly from within iinked Sign.
* You can call `packages/status` to get a summary of the package, including the next signers.
If you are creating the new signing package via the `packages/add` API you typically have already handled your server-side logic for `package_add` and can ignore this event.
## Example
```json Payload theme={null}
{
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"externalData": null,
"action": "package_add",
"eventId": "e9b8fe63-4a19-4446-bd6e-cb34b72b411e",
"eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
"eventTime": "2022-02-23T20:19:28.9357901Z"
}
```
# Package decline
Source: https://docs.iinkedsign.com/v4/webhooks/events/package-decline
Fired when a package is declined by a signer. This event is fired when a signer declines to sign a package or when a signer declines to share their geolocation (only when geolocation is set to required).
* declineReason (optional reason for being declined)
* declined\_geolocation
* rescinded (if the package was rescinded)
## Example
```json Payload theme={null}
{
"packageId": "dd37674b-7545-40d8-91f4-db35b5dd271d",
"signerId": "738880d9-2427-4eef-9bb4-554412a99654",
"rescinded": false,
"declineReason": "declined_geolocation",
"state": "active",
"action": "package_decline",
"eventId": "0e294781-0de1-4cc4-89b4-0079581e594a",
"eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
"eventTime": "2024-10-08T13:27:58.1324692Z"
}
```
# Package delete
Source: https://docs.iinkedsign.com/v4/webhooks/events/package-delete
Fired when a package is deleted.
## Example
```json Payload theme={null}
{
"packageId": "c24c4fa5-2bd8-4b5c-b717-6ab3297cb424",
"externalData": null,
"action": "package_delete",
"eventId": "1221fde3-4200-4c65-ba88-8a787e9f7758",
"eventOwnerOrganizationId": "a51aa87f-2567-490e-8a93-00618f0cc3de",
"eventOwnerMemberId": "83ac20dc-ca4d-4534-a8f5-61ce0934fe71",
"eventTime": "2023-03-20T18:45:38.2509538Z"
}
```
# Package executed
Source: https://docs.iinkedsign.com/v4/webhooks/events/package-executed
Fired when **all documents** within a package have been **executed**.
* Download all executed documents and add them to your system
* Update the state of all documents and package within your system
## Example
```json Payload theme={null}
{
"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
"externalData": null,
"action": "package_executed",
"eventId": "0ea12600-85bc-46dd-af85-f82f621c1abc",
"eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
"eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
"eventTime": "2022-02-23T20:20:15.9714327Z"
}
```
# Package expired
Source: https://docs.iinkedsign.com/v4/webhooks/events/package-expired
When a package has not been signed by its Sign By date it will transition into an expired state and fire this event.
VSR packages will expire 7 days after their scheduled meeting date.
## Example
```json Payload theme={null}
{
"packageId": "6bfaec8a-cc7f-470f-a84d-69abcda2a36e",
"externalData": null,
"action": "package_expired",
"eventId": "76ca33aa-93f9-4753-81db-591def275b94",
"eventOwnerMemberId": "ce5b813a-92e0-4958-8c16-43e608c9f4bc",
"eventTime": "2025-08-20T15:37:26.5427339Z"
}
```
# Package rescind
Source: https://docs.iinkedsign.com/v4/webhooks/events/package-rescind
Fired when a package is rescinded.
## Example
```json Payload theme={null}
{
"packageId": "ea24f722-3535-4869-8afc-dc6f2ee585b7",
"externalData": null,
"action": "package_rescind",
"eventId": "d002627a-b623-424c-af2e-d5c25f78e84d",
"eventTime": "2023-03-21T13:33:16.7221085Z"
}
```
# Package send
Source: https://docs.iinkedsign.com/v4/webhooks/events/package-send
Fired when an existing package in a `select`, `add`, or `draft` state is sent.
This event is only triggered on a successful call to `packages/send`.
Use the `package_sent` event to track when packages are sent for signing from any endpoint such as `packages/add`, `packages/update`, or `packages/send`.
## Example
```json Payload theme={null}
{
"packageId": "ea24f722-3535-4869-8afc-dc6f2ee585b7",
"externalData": null,
"action": "package_send",
"eventId": "d5f4a3dd-6bcd-4a99-8ff0-b72843d143b8",
"eventOwnerOrganizationId": "a51aa87f-2567-490e-8a93-00618f0cc3de",
"eventOwnerMemberId": "83ac20dc-ca4d-4534-a8f5-61ce0934fe71",
"eventTime": "2023-03-21T13:25:35.5909223Z"
}
```
# Package sent
Source: https://docs.iinkedsign.com/v4/webhooks/events/package-sent
Fired when a package transitions from `select`, `add`, or `draft` state to `open`.
* This event can be triggered from `packages/add`, `packages/update`, and `packages/send` depending on the current state of the package.
* We recommend you use this event over `package_send` event for most workflows.
## Example
```json Payload theme={null}
{
"packageId": "ea24f722-3535-4869-8afc-dc6f2ee585b7",
"externalData": null,
"action": "package_sent",
"eventId": "d5f4a3dd-6bcd-4a99-8ff0-b72843d143b8",
"eventOwnerOrganizationId": "a51aa87f-2567-490e-8a93-00618f0cc3de",
"eventOwnerMemberId": "83ac20dc-ca4d-4534-a8f5-61ce0934fe71",
"eventTime": "2023-03-21T13:25:35.5909223Z"
}
```
# Package update
Source: https://docs.iinkedsign.com/v4/webhooks/events/package-update
Fired when an existing package is updated.
This event is only triggered on a successful call to `packages/update`.
## Example
```json Payload theme={null}
{
"packageId": "ea24f722-3535-4869-8afc-dc6f2ee585b7",
"externalData": null,
"action": "package_update",
"eventId": "d002627a-b623-424c-af2e-d5c25f78e84d",
"eventOwnerOrganizationId": "a51aa87f-2567-490e-8a93-00618f0cc3de",
"eventOwnerMemberId": "83ac20dc-ca4d-4534-a8f5-61ce0934fe71",
"eventTime": "2023-03-21T13:33:16.7221085Z"
}
```
# Verification status
Source: https://docs.iinkedsign.com/v4/webhooks/events/verification-status
The verification status event gets sent when a verification has been **completed** or **failed** by a signer.
If continue is `true`, the signer's verification policy has allowed them to continue to the signing of the package or VSR even if they have failed their identity verification.
If the verification policy allows the signer 3 attempts and they fail all 3 times, you will receive failed, failed, failed\_reset/failed\_locked events.
## Example
```json Payload theme={null}
{
"verificationId": "a688e7c1-f3b1-4b16-9d2b-d09065a10ed9",
"packageId": "2dcb8021-c3fe-465c-bd6a-dcca3a43a2e9",
"signerId": "57af6e67-d9d6-4ac9-9744-17d1c895eb89",
"continue": true,
"state": "completed",
"action": "verification_status",
"eventId": "90de30c7-e248-4331-b814-5a4fa75e0c6f",
"eventTime": "2023-03-10T22:49:01.2500632Z"
}
```
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
# Video delete
Source: https://docs.iinkedsign.com/v4/webhooks/events/video-delete
Fired when a user deletes a video from a package.
## Example
```json Payload theme={null}
{
"packageId": "9c9107b7-2d7f-4275-93d8-851e915812dd",
"action": "video_delete",
"eventId": "a96026de-5777-4cc4-a346-f9ec8cbc94d1",
"eventOwnerOrganizationId": "a51aa87f-2567-490e-8a93-00618f0cc3de",
"eventOwnerMemberId": "83ac20dc-ca4d-4534-a8f5-61ce0934fe71",
"eventTime": "2023-03-21T14:54:02.003745Z"
}
```
# Setup webhooks
Source: https://docs.iinkedsign.com/v4/webhooks/setup
Learn how to set up webhooks to receive real-time notifications about events in your account.
## Subscribe to webhooks
To receive real-time notifications about events in your account, you can set up webhooks. Webhooks allow your application to be notified when specific events occur, such as document signing or verification completion.
First, create an endpoint in your application that can receive HTTP POST requests. This endpoint will handle incoming webhook notifications.
Make sure your endpoint is publicly accessible and can handle incoming POST requests. It must also have a valid SSL certificate (HTTPS).
Next, register your webhook endpoint by providing the URL of your endpoint.
You can register your webhook endpoint by calling `events/endpoints/set` or within the iinked Sign web application under `Settings > Integrations > Endpoints`.
Optionally, update your webhook endpoint to authenticate requests using a secret token. This helps ensure that incoming requests are from the iinked Sign platform.
## Create endpoint via iinked Sign
You can manually configure your webhook endpoint within the iinked Sign platform. To do this, navigate to `Settings > Integrations > Endpoints` in the web application.
From there, you can add one or more endpoints by providing the URL of your webhook endpoint.
## Create endpoint via API
To help streamline the process of setting up webhooks, you can use the `events/endpoints/set` endpoint to register your webhook URL.
When called with OAuth authorization, this endpoint is useful to create, update, or delete a webhook endpoint for the users account, overwriting any existing endpoint associated to your OAuth client ID.
The endpoint will automatically be named after your application name as defined when registering your client ID.
### Request
```http Request theme={null}
POST /events/endpoints/set
{
"url": "https://example.com/your-webhook-endpoint",
}
```
### Body
A friendly name for your webhook endpoint.
The publicly accessible URL of your webhook endpoint. It must use HTTPS and have a valid SSL certificate.
Set to true to delete the specified webhook endpoint.
### Response
```http Response theme={null}
200 OK
{
"endpoint": {
"eventEndpointId": "e7b8f9c2-3d4a-4b5c-8e9f-1a2b3c4d5e6f",
"name": "My Webhook Endpoint",
"url": "https://example.com/your-webhook-endpoint",
"secret": "your-secret-token"
}
}
```
Details of the registered webhook endpoint.
Unique identifier for the webhook endpoint.
Friendly name for the webhook endpoint.
The URL of the webhook endpoint.
The secret token used for authenticating webhook requests.
## Verify webhooks
To ensure that incoming webhook requests are from iinked Sign, you can authenticate them using a secret token. When you register your webhook endpoint, a secret token is generated and included in the response.
All notifications will include a X-Syngrafii-Signature header that you can use to authenticate each callback.
```http theme={null}
X-Syngrafii-Signature: 4d3nJjEP4JJXZBGZROEQKQr4w3E=
```
You can re-compute the signature by using the endpoint secret token to compute a HMAC-SHA256 hash of the endpoint URL concatenated with the raw JSON content. The URL must match exactly including case and any trailing slashes.
```javascript theme={null}
app.use(express.json({
verify: (req, res, buf) => {
req.rawBody = buf;
}
}));
function verifySignature(req) {
const url = process.env.WEBHOOK_ENDPOINT; // iinked Sign Endpoint URL (must match exactly)
const secret = process.env.WEBHOOK_SECRET; // iinked Sign Endpoint Secret token
const signatureBase64 = req.headers['x-syngrafii-signature']; // iinked Sign Signature (Node.js header names are lowercased)
const rawBody = req.rawBody; // Raw body buffer (set in the express.json verify function)
if (!url || !secret || !signatureBase64 || !rawBody) return false;
const signatureBuff = Buffer.from(signatureBase64, 'base64'); // Convert base64 to bytes
const secretBuff = Buffer.from(secret, 'utf8'); // Convert secret to bytes (use utf8, do not use hex)
const json = rawBody.toString('utf8'); // Convert rawBody buffer to string
const dataBuff = Buffer.from(url + json, 'utf8'); // Convert url + json to bytes
const hmac = crypto.createHmac('sha256', secretBuff);
const dataSignature = hmac.update(dataBuff).digest();
return crypto.timingSafeEqual(signatureBuff, dataSignature);
}
```
```C# theme={null}
async Task VerifySignature()
{
var url = Environment.GetEnvironmentVariable("WEBHOOK_ENDPOINT"); // iinked Sign Endpoint URL (must match exactly)
var secret = Environment.GetEnvironmentVariable("WEBHOOK_SECRET"); // iinked Sign Endpoint Secret token
var signatureBase64 = Request.Headers.GetValues("X-Syngrafii-Signature").FirstOrDefault(); // iinked Sign Signature
var json = await Request.Content.ReadAsStringAsync(); // Unformatted JSON content
if (string.IsNullOrEmpty(url) || string.IsNullOrEmpty(secret) || string.IsNullOrEmpty(signatureBase64) || string.IsNullOrEmpty(json)) return false;
var signatureBuff = Convert.FromBase64String(signatureBase64); // Convert base64 to bytes
var secretBuff = Encoding.UTF8.GetBytes(secret); // Convert secret to bytes (use utf8)
var dataBuff = Encoding.UTF8.GetBytes(url + json); // Convert url + json to bytes
var hmac = new HMACSHA256(secretBuff);
var hash = hmac.ComputeHash(dataBuff);
return hash.SequenceEqual(signatureBuff);
}
```
If your server-side platform automatically deserializes the JSON content, you will have to add a handler to the request pipeline to perform authentication of the event notification content before deserialization occurs or as in the example above read the request content directly and manually deserialize the JSON afterwards.
This is because the signature is computed using the raw JSON content as it was sent and any changes to the content such as whitespace formatting or property ordering will result in a different hash value.
# CAC values
Source: https://docs.iinkedsign.com/v4/reference/package-options/package-options-cac
```json theme={null}
{
"options": {
"cac": "document_all"
}
}
```
| Value | Description |
| :-------------- | :---------------------------------- |
| document\_all | Append to all documents in package |
| document\_first | Append to first document in package |
| document\_last | Append to last document in package |
# Mark types
Source: https://docs.iinkedsign.com/v4/reference/package-options/package-options-default-mark
```json theme={null}
{
"options": {
"defaultMark": "click_to_sign"
}
}
```
| Value | Description |
| :-------------- | :---------- |
| touch\_to\_sign | iink It |
| type\_to\_sign | Type It |
| click\_to\_sign | Accept It |
# Form flattening
Source: https://docs.iinkedsign.com/v4/reference/package-options/package-options-form-flattening
```json theme={null}
{
"options": {
"formFlattening": "none"
}
}
```
| Value | Description |
| :----- | :----------------------------------- |
| none | Do not flatten fields |
| filled | Flatten only fields filled by signer |
| all | Flatten all fields `default` |
# Unused tags
Source: https://docs.iinkedsign.com/v4/reference/package-options/package-options-template-unused-signer-tags
```json theme={null}
{
"options": {
"templateUnusedSignerTags": "remove"
}
}
```
| Value | Description |
| :----- | :------------------------------- |
| keep | Leave unused tags in document |
| hide | Move unused tags to hidden layer |
| remove | Remove unused tags `default` |
# Verification options
Source: https://docs.iinkedsign.com/v4/reference/package-options/verification-options
The policy ID of the custom Identity Verification Policy to use during signer identity verification. (Custom IDV policies currently must be created by our Support Team for your organization.)
The code of one of our standard Identity Verification Policy to use during signer identity verification.
| Policy Code | Pass-To-Sign | Region | Retries |
| :--------------------------------------- | :----------: | :----: | :-----: |
| trulioo3\_document | false | Any | 2 |
| trulioo3\_document\_required | true | Any | 2 |
| trulioo3\_document\_ca\_strict | false | CA | 2 |
| trulioo3\_document\_ca\_strict\_required | true | CA | 2 |
**Pass-To-Sign** indicates whether the signer must successfully complete identity verification before they can sign their documents.
# Recipient
Source: https://docs.iinkedsign.com/v4/reference/recipients/recipient
Unique identifier for the recipient.
Identifier of the package the recipient belongs to.
Creation time for the recipient record (ISO 8601).
Last update time for the recipient record (ISO 8601).
Recipient first name.
Recipient last name.
Recipient email address.
Recipient mobile number country code. (optional)
Original recipient mobile number provided.
Normalized recipient mobile number. (optional)
Recipient locale. (optional)
Recipient type.
Current state of the recipient record.
# Recipient types
Source: https://docs.iinkedsign.com/v4/reference/recipients/recipient-types
| Value | Description |
| :---- | :------------------------------------------------------------- |
| cc | Recipient that will be **CC** on package email notifications. |
| bcc | Recipient that will be **BCC** on package email notifications. |
# Signer
Source: https://docs.iinkedsign.com/v4/reference/signers/signer
Unique identifier for the signer.
Package identifier the signer belongs to.
Member identifier when the signer is an organization member. (optional)
Tag associated with the signer. (optional)
When the signer record was created (ISO 8601).
Time the signer declined (if applicable).
Last update time for the signer record.
Signing order index.
Locale for the signer. (optional)
Set to `true` if signer requires CAC signing.
Set to `true` if signer requires identity verification before signing.
First name of the signer.
Last name of the signer.
Email address for the signer.
Country code for the mobile number. (optional)
Original mobile number provided.
Normalized mobile number (E.164) when available.
Message left by the signer when declining (if any).
Reason code for decline (if applicable).
Set to `true` if this signer is next in signing order across the package.
Number of revisions the signer has signed.
Number of revisions assigned to the signer.
Role of the signer.
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
Type of signer.
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
Current state of the signer.
| Value | Description |
| :------- | :-------------------------------------------------------------- |
| active | Signer that is actively participating in the signing process. |
| declined | Signer that has declined to participate in the signing process. |
| deleted | Signer that has been removed from the package. |
Signer verification status. (if any)
Identifier for the verification record.
Signer identifier associated with this verification.
Set to `true` if the signer is can sign documents after verification.
Set to `true` if the signer can join VSR after verification.
Set to `true` if the signer may retry verification on failure.
Set to `true` if the signer has successfully signed after verification.
Set to `true` if the verification is currently locked.
Number of verification attempts made.
Number of errors encountered during verification.
Whether the verification flow should continue to next step.
Whether to continue the flow when verification errors occur.
Current verification error code (if any).
Current state of the verification.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
# Signer roles
Source: https://docs.iinkedsign.com/v4/reference/signers/signer-roles
| Value | Description |
| :----- | :---------------------------------------------------------------------- |
| signer | Signer |
| guest | Guest of VSR or In Person signing that is not a signer of any documents |
| host | Host of VSR or In Person signing |
# Signer types
Source: https://docs.iinkedsign.com/v4/reference/signers/signer-types
| Value | Description |
| :----- | :------------------------------------------------------------------------ |
| signer | Signer |
| guest | Signer that was added by the host during VSR or In Person signing session |
# Template types
Source: https://docs.iinkedsign.com/v4/reference/templates/template-types
| Value | Description |
| -------------- | ------------------ |
| template | Standard template. |
| auto\_template | Auto template. |
# Document types
Source: https://docs.iinkedsign.com/v4/reference/verifications/verification-document-types
| Key | Description |
| ---------------- | ---------------------------------------------------- |
| drivers\_license | Driver's License |
| health\_card | Health Card |
| identity\_card | Identity Card |
| military\_id | Military ID |
| other | Other (Returned when document type detection failed) |
| passport | Passport |
| resident\_card | Resident Card |
| travel\_document | Travel Document |
| visa | Visa |
| voter\_id | Voter ID |
# Field types
Source: https://docs.iinkedsign.com/v4/reference/verifications/verification-field-types
| Key | Label |
| -------------------------- | ----------------- |
| address | Address |
| city | City |
| credit\_details\_trulioo | Credit |
| dob\_day | DOB Day |
| dob\_month | DOB Month |
| dob\_year | DOB Year |
| document\_address | Address |
| document\_address\_2 | Address 2 |
| document\_city | City |
| document\_class | Class |
| document\_country\_code | Country |
| document\_dob\_day | Birth Day |
| document\_dob\_month | Birth Month |
| document\_dob\_year | Birth Year |
| document\_doe\_day | Expiry Day |
| document\_doe\_month | Expiry Month |
| document\_doe\_year | Expiry Year |
| document\_doi\_day | Issue Day |
| document\_doi\_month | Issue Month |
| document\_doi\_year | Issue Year |
| document\_first\_name | First Name |
| document\_full\_name | Full Name |
| document\_gender | Gender |
| document\_issuer | Issuer |
| document\_last\_name | Last Name |
| document\_middle\_name | Middle Name |
| document\_nationality | Nationality |
| document\_number | Document Number |
| document\_number\_2 | Document Number 2 |
| document\_place\_of\_birth | Place of Birth |
| document\_postal\_code | Postal Code |
| document\_subdivision | Province |
| document\_type | Document Type |
| email | Email |
| first\_name | First Name |
| full\_name | Full Name |
| last\_name | Last Name |
| last\_name\_other | Last Name (Other) |
| middle\_name | Middle Name |
| mobile\_number | Mobile Number |
| postal\_code | Postal Code |
| prefix | Prefix |
| street\_name | Street Name |
| street\_number | Street Number |
| street\_type | Street Type |
| subdivision | Province |
| unit\_number | Unit Number |
# Image types
Source: https://docs.iinkedsign.com/v4/reference/verifications/verification-image-types
| Key | Description |
| ----------- | ------------------------------------------------------------------------------ |
| live\_photo | Selfie of signer captured during live selfie process of document verification. |
| front | Front image of document captured during document verification. |
| back | Back image of document captured during document verification. |
| passport | Image of passport captured during document verification. |
# Result states
Source: https://docs.iinkedsign.com/v4/reference/verifications/verification-result-states
| State | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| processing | Verification result is currently being processed. |
| collected | Verification input fields have been successfully collected. The input fields will be validated by a subsequent verification step. |
| passed | Verification result has been processed and has passed. |
| failed | Verification result has been processed and has failed. |
| error | An **error** occurred while processing the verification. Check the error field for reason. |
# Result types
Source: https://docs.iinkedsign.com/v4/reference/verifications/verification-result-types
| Value | Description |
| -------- | ------------------------------------- |
| identity | Identity verification. |
| kba | Knowledge based answers verification. |
| document | Document verification. |
# Score types
Source: https://docs.iinkedsign.com/v4/reference/verifications/verification-score-types
| Value | Description | Version |
| ---------------------------------------- | ---------------------------------- | ------- |
| credit\_fraud | Fraud Check | |
| credit\_six\_month\_residency | Six Month Residency Check | |
| credit\_three\_year | Three Year Credit Check | |
| document | Identification | |
| document\_confidence | Document Confidence | 3.5 |
| document\_live\_photo\_liveness | Live Selfie Liveness Detection | |
| document\_live\_photo\_match | Live Selfie Matches Document Photo | 3.5 |
| identity | Identity | |
| kba | Knowledge Based Answers | |
| security\_check\_country | Country Match | |
| security\_check\_data | Data Crosscheck Analysis | |
| security\_check\_document\_type | Document Type Match | |
| security\_check\_features | Security Feature Analysis | |
| security\_check\_live\_photo | Live Selfie Match | |
| security\_check\_session | Session Analysis | 3.5 |
| security\_check\_tampering | Tampering Analysis | |
| security\_valid\_data | Data Format Analysis | |
| security\_valid\_document | Data Analysis | |
| security\_valid\_document\_type | Document Type Analysis | |
| security\_valid\_machine\_readable\_data | Machine Readable Data Analysis | |
| security\_valid\_ocr | OCR Analysis | 3.5 |
| security\_valid\_photos | Photo Analysis | 3.5 |
# Verification states
Source: https://docs.iinkedsign.com/v4/reference/verifications/verification-states
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
# Verification
Source: https://docs.iinkedsign.com/v4/reference/verifications/verification-view
Unique identifier for the verification.
Unique identifier for the organization.
Unique identifier for the package.
Package name.
Package type.
| Value | Description |
| :------------------- | :---------------------------------------------------------------------------------------------- |
| concurrent | **Concurrent**: Allows multiple signers to sign the document simultaneously. |
| Sequential | **Sequential**: Requires signers to sign the document in a specific order. |
| Counterpart | **Group Send**: Enables group signing, where all signers receive the document at the same time. |
| video\_closing\_room | **Video Signing Room**: A virtual room for signing documents via video conference. |
| Live Session | **In Person**: An in-person signing session with all parties present. |
Even though the signing workflow names have evolved, the constants used to identify them have remained the same.
The package type constants are case-sensitive. Ensure that you use the exact casing as shown in the table above when specifying package types in your API requests.
Unique identifier for the signer.
Signer's first name.
Signer's last name.
Signer's email address.
Time verification record was created.
Time verification record was last updated.
Two-character ISO-3166-1 country code.
Current number of failed attempts.
Current number of errors.
Set to `true` if the signer is allowed to continue with signing documents after failing identity verification.
Error code if verification is in a failed state (if any).
The current state of the signer's identity verification process.
| State | Description |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| not\_started | Signer has not started identity verification. |
| start | Signer is on start step. |
| consent | Signer is on consent step. |
| consent\_processing | Server is processing consent. |
| identity | Signer is on identity verification step. |
| identity\_processing | Server is processing identity verification. |
| kba | Signer is on KBA verification step. |
| kba\_processing | Server is processing KBA verification. |
| document | Signer is on document verification step. |
| document\_processing | Server is processing document verification. |
| end | Server is finalizing identity verification result. |
| passed | Identity verification has passed. |
| failed | Identity verification has failed and can be retried by signer. |
| failed\_reset | Identity verification has failed and must be reset by package owner for signer to retry. |
| failed\_locked | Identity verification has failed and is now locked and can no longer be reset by package owner. |
| error | A server error has occurred and can be retried by signer. |
| error\_reset | A server error has occurred and must be reset by package owner for signer to retry. |
| error\_locked | A server error has occurred and can no longer be reset by package owner. |
| cancelled | Identity verification has been cancelled. |
| cancelled\_reset | Identity verification has been cancelled due to package owner resetting signer's verification. |
| invalid | Identity verification is in an invalid state and cannot be processed. |
Results of the verification record.
Unique identifier for the verification result.
Unique identifier for the verification.
Time verification result record was created.
Set to `true` if the verification result has passed.
Set to `true` if the verification result has failed and the signer can no longer retry.
Set to `true` if the verification result has expired and can no longer be completed by signer.
Dictionary of verification results and their pass/fail score.
Score mapping: -1 = missing, 0 = failed/no match, 50 = partial match, 100 = passed.
| Value | Description | Version |
| ---------------------------------------- | ---------------------------------- | ------- |
| credit\_fraud | Fraud Check | |
| credit\_six\_month\_residency | Six Month Residency Check | |
| credit\_three\_year | Three Year Credit Check | |
| document | Identification | |
| document\_confidence | Document Confidence | 3.5 |
| document\_live\_photo\_liveness | Live Selfie Liveness Detection | |
| document\_live\_photo\_match | Live Selfie Matches Document Photo | 3.5 |
| identity | Identity | |
| kba | Knowledge Based Answers | |
| security\_check\_country | Country Match | |
| security\_check\_data | Data Crosscheck Analysis | |
| security\_check\_document\_type | Document Type Match | |
| security\_check\_features | Security Feature Analysis | |
| security\_check\_live\_photo | Live Selfie Match | |
| security\_check\_session | Session Analysis | 3.5 |
| security\_check\_tampering | Tampering Analysis | |
| security\_valid\_data | Data Format Analysis | |
| security\_valid\_document | Data Analysis | |
| security\_valid\_document\_type | Document Type Analysis | |
| security\_valid\_machine\_readable\_data | Machine Readable Data Analysis | |
| security\_valid\_ocr | OCR Analysis | 3.5 |
| security\_valid\_photos | Photo Analysis | 3.5 |
Dictionary of messages associated with each score in `scores`.
Dictionary of verification input fields and their pass/fail score.
Dictionary of verification input fields and their values used to generate the results.
| Key | Label |
| -------------------------- | ----------------- |
| address | Address |
| city | City |
| credit\_details\_trulioo | Credit |
| dob\_day | DOB Day |
| dob\_month | DOB Month |
| dob\_year | DOB Year |
| document\_address | Address |
| document\_address\_2 | Address 2 |
| document\_city | City |
| document\_class | Class |
| document\_country\_code | Country |
| document\_dob\_day | Birth Day |
| document\_dob\_month | Birth Month |
| document\_dob\_year | Birth Year |
| document\_doe\_day | Expiry Day |
| document\_doe\_month | Expiry Month |
| document\_doe\_year | Expiry Year |
| document\_doi\_day | Issue Day |
| document\_doi\_month | Issue Month |
| document\_doi\_year | Issue Year |
| document\_first\_name | First Name |
| document\_full\_name | Full Name |
| document\_gender | Gender |
| document\_issuer | Issuer |
| document\_last\_name | Last Name |
| document\_middle\_name | Middle Name |
| document\_nationality | Nationality |
| document\_number | Document Number |
| document\_number\_2 | Document Number 2 |
| document\_place\_of\_birth | Place of Birth |
| document\_postal\_code | Postal Code |
| document\_subdivision | Province |
| document\_type | Document Type |
| email | Email |
| first\_name | First Name |
| full\_name | Full Name |
| last\_name | Last Name |
| last\_name\_other | Last Name (Other) |
| middle\_name | Middle Name |
| mobile\_number | Mobile Number |
| postal\_code | Postal Code |
| prefix | Prefix |
| street\_name | Street Name |
| street\_number | Street Number |
| street\_type | Street Type |
| subdivision | Province |
| unit\_number | Unit Number |
Dictionary of any additional fields and their values generated while processing the results.
May contain an error code if verification result is in a failed state.
The type of verification result.
| Value | Description |
| -------- | ------------------------------------- |
| identity | Identity verification. |
| kba | Knowledge based answers verification. |
| document | Document verification. |
The state of the verification result.
| State | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| processing | Verification result is currently being processed. |
| collected | Verification input fields have been successfully collected. The input fields will be validated by a subsequent verification step. |
| passed | Verification result has been processed and has passed. |
| failed | Verification result has been processed and has failed. |
| error | An **error** occurred while processing the verification. Check the error field for reason. |
Documents associated with the verification result.
Unique identifier for the verification document.
Unique identifier for the verification.
Time verification document record was created.
Verification document type.
| Key | Description |
| ---------------- | ---------------------------------------------------- |
| drivers\_license | Driver's License |
| health\_card | Health Card |
| identity\_card | Identity Card |
| military\_id | Military ID |
| other | Other (Returned when document type detection failed) |
| passport | Passport |
| resident\_card | Resident Card |
| travel\_document | Travel Document |
| visa | Visa |
| voter\_id | Voter ID |
Verification document image type.
| Key | Description |
| ----------- | ------------------------------------------------------------------------------ |
| live\_photo | Selfie of signer captured during live selfie process of document verification. |
| front | Front image of document captured during document verification. |
| back | Back image of document captured during document verification. |
| passport | Image of passport captured during document verification. |
URL to download document or document image from.
Document URLs returned by the verification endpoint have a lifetime of 15 minutes.
As of `3.6` images now default to `WEBP` format. You can convert images to `JPEG` by appending the following query string parameter to end of the returned URL:
`&mimeType=image/jpeg`
# Verification document
Source: https://docs.iinkedsign.com/v4/reference/verifications/verification-view-document
Unique identifier for the verification document.
Unique identifier for the verification.
Time verification document record was created.
Verification document type.
| Key | Description |
| ---------------- | ---------------------------------------------------- |
| drivers\_license | Driver's License |
| health\_card | Health Card |
| identity\_card | Identity Card |
| military\_id | Military ID |
| other | Other (Returned when document type detection failed) |
| passport | Passport |
| resident\_card | Resident Card |
| travel\_document | Travel Document |
| visa | Visa |
| voter\_id | Voter ID |
Verification document image type.
| Key | Description |
| ----------- | ------------------------------------------------------------------------------ |
| live\_photo | Selfie of signer captured during live selfie process of document verification. |
| front | Front image of document captured during document verification. |
| back | Back image of document captured during document verification. |
| passport | Image of passport captured during document verification. |
URL to download document or document image from.
Document URLs returned by the verification endpoint have a lifetime of 15 minutes.
As of `3.6` images now default to `WEBP` format. You can convert images to `JPEG` by appending the following query string parameter to end of the returned URL:
`&mimeType=image/jpeg`
# Verification result
Source: https://docs.iinkedsign.com/v4/reference/verifications/verification-view-result
Unique identifier for the verification result.
Unique identifier for the verification.
Time verification result record was created.
Set to `true` if the verification result has passed.
Set to `true` if the verification result has failed and the signer can no longer retry.
Set to `true` if the verification result has expired and can no longer be completed by signer.
Dictionary of verification results and their pass/fail score.
Score mapping: -1 = missing, 0 = failed/no match, 50 = partial match, 100 = passed.
| Value | Description | Version |
| ---------------------------------------- | ---------------------------------- | ------- |
| credit\_fraud | Fraud Check | |
| credit\_six\_month\_residency | Six Month Residency Check | |
| credit\_three\_year | Three Year Credit Check | |
| document | Identification | |
| document\_confidence | Document Confidence | 3.5 |
| document\_live\_photo\_liveness | Live Selfie Liveness Detection | |
| document\_live\_photo\_match | Live Selfie Matches Document Photo | 3.5 |
| identity | Identity | |
| kba | Knowledge Based Answers | |
| security\_check\_country | Country Match | |
| security\_check\_data | Data Crosscheck Analysis | |
| security\_check\_document\_type | Document Type Match | |
| security\_check\_features | Security Feature Analysis | |
| security\_check\_live\_photo | Live Selfie Match | |
| security\_check\_session | Session Analysis | 3.5 |
| security\_check\_tampering | Tampering Analysis | |
| security\_valid\_data | Data Format Analysis | |
| security\_valid\_document | Data Analysis | |
| security\_valid\_document\_type | Document Type Analysis | |
| security\_valid\_machine\_readable\_data | Machine Readable Data Analysis | |
| security\_valid\_ocr | OCR Analysis | 3.5 |
| security\_valid\_photos | Photo Analysis | 3.5 |
Dictionary of messages associated with each score in `scores`.
Dictionary of verification input fields and their pass/fail score.
Dictionary of verification input fields and their values used to generate the results.
| Key | Label |
| -------------------------- | ----------------- |
| address | Address |
| city | City |
| credit\_details\_trulioo | Credit |
| dob\_day | DOB Day |
| dob\_month | DOB Month |
| dob\_year | DOB Year |
| document\_address | Address |
| document\_address\_2 | Address 2 |
| document\_city | City |
| document\_class | Class |
| document\_country\_code | Country |
| document\_dob\_day | Birth Day |
| document\_dob\_month | Birth Month |
| document\_dob\_year | Birth Year |
| document\_doe\_day | Expiry Day |
| document\_doe\_month | Expiry Month |
| document\_doe\_year | Expiry Year |
| document\_doi\_day | Issue Day |
| document\_doi\_month | Issue Month |
| document\_doi\_year | Issue Year |
| document\_first\_name | First Name |
| document\_full\_name | Full Name |
| document\_gender | Gender |
| document\_issuer | Issuer |
| document\_last\_name | Last Name |
| document\_middle\_name | Middle Name |
| document\_nationality | Nationality |
| document\_number | Document Number |
| document\_number\_2 | Document Number 2 |
| document\_place\_of\_birth | Place of Birth |
| document\_postal\_code | Postal Code |
| document\_subdivision | Province |
| document\_type | Document Type |
| email | Email |
| first\_name | First Name |
| full\_name | Full Name |
| last\_name | Last Name |
| last\_name\_other | Last Name (Other) |
| middle\_name | Middle Name |
| mobile\_number | Mobile Number |
| postal\_code | Postal Code |
| prefix | Prefix |
| street\_name | Street Name |
| street\_number | Street Number |
| street\_type | Street Type |
| subdivision | Province |
| unit\_number | Unit Number |
Dictionary of any additional fields and their values generated while processing the results.
May contain an error code if verification result is in a failed state.
The type of verification result.
| Value | Description |
| -------- | ------------------------------------- |
| identity | Identity verification. |
| kba | Knowledge based answers verification. |
| document | Document verification. |
The state of the verification result.
| State | Description |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
| processing | Verification result is currently being processed. |
| collected | Verification input fields have been successfully collected. The input fields will be validated by a subsequent verification step. |
| passed | Verification result has been processed and has passed. |
| failed | Verification result has been processed and has failed. |
| error | An **error** occurred while processing the verification. Check the error field for reason. |
Documents associated with the verification result.
Unique identifier for the verification document.
Unique identifier for the verification.
Time verification document record was created.
Verification document type.
| Key | Description |
| ---------------- | ---------------------------------------------------- |
| drivers\_license | Driver's License |
| health\_card | Health Card |
| identity\_card | Identity Card |
| military\_id | Military ID |
| other | Other (Returned when document type detection failed) |
| passport | Passport |
| resident\_card | Resident Card |
| travel\_document | Travel Document |
| visa | Visa |
| voter\_id | Voter ID |
Verification document image type.
| Key | Description |
| ----------- | ------------------------------------------------------------------------------ |
| live\_photo | Selfie of signer captured during live selfie process of document verification. |
| front | Front image of document captured during document verification. |
| back | Back image of document captured during document verification. |
| passport | Image of passport captured during document verification. |
URL to download document or document image from.
Document URLs returned by the verification endpoint have a lifetime of 15 minutes.
As of `3.6` images now default to `WEBP` format. You can convert images to `JPEG` by appending the following query string parameter to end of the returned URL:
`&mimeType=image/jpeg`
# Updates
Source: https://docs.iinkedsign.com/v4/updates
## Consent and digital signatures
Release 4.2 adds package consent controls, localized custom consent notices, returned consent records, and digital signature provider configuration.
* Configure signing and Video Signing Room consent with [`consentOptions`](/v4/reference/package-options/consent-options).
* Add localized consent text with the `notices` package option.
* Configure qualified electronic signature providers with [`digitalSignatures`](/v4/reference/package-options/digital-signature-options) and follow the [QES guide](/v4/guides/sign-qes).
* Read consent history from the package response's [`consents`](/v4/reference/packages/consent) collection.
* See the [Package options guide](/v4/guides/package-options) for valid configuration combinations and examples.
## New API docs site launched
We are excited to announce the launch of our new API documentation site! The new site features a modern design, improved navigation, and enhanced search capabilities to help you find the information you need quickly and easily.
### Improvements
* All of our existing guides have been rewritten to focus on specific integration challenges so teams can move from setup to production faster.
* New guides on template tagging and webhooks have been added to help you get the most out of our platform.
* The API reference has been restructured to provide clearer organization of endpoints and parameters.