Document Retrieval and Archiving

Suggest Edits

Many users of Proof want to retrieve and archive documents when the transaction is completed. The following steps will walk you through some best practices on pulling documents from Proof in order to archive or use them in a downstream system.

1. Generate your full access API key.

See our guides on API Keys for more info.

2. Setup webhooks.

Webhooks allow you to subscribe to certain events within Proof. We have a complete webhook guide that will teach your the basics. This includes notes on our webhook security.

  1. Create an endpoint to receive and consume the webhook events.

  2. Use the Create Webhook endpoint to subscribe to the events you are interested in receiving.

    1. For document archiving, the most important events are transaction.completed and transaction.completed_with_rejections. This will tell your system when a document is ready to be retrieved.

    2. Note: When subscribing to a webhook, the API key will dictate which organization is subscribed to the transactions. If your organization uses a parent-child structure, you may need to make a decision on which organization you create your API key in.

      1. For example: You may only want to retrieve documents for transactions created by Child Org #2. In this case, the API key you use to subscribe to webhook events should be created under Child Org #2. If you were to use an API key created under the Parent Org, you would receive webhook events for all transactions created by that Parent Org as well as all of its Child Orgs.

    3. Example Create Webhook Request:

      POST /v2/webhooks/

{
    "url": "https://webhook.site/2aceb3d9-8602-4d97-94f3-a7d7e63fe1a3",
    "subscriptions": [
        "transaction.completed",
        "transaction.completed_with_rejections"
    ]
}

3. Retrieve documents.

When a transaction is completed, you’ll receive a webhook event telling you that the transaction status is now complete. This is when documents will be ready for retrieval.

  1. Example webhook event payload: 

    {
  "event": "transaction.completed_with_rejections",
  "data": {
    "transaction_id": "ot_nbr86qb"
  }
}

  2. Use the Retrieve Transaction endpoint to get the latest details on the completed transaction, using the transaction_id from the webhook event.

    1. If you are downloading documents via URL, the response from this endpoint will provide links for downloading all documents in the package as well as the audit trail.

    2. Example Retrieve Transaction Response (with non-relevant fields redacted). The most relevant fields for retrieval are the audit_trail_url, final_document_url (for each document), and the various signer metadata fields.

      {
    "id": "ot_nbr86qb",
    "audit_trail_url": "https://463675841562-notarize-productionmirror-documents.s3.amazonaws.com/4c1ca084d6317e7ab1b7_AuditTrail.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAWX5J33QNAB7B5UMG%2F20231109%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20231109T202438Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8ec57f72848dddc0bbf15f284e209f3ac4409851bd9dd0f4bf52ab761ff0bd1d",
    "date_created": "2023-10-11T15:32:59.991927Z",
    "date_updated": "2023-10-11T15:33:39.957143Z",
    "detailed_status": "complete",
    "documents": [
        {
            "id": "do_b2be9ead-fe82-48b2-86c4-409bdb5e127e",
            "date_created": "2023-10-11T15:33:00.221405Z",
            "date_updated": "2023-10-11T15:33:39.682147Z",
            "document_name": "20231011-66-40i052.pdf",
            "final_document_url": "https://463675841562-notarize-productionmirror-documents.s3.amazonaws.com/finalized_documents/9987d38ffed478662d46_.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAWX5J33QNAB7B5UMG%2F20231109%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20231109T202438Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=67f01d7b1d446c19551b95915d50ff6067c35a2eb11a9ecaae80d0cd9edd819e"
        },
        {
            "id": "do_1a718e6b-1c63-4679-9126-26754a4aa015",
            "date_created": "2023-10-11T15:33:11.459178Z",
            "date_updated": "2023-10-11T15:33:39.000000Z",
            "document_name": "dummy.pdf",
            "final_document_url": "https://463675841562-notarize-productionmirror-documents.s3.amazonaws.com/finalized_documents/9c4d0b4891d950ba2501_.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAWX5J33QNAB7B5UMG%2F20231109%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20231109T202438Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=44823192e04274c23020a58334fa82ff738c4cde38308866c09f198c676d5a2a"
        }
    ],
    "external_id": "123456",
    "organization_id": "or_nxz456n",
    "signer_info": {
        "email": "[email protected]",
        "first_name": "Test",
        "last_name": "Signer",
        },
        "signing_status": "complete"
    },
    "signers": [
        {
            "email": "[email protected]",
            "first_name": "Test",
            "last_name": "Signer",
            },
            "signing_status": "complete"
        }
    ],
    "status": "completed_with_rejections",
    "transaction_name": "Test Transaction"
}

  3. (Optional) If you would like to download documents in base64 format instead of via URL, the response from the endpoint above will provide document IDs. Take these document IDs and use them with the Get Document endpoint, making sure to include the query parameter encoding=base64.

Identifying Failed Delivery of Events

If you haven't already, check out the Errors and Retries section of the Webhook guide before reading this section.

When events retried and never succeeded in delivery, you can retrieve all webhook events that were not delivered using the following method. We'll focus on document retrieval for this example, but the same steps can be followed to reconcile other workflows that depend on webhook events.

  1. Use the List Webhooks endpoint to retrieve all webhook IDs that you have set up.
  2. Locate the webhook ID(s) for the endpoints that you want to pull failed events for.
  3. Use the Get Webhook Events endpoint to get all events triggered for a particular webhook ID.
    1. Example Get Webhook Events Payload: 
      [
    {
        "event": "transaction.completed_with_rejections",
        "response": {
            "body": "{\"success\":false,\"error\":{\"message\":\"Token not found\",\"id\":null}}",
            "code": 404,
            "error": "Webhook https://webhook.site/0fdc6aac-c71a-4587-944d-e25853ca5bd1 failed for 'BHJ Fairfax Business' with status 404 and returned {\"success\":false,\"error\":{\"message\":\"Token not found\",\"id\":null}}"
        },
        "delivered": "2023-10-11T15:33:41.501Z",
        "payload": "{\"event\":\"transaction.completed_with_rejections\",\"data\":{\"transaction_id\":\"ot_nbr86qb\"}}"
    }
]
  4. Look for events that you may have needed to take action on. In the case of document retrieval, it's likely you'll be looking for events where:
    1. Event = transaction.completed or transaction.completed_with_rejections
    2. Code ≠ 200
    3. Delivered = (time period of lookback)
  5. For each failed event you're interested in reconciling, retrieve the transaction_id from the "payload" property (example above).
  6. Bulk download documents for all identified transaction_ids by following the Retrieve Documents section above.

Updated 6 months ago