NotaryLive API - Order Creation

Creating a Session Order

Below is an example request to create a customer order:

curl -X POST "https://notarylive.com/api/v2/order/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{"options": {"internal_id": "((internal_order_id))"}, "participants": [{"email": "john.doe@notarylive.com", "last_name": "Doe", "type": "signer", "first_name": "John"}]}'

A successful request will generate the following response:

{
    "success":1,
    "link_to_order":"https://notarylive.com/notarize/request-form?guest=true&oid={unique_order_identifier}"
}

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={unique_order_identifier}"
}

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.

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 "https://notarylive.com/api/v2/order/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{"options":{"internal_id":"internal_order_id"},"participants":[{"email":"john.doe@notarylive.com","last_name":"Doe","first_name":"Johnny"}]}'

{
    "success": 0,
    "errors": [
        {
            "code": "validation_failed",
            "message": "At least 1 participant of type 'signer' is required."
        },
        {
            "code": "validation_failed",
            "message": "The participants.0.type field is required."
        }
    ]
}

Attaching Documents

via Document URL

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

curl -X POST "https://notarylive.com/api/v2/order/create" \
    -u 'api_test_user:api_test_key' \
    -H 'Content-Type: application/json' \
    -d $'{"options": {"internal_id": "((internal_order_id))"}, "participants": [{"email": "john.doe@notarylive.com", "last_name": "Doe", "type": "signer", "first_name": "Johnny"}], "document_urls": ["https://pdfobject.com/pdf/sample.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 "https://notarylive.com/api/v2/order/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" \
    -F "participants[0][type]=signer" \
    -F "options[internal_id]=internal_order_id"

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 and witnesses to the request in the Session Order API by using the participants parameter. The participants parameter accepts an array of objects representing participants, the first signer will always be treated as the primary signer. Each participant object must contain the following parameters:

• first_name - The first name of the participant
• last_name - The last name of the participant
• email - The email address of the participant
• type - The type 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 "https://notarylive.com/api/v2/order/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{"options":{"internal_id":"((internal_order_id))"},"participants":[{"email":"john.doe@notarylive.com","last_name":"Doe","type":"signer","first_name":"Johnny"},{"email":"jane.doe@notarylive.com","last_name":"Doe","type":"signer","first_name":"Jane"}]}'

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

curl -X POST "https://notarylive.com/api/v2/order/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{"options":{"internal_id":"((internal_order_id))"},"participants":[{"email":"john.doe@notarylive.com","last_name":"Doe","type":"signer","first_name":"Johnny"},{"email":"jane.doe@notarylive.com","last_name":"Doe","type":"witness","first_name":"Jane"}]}'

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.

Choosing 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 options.charge_to API parameter to my_account, as shown below:

curl -X POST "https://notarylive.com/api/v2/order/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{"options":{"charge_to":"my_account","internal_id":"((internal_order_id))"},"participants":[{"email":"john.doe@notarylive.com","last_name":"Doe","type":"signer","first_name":"Johnny"}]}'

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 options.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 note: Using the test credentials (-u 'api_test_user:api_test_key') in combination with options.charge_to=my_account will result in an error as this account can't be used as a funding source.

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.

Using Templates

Order templates allow you to reuse the same type of document for multiple 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 order.

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

Please note: If you provide options.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.

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/v2/order/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"] \
            ] \
         ] \
      } \
   ], \
   "options":{ \
      "template_id":"((template_id))", \
      "internal_id":"((internal_order_id))" \
   }, \
   "participants":[ \
      { \
         "email":"john.doe@notarylive.com", \
         "last_name":"Doe", \
         "type":"signer", \
         "first_name":"Johnny" \
      } \
   ] \
}'

Once the 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.

Editing Participants During the Session

Two API parameters control what your clients are able to edit during the session, client_can_change_names and client_can_add_or_remove_participants. Additional info regarding these parameters can be found in the validation rules.

If you have additional requirements for forms of identification, please reach out to us at support@notarylive.com for help crafting custom solutions.

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 "https://notarylive.com/api/v2/order/create" \
    -H 'Content-Type: application/json' \
    -u 'api_test_user:api_test_key' \
    -d $'{"options": {"receive_files_as_attachments": 1, "internal_id": "((internal_order_id))"}, "participants": [{"email": "john.doe@notarylive.com", "last_name": "Doe", "type": "signer", "first_name": "John"}]}'

