NotaryLive API - eSign Creation

Creating an eSign Order

Below is an example request to create an eSign order:

curl -X POST -k "https://notarylive.com/api/v1/esign/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{
        "document_urls":["https://pdfobject.com/pdf/sample.pdf"], 
        "participants": [{
            "email": "john.doe@notarylive.com", 
            "first_name": "Johnny", 
            "last_name": "Doe"}]
        }'

A successful request will generate the following response:

{
    "success":1,
    "link_to_order":"https://notarylive.com/tu/es?uid={user_identifier}&eid={unique_esign_identifier}"
}

If that user is not a guest, they will be required to login to their account to proceed with this order. All webhooks and status emails will still trigger for non-guest users.

Validation Failures

Invalid credentials will return a 401 response with the message: HTTP/1.0 401 Unauthorized

Invalid or missing payload data will return a 400 HTTP response with a JSON body containing success = 0 as well as an array of errors containing both a standardized error code, as well as a human-readable description of what caused the error.

If you continue having issues, please take a look at our troubleshooting guide.

curl -X POST -k "https://notarylive.com/api/v1/esign/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{
        "participants": [{
            "email": "john.doe@notarylive.com", 
            "first_name": "Johnny", 
            "last_name": "Doe"}]
        }'

{
    "success": 0,
    "errors": [{
        "code": "validation_failed",
        "message":"Either document_files, document_urls, or template_id must be provided.""
    }]
}

Attaching Documents

via Document URL

To upload a document to eSign, pass in a comma-separated list of document urls as shown below:

curl -X POST -k "https://notarylive.com/api/v1/esign/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{
        "document_urls":[
            "https://pdfobject.com/pdf/sample.pdf",
            "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"
        ], 
        "participants": [{
            "email": "john.doe@notarylive.com", 
            "first_name": "Johnny", 
            "last_name": "Doe"}]
        }'

Each file will be attached as a separate document that the signer can eSign within the same session.

via Direct File Upload

In the direct file upload approach, the file must exist on the same server infrastructure as where the API request is originating from. You will then reference the full file path to the document within the API call:

curl -X POST "https://notarylive.com/api/v1/esign/create" \
    -u 'api_test_user:api_test_key' \
    -H 'Content-Type: multipart/form-data' \
    -F "document_files[0]=@/path/to/document_1.pdf" \
    -F "document_files[1]=@/path/to/document_2.pdf" \
    -F "participants[0][first_name]=Johnny" \
    -F "participants[0][last_name]=Doe" \
    -F "participants[0][email]=john.doe@notarylive.com"

Please note: The API will fail with an error message if the file does not exist or the full file path is not specified correctly.

Please note: API calls including large documents or multiple documents will take longer to process than API calls with smaller filesize documents.

Adding Participants

You can add signers to the request in the eSign API by using the participants parameter. The participants parameter accepts an array of objects representing participants, where the first signer will always be treated as the primary signer. Each participant object must contain the following parameters:

• email - The email address of the participant
• first_name - The first name of the participant
• last_name - The last name of the participant

For more information on the validation rules for participant names and emails, please click here.

You can add multiple signers types to the request in this manner:

curl -X POST -k "https://notarylive.com/api/v1/esign/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{
        "document_urls":["https://pdfobject.com/pdf/sample.pdf"], 
        "participants": [{
            "email": "john.doe@notarylive.com", 
            "first_name": "Johnny", 
            "last_name": "Doe"
        }, {
            "email":"jane.doe@notarylive.com",
            "last_name":"Doe",
            "first_name":"Jane"
        }]
    }'

Using Templates

Templates allow you to reuse the same type of document for multiple eSign orders, but with dynamic fields that are unique to the information about that specific customer. You can create templates from the dashboard and use the template ID while creating an eSign order.

curl -X POST -k "https://notarylive.com/api/v1/esign/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{
        "template_id":"((template_id))", 
        "participants": [{
            "email": "john.doe@notarylive.com", 
            "first_name": "Johnny", 
            "last_name": "Doe"}]
        }'

Please note: If you provide template_id you can still provide document_urls or document_files to include additional non-templated documents. This will append the templated documents to the end of the list.

Please note: Using the test credentials (-u 'api_test_user:api_test_key') in combination with template_id will result in an error as your template is tied to your account, not the universal testing account. For Business Premier accounts, you can generate your own eSign sandbox keys in your NotaryLive dashboard under the eSign API tab.

Document Dynamic Fields

