NotaryLive API - ID Preupload

ID Preuploads

NotaryLive allows you to preupload a signer's ID to the system before the notarial session begins. This removes friction for the user by allowing them to skip the upload ID step unless there was an issue while verifying the provided ID.

To preupload an ID, you will need to send a POST request to the /api/v2/id/upload endpoint. Below is an example:

curl -X POST "https://notarylive.com/api/v2/id/upload" \
    -u 'api_test_user:api_test_key' \
    -H 'Content-Type: multipart/form-data' \
    -F "ids[0][type]=drivers_license" \
    -F "ids[0][front_image]=@/path/to/drivers_license/front.jpg" \
    -F "ids[0][back_image]=@/path/to/drivers_license/back.jpg" \
    -F "ids[0][country_code]=USA"

Please note: The country code of the ID is required. Please make sure it is the three letter country code.

You can upload multiple IDs in a single request by incrementing the index of the ids array, for example:

curl -X POST "https://notarylive.com/api/v2/id/upload" \
    -u 'api_test_user:api_test_key' \
    -H 'Content-Type: multipart/form-data' \
    -F "ids[0][type]=drivers_license" \
    -F "ids[0][front_image]=@/path/to/drivers_license/front.jpg" \
    -F "ids[0][back_image]=@/path/to/drivers_license/back.jpg" \
    -F "ids[0][country_code]=USA" \
    -F "ids[1][type]=passport" \
    -F "ids[1][front_image]=@/path/to/passport/front_.jpg" \
    -F "ids[1][country_code]=USA"

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.

A successful request will generate the following response:

{
    "success": 1,
    "ids": [
        {
            "id": "01hkqatawd5xan77x806r3eyv9",
            "type": "drivers_license"
        }, {
            "id": "01hkqataxfaee30w9dh68rfhy5",
            "type": "passport"
        }
    ]
}

You will then need to pass the id returned above into either the Session Order API or the Iframe Creation API. Below is an example using the Session Order API with a Preupload ID of 01hkqatawd5xan77x806r3eyv9 retrieved from the previous API call:

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": [{"preupload_id":"01hkqatawd5xan77x806r3eyv9", "email": "john.doe@notarylive.com", "last_name": "Doe", "type": "signer", "first_name": "John"}]}'

Please note: You can only use a Preupload ID within a single session. You cannot reuse the same Preupload ID within multiple sessions.


Validation Rules

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

Parameter Validation Rules
ids Required | Array of objects
ids.*.type Required | String | Options: drivers_license, passport, id_card
ids.*.front_image Required | Image File
ids.*.back_image Required if ids.*.type is not passport | Image File
ids.*.country_code Optional | String | Defaults to: USA | 3-letter country code of ID

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, and 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/id/upload" \
    -u 'api_test_user:api_test_key' \
    -H 'Content-Type: multipart/form-data' \
    -F "ids[0][type]=dl" \
    -F "ids[0][front_image]=@/path/to/drivers_license/front.jpg" \
    -F "ids[0][back_image]=@/path/to/drivers_license/back.jpg"
{
    "success": 0,
    "errors": [
        {
            "code": "validation_failed",
            "message": "The selected ids.0.type is invalid. Valid options are 'drivers_license', 'passport' and 'id_card'."
        }
    ]
}

Changelogs

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


Copyright © 2025, NotaryLive.com