Please note: NotaryLive webhook events by default are send 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": "((internal_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,
    "participants": "[{\"email\":\"john.doe@notarylive.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"type\":\"signer\"}]",
    "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,"participants":"[{\"email\":\"john.doe@notarylive.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"type\":\"signer\"}]","total_doc_page_count":2}\"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.

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.

Keeping Track of Different Documents in the Notarization Lifecycle

When multiple documents must be notarized at the same time, it is crucial to have a system in place to identify which document is which in an automated way. To accomplish this, we recommend using the document_ids API parameter, like so:

curl -X POST "https://notarylive.com/api/v2/order/create" \
    -u 'api_test_user:api_test_key' \
    -H 'Content-Type: application/json' \
    -d $'{"options": {"internal_id": "((internal_order_id))"}, "participants": [{"email": "john.doe@notarylive.com", "last_name": "Doe", "type": "signer", "first_name": "Johnny"}], "document_urls": ["https://pdfobject.com/pdf/sample.pdf", "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"],"document_ids": ["deed-of-trust", "grant-deed"]}'

The document_ids parameter works by matching the exact order of either the document_urls or the document_files you've supplied. In the example above, this means that https://pdfobject.com/pdf/sample.pdf is marked in our system as document_id deed-of-trust, and we will keep track of that identifier throughout the lifecycle of the document. Once the session has been notarized, we will send the document_notarized webhook event like so:

{
    "event": "document_notarized",
    "nl_order_id": "1s1129",
    "their_order_id": "((internal_order_id))",
    "customer_email": "john.doe@notarylive.com",
    "link_to_document": [
        "https://notary-session-files.../document1.pdf",
        "https://notary-session-files.../document2.pdf"
    ],
    "document_ids":[
        "deed-of-trust",
        "grant-deed"
    ],
    "order_price": 25,
    "number_of_participants_together": 1,
    "participants": "[{\"email\":\"john.doe@notarylive.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"type\":\"signer\"}]",
    "total_doc_page_count": 10
}

It will then be the responsibility of your system that receives the webhook to tie together that the first entry in document_ids is "deed-of-trust", which is the first entry in the link_to_document array.

Attaching Instructions For The Notary

Sessions notes are not required, but if you feel the notary should be aware of special information unique to a particular signing or in compliance with your business needs, you can pass guidance along to the notary in the options.instructions parameter. Below is an example of how to supply those instructions:

curl -X POST "https://notarylive.com/api/v2/order/create" \
    -u 'api_test_user:api_test_key' \
    -H 'Content-Type: application/json' \
    -d $'{"options": {"internal_id": "((internal_order_id))", "instructions":"1. Verify the Signer\'s Identity \\n Ask for valid identification (e.g., \\"government-issued photo ID\\"). \\n 2. Administer an Oath or Affirmation \\n Ask the signer to swear or affirm that the information is true \\n 3. Notify signer they will receive their notarized document in the Example.com Dashboard \\n Customers can reach out to support@example.com for further assistance"}, "participants": [{"email": "john.doe@notarylive.com", "last_name": "Doe", "type": "signer", "first_name": "Johnny"}], "document_urls": ["https://pdfobject.com/pdf/sample.pdf", "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"],"document_ids": ["deed-of-trust", "grant-deed"]}'

The notary will see a flashing red message while with the customer, notifying them that there are special instructions for this session:

And your note to the notary will then be rendered onscreen like so:

Webhook Events

The following webhook events are sent during the order lifecycle:

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

{
    "event": "customer_paid",
    "nl_order_id": "notarylive_order_id",
    "their_order_id": "your_company_order_id",
    "customer_email": "customer@domain.tld"
}

{
    "event": "passed_identity_verification",
    "nl_order_id": "notarylive_order_id",
    "their_order_id": "your_company_order_id",
    "customer_email": "customer@domain.tld"
}

{
    "event": "order_expired",
    "nl_order_id": "notarylive_order_id",
    "their_order_id": "your_company_order_id",
    "customer_email": "customer@domain.tld"
}

{
    "event": "ready_to_reattempt_kba",
    "nl_order_id": "notarylive_order_id",
    "their_order_id": "your_company_order_id",
    "customer_email": "customer@domain.tld"
}

{
    "event": "document_notarized",
    "nl_order_id": "notarylive_order_id",
    "their_order_id": "your_company_order_id",
    "customer_email": "customer@domain.tld",
    "link_to_document": "https://notary-session-files.../document.pdf",
    "order_price": 30,
    "number_of_participants_together": 3, // signers + witnesses, excluding verifiers
    "participants": "[{\"email\":\"john.doe@notarylive.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"type\":\"signer\"},{\"email\":\"jane.doe@notarylive.com\",\"first_name\":\"Jane\",\"last_name\":\"Doe\",\"type\":\"signer\"},{\"email\":\"jim.doe@notarylive.com\",\"first_name\":\"Jim\",\"last_name\":\"Doe\",\"type\":\"signer\"}]",
    "total_doc_page_count": 5
}

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.

You can trigger the expiration of an order immediately after it's creation. This is helpful in order to test your system's response to the order_expired webhook event. In order to immediately expire a created order, please set the primary signer's first name to NLexpireOrder. Please note! the NLexpireOrder technique will only work with production API credentials.

Absentee Participants

If a signer or witness is unable to attend the notarization at the same time as the rest of the participants, the primary signer can mark this participant as absentee. The absentee participant will receive a followup session to notarize after the original session has been completed.

In order for your system to tie these two sessions together, the document_notarized webhook event for the first session will contain additional information regarding the followup session. The two additional parts of the webhook response are the followup_order_id and the followup_order_member_details:

{
    "event": "document_notarized",
    "nl_order_id": "order_1",
    "their_order_id": "your_company_order_id",
    "customer_email": "john.doe@notarylive.com",
    "link_to_document": "https://notary-session-files.../document.pdf",
    "order_price": 25,
    "number_of_participants_together": 1, // signers + witnesses, excluding verifiers
    "participants": "[{\"email\":\"john.doe@notarylive.com\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"type\":\"signer\"}]",
    "total_doc_page_count": 5,
    "followup_order_id": "order_2",
    "link_to_followup_order": "https://notarylive.com/tu/cai...",
    "followup_order_member_details": "[{\"email\":\"jane.doe@notarylive.com\",\"first_name\":\"Jane\",\"last_name\":\"Doe\",\"type\":\"signer\"}]"
}

The primary signer of this followup session will be the first signer in the followup_order_member_details array above.

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.

Validation Rules

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

If the options.skip_upload_doc_page parameter is set to 1 a document must also be provided using any of the following parameters: document_urls or document_files

Changelogs

For a list of changes to this api endpoint, please see the changelog.

Copyright © 2024, NotaryLive.com