When using an api template, you can also provide values for templated fields. These fields are placeholders in the document that are replaced with the values you provide. You can provide these values using the templated_documents_fields parameter.

Let's say you have an api template with the first_name, last_name, and country fields on the document. first_name and last_name being on the first page and country being on the second page. You can provide the values for these fields as shown below:

curl -X POST "https://notarylive.com/api/v1/esign/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{
        "templated_documents_fields":[{
            "file_id":"((file_id))",
            "fields":[
                [
                    ["first_name","Johnny"],
                    ["last_name","Doe"]
                ],
                [
                    ["country","USA"]
                ]
            ]
        }],
        "template_id":"((template_id))",
        "participants": [{
            "email": "john.doe@notarylive.com", 
            "first_name": "Johnny", 
            "last_name": "Doe"}]
        }'

Once the eSign order is created, the first_name, last_name and country fields will be replaced in this example. The fields you create in your template will be replaced with the values you provide in the API call as long as they're found in the document.

The field names should be unique within the document. If you provide the same field name multiple times, the first value provided will be used. If you provide a value for a field that doesn't exist in the document, it will be ignored.

Please note: The file_id is the ID of the document in the template. You can get the file_id from the template details page in the dashboard.

Please note: Currently, applying templates and using templated fields are limited to templates with the type api. You can create an api template from the dashboard.

Choosing How You Receive Files Back

By default, NotaryLive will send the eSigned documents back to you as a url link to a remote file within the body of a webhook event. If you would rather receive the file itself in the webhook event, you will need to set the receive_files_as_attachments parameter in your initial API call to 1. Below is an example of what that would look like:

curl -X POST -k "https://notarylive.com/api/v1/esign/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{
        "document_urls":["https://pdfobject.com/pdf/sample.pdf"], 
        "receive_files_as_attachments": 1,
        "participants": [{
            "email": "john.doe@notarylive.com", 
            "first_name": "Johnny", 
            "last_name": "Doe"}]
        }'

Please note: NotaryLive webhook events by default are sent as Content-Type: application/json. However, when receive_files_as_attachments is 1, NotaryLive webhooks will always be sent with Content-Type: multipart/form-data. The shape of the response will also change slightly between the two versions. Below are example webhook responses with receive_files_as_attachments enabled and disabled:

receive_files_as_attachments disabled:

{
    "event": "esign_complete",
    "nl_esign_id": "ES257",
    "their_order_id": "((internal_order_id))", 
    "links_to_documents": [
        "https://esigned-files.../document1.pdf",
        "https://esigned-files.../document2.pdf"
    ]
}

receive_files_as_attachments enabled:

{
    "response": {
        "event":"esign_complete","nl_order_id":"ES257","their_order_id":"((internal_order_id))"
    }
}

When receive_files_as_attachments is enabled, the files will be attached to the webhook POST in the following file format:

document-1
document-2
document-3
etc

Please note: The original filenames of your documents are preserved after notarization. The document-1, etc format is only used for fetching the resultant files from the webhook.

Please consult the documentation for your server-side language of choice on how to download and store the file from the HTTP POST when receive_files_as_attachments is enabled.

Webhook Events

The following webhook events are sent during the eSign order lifecycle:

{
    "event": "esign_created",
    "nl_esign_id": "notarylive_esign_id",
    "their_order_id": "your_company_order_id",
}

{
    "event": "order_canceled",
    "nl_esign_id": "notarylive_esign_id",
    "their_order_id": "your_company_order_id",
}

{
    "event": "esign_complete",
    "nl_esign_id": "notarylive_esign_id",
    "their_order_id": "your_company_order_id",
    "links_to_documents": [
        "https://esigned-files.../document1.pdf",
        "https://esigned-files.../document2.pdf"
    ]
}

Please note: the links_to_documents will only be accessible for 30 minutes when you move to the production API. Please have a plan in place to download and store this document on your own infrastructure if you plan on needing access to this document for more than 30 minutes. If you would rather receive the files back directly, instead of as remote urls, please click here.

Webhook Security

All webhook messages sent by NotaryLive are sent over HTTPS to ensure messages are encrypted in transit.

While HMAC verification is a common security measure, integrating partners have had difficulty replicating the HMAC signature, especially when webhooks include attached media or when the Content-Type isn't application/json. For this reason, NotaryLive does not support HMAC signing for webhooks.

Instead, we recommend treating webhooks as simple notifications that the session order status has changed.

Validation Rules

The following are the validation rules for all arguments within the order creation API call:

Copyright © 2026, NotaryLive.com