NotaryLive API - Order Creation

The Sandbox Environment

The NotaryLive API sandbox credentials expose limited functionality to the NotaryLive API and are intended for testing purposes. In the sandbox environment, payment processing and the notarial session itself are disabled. Please note: The API examples shown in this documentation are all working examples. You can copy any of the curl calls below into your terminal to get started right away with sandbox testing!

Creating a Session Order

Below is an example request to create a customer order:

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create -d "customer_fname=John&customer_lname=Doe&customer_email=john.doe@notarylive.com&order_id=your_company_order_id"

A successful request will generate the following response:

{
  "success":1,
  "link_to_order":"https://notarylive.com/notarize/request-form?guest=true&oid=[ our unique identifier for the order ]"
}

If this email is already associated with a non-guest customer in our system, the returned url will reflect this:

{
  "success":1,
  "link_to_order":"https://notarylive.com/notarize/request-form?guest=false&oid=[ our unique identifier for the order ]"
}

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

Attaching Documents to the Order

via Document URL

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

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create \
-d "customer_fname=John&customer_lname=Doe&customer_email=john.doe@notarylive.com&order_id=your_company_order_id&doc_urls=\
  https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf,\
  https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"

Each file will be attached as a separate document, and all identity verification and notarization steps will occur with these documents within the same live session with the notary public.

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 --user api_test_user:api_test_key https://notarylive.com/api/order/create \
-F "customer_fname=Johnny" -F "customer_lname=Doe" \
-F "customer_email=john.doe@notarylive.com" \
-F "order_id=your_company_order_id" \
-F "document_1=@/folder1/folder2/folder3/file1.pdf" \
-F "document_2=@/folder1/folder2/folder3/file2.pdf"

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.

via Direct File Upload (many files)

The order creation API currently allows for up to four documents to be uploaded via the document_1, document_2, document_3, document_4 API parameters. If you need to upload more than 4 documents in a single customer order, you may do so via the documents parameter as an array of file paths:

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create \
-F "customer_fname=Johnny" -F "customer_lname=Doe" \
-F "customer_email=john.doe@notarylive.com" \
-F "order_id=your_company_order_id" \
-F "documents[]=@/folder1/folder2/folder3/file1.pdf" \
-F "documents[]=@/folder1/folder2/folder3/file2.pdf"

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

Troubleshooting Encoding Issues with Document Urls

Commas

Document urls that contain commas will not be uploaded via the API. If you need to submit document urls that contain commas, please replace the comma character with the percent-encoded equivalent %2C

Ampersands

If your document urls contain ampersands (&) and you are posting to the API via curl, the following API call will not successfully upload the document:

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create \
-d "customer_fname=John&customer_lname=Doe&customer_email=john.doe@notarylive.com&order_id=your_company_order_id&doc_urls=\
  https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf?param1=data1&param2=data2,\
  https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf?param1=dataA&param2=dataB"

Instead, you can convert the curl call to the following:

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create \
-d "customer_fname=John&customer_lname=Doe&customer_email=john.doe@notarylive.com&order_id=your_company_order_id" --data-urlencode "doc_urls=\
  https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf?param1=data1&param2=data2,\
  https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf?param1=dataA&param2=dataB"

Another option for dealing with ampersands is to replace the ampersand with the percent-encoded equivalent %26. This will then be converted back to '&' within the API. This solution is also an option for API integrations that use a tool other than curl.

Adding Participants to the Session

You can add signers to the request in the Session Order API by using the additional_signers parameter. The additional_signers parameter accepts a JSON string representing a list of additional signers to add to the request. Each signer object must contain the following parameters:

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

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

Here is an example of how to add a signer to the request:

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create -d "customer_fname=John&customer_lname=Doe&customer_email=john.doe@notarylive.com&order_id=your_company_order_id&additional_signers=[{\"first_name\":\"Jane\",\"last_name\":\"Doe\",\"email\":\"jane.doe@notarylive.com\"}]"

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

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create -d "customer_fname=John&customer_lname=Doe&customer_email=john.doe@notarylive.com&order_id=your_company_order_id&additional_signers=[{\"first_name\":\"Jane\",\"last_name\":\"Doe\",\"email\":\"jane.doe@notarylive.com\"},{\"first_name\":\"Jimmy\",\"last_name\":\"Doe\",\"email\":\"jimmy.doe@notarylive.com\"}]"

You can use this same technique to add witnesses to the request.

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create -d "customer_fname=John&customer_lname=Doe&customer_email=john.doe@notarylive.com&order_id=your_company_order_id&witnesses=[{\"first_name\":\"Jane\",\"last_name\":\"Doe\",\"email\":\"jane.doe@notarylive.com\"}]"

Below is an example of adding both an additional signer and a witness to the request:

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create -d "customer_fname=John&customer_lname=Doe&customer_email=john.doe@notarylive.com&order_id=your_company_order_id&additional_signers=[{\"first_name\":\"Jane\",\"last_name\":\"Doe\",\"email\":\"jane.doe@notarylive.com\"}]&witnesses=[{\"first_name\":\"Jimmy\",\"last_name\":\"Doe\",\"email\":\"jimmy.doe@notarylive.com\"}]"

Please note: Each additional signer or witness you add to the request increases the price of the order by $5 dollars. All signers and witnesses must have a unique email address, and the API request will fail with a validation error if participants share email addresses.

Choose who pays

By default, the person notarizing the document will need to pay for the notarial session. If you would like to pay for the session instead of the end user, you may do so by setting the charge_to API parameter to my_account, as shown below:

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create -d "customer_fname=John&customer_lname=Doe&customer_email=john.doe@notarylive.com&order_id=your_company_order_id&charge_to=my_account"

Please note: Charging orders to your account is only available to Business Premier level accounts with a working payment profile saved to the system. Using the charge_to=my_account parameter on an unqualified account will cause the Create Session Order API call to fail. Only orders which complete the notarial event successfully will be charged to your account. Billing for these orders occurs at the end of the month and will be reflected in your monthly invoice.

Please contact us at support@notarylive.com if you would like to set up a Business Premier account and use the charge_to API parameter.

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:

curl -X POST --user api_test_user:api_test_key https://notarylive.com/api/order/create -d "customer_fname=John&customer_lname=Doe123&order_id=your_company_order_id"

{
  "success":0,
  "errors":[
    {
       "code":"customer_email_missing"
       "message":"customer_email is required"
    }
  ]
}

Validation Rules

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

If the skip_upload_doc_page parameter is set to true a document must also be provided using any of the following parameters: doc_urls, documents, or document_1 - document_4

Order ID

The order_id parameter is used to identify the order in your internal systems.

If you're using the same order_id for multiple sessions, make sure your system can properly track and differentiate each one to avoid any mix-ups when webhooks are received or when you're retrieving information for a specific session.

Example of webhook events for two different NotaryLive sessions with the same order_id:

{
        "event": "order_created",
        "nl_order_id": "notarylive_order_id",
        "their_order_id": "1234",
        "customer_email": "customer@domain.tld"
}

{
    "event": "order_created",
    "nl_order_id": "new_notarylive_order_id",
    "their_order_id": "1234",
    "customer_email": "customer@domain.tld"
}

Choosing how you receive files back

By default, NotaryLive will send the notarized 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 --user api_test_user:api_test_key https://notarylive.com/api/order/create -d "receive_files_as_attachments=1&customer_fname=John&customer_lname=Doe&customer_email=john.doe@notarylive.com&order_id=your_company_order_id"

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": "document_notarized", "nl_order_id": "1s1129", "their_order_id": "your_company_order_id", "customer_email": "john.doe@notarylive.com", "link_to_document": [ "https://notary-session-files.../document1.pdf", "https://notary-session-files.../document2.pdf" ], "order_price": 25, "number_of_participants_together": 1, "total_doc_page_count": 10 }

receive_files_as_attachments enabled:

{ "response": "{\"event\":\"document_notarized\",\"nl_order_id\":\"1s1130\",\"their_order_id\":\"((internal_order_id))\",\"customer_email\":\"john.doe@notarylive.com\",\"order_price\":25,\"number_of_participants_together\":1,\"total_doc_page_count\":10}" }

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.

In addition to the notarized documents, enabling receive_files_as_attachments will also attach the audit trail for that order in .csv format.

The audit trail will be attached to the webhook POST in the following file format:

audit-trail

The actual filename will be audit-trail-{nl_order_number}.csv. The file will consist of order details including time of notarization, signer name and email, etc.

Receiving IDs Back

You can also receive IDs back as files in the webhook event using receive_files_as_attachments.

In order to use this feature, you must:

• be approved for this feature by NotaryLive (contact us at support@notarylive.com)
• be in production mode
• enable receive_files_as_attachments

Once the above requirements are met, the IDs for each participant will be attached to the webhook POST in the following file format:

participant-1-id-front
participant-1-id-back
participant-2-id-front
participant-2-id-back
etc

If the participant supplied a passport, the participant-{number}-id-back file will not exist and will not be sent in 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 order lifecycle:

{
    "event": "kba_locked_out",
    "nl_order_id": "notarylive_order_id",
    "their_order_id": "your_company_order_id",
    "customer_email": "customer@domain.tld",
    "verifier_email": "verifier@domain.tld" // if a verifier was used
}

{
    "event": "order_canceled",
    "nl_order_id": "notarylive_order_id",
    "their_order_id": "your_company_order_id",
    "customer_email": "customer@domain.tld",
    "cancel_reason_code": "canceled_by_notary",
    "cancel_reason": "cant notarize"
}

Please note: the link_to_document 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

Canceled Orders

The following are the possible values for the cancel_reason_code

Expired Orders

For security purposes, incomplete orders are purged from the NotaryLive platform after multiple days of inactivity. When a customer tries to resume an order that is expired, they are instead shown a notice that they will need to start a new order.

In order to provide a more seamless experience to the customer, you may include an expired_order_redirect parameter during the order creation API call. If this parameter is included during order creation, we will automatically redirect the customer to the url provided when the customer tries to resume a canceled order. Once the customer has been directed to your url, you can then tailor the expiration message, authentication rules and conditions under which the customer can start a new notarization order to what will fit your business needs.

Troubleshooting Issues Locally or in Production

If your integration is not behaving as it should, the following checklist is useful to narrow down the source of the problem:

1. Do the example curl calls above work on your local machine?
2. Do the example curl calls above work in your production environment?
3. Does your integration code work on your local machine?
4. Does your integration code work in your production environment?

If the example curl calls above work on your local machine but do not work in your production environment, please reach out to us at support@notarylive.com to ensure that your production environment has not been flagged by any automated security measures.

Moving to Production

Please reach out to us at support@notarylive.com to request access to the production environment. Once you have been provided with your production API user ID and API key, you will then replace 'api_test_user' and 'api_test_key' in the examples above with your production credentials.

Copyright © 2025, NotaryLive.com