Business API quick start guide

Audience: Organizations

Before you begin.

Availability: API access is available to eligible organization accounts. Contact your Customer Success Manager (CSM) or Sales representative if API access is not enabled for your organization.
Important: API credentials provide access to your Proof account. Store API keys and OAuth secrets securely, and never share them publicly or through unsecured channels.

The short answer: The Proof Business API lets you send documents to Proof and connect your signer to complete them. This guide outlines the sequence of API calls typically used for an end-to-end Proof integration.

The API is organized around REST, uses predictable resource-oriented URLs, and returns HTTP response codes to indicate errors. Webhooks are available to notify you when a transaction changes state.

For full technical specifications, see the API Endpoint Reference. OAuth client applications are also available as an alternative authentication method.

Common use cases

  • Creating Proof transactions from an external platform
  • Sending documents to Proof through an integration
  • Connecting signers to complete notarization or eSignature workflows
  • Monitoring transaction status with webhooks
  • Retrieving completed documents through the API

Security considerations

  • Store API keys and OAuth secrets in a secure credential management system.
  • Never expose credentials in source code repositories or client-side applications.
  • Rotate credentials according to your organization’s security policies.
  • Use OAuth client applications when your integration requires OAuth-based authentication.
  • Delete or revoke unused, exposed, or compromised credentials immediately.

1. Generate your API key

After you create a Proof account, generate your API key from within your account. To generate your key, follow these instructions.

Tip: OAuth client applications are also available for approved organizations that prefer OAuth-based authentication.

2. Decide the transaction parameters

These parameters allow you to customize the transaction for your internal needs and the signer experience. You can set values such as transaction_name, file_number, and message_to_signer. A full list of parameters can be found in the Create Transaction endpoint.

Specifically, we recommend setting the following:

  • draft_sign: true

3. Create your transaction

Once you've decided on your transaction parameters, make a POST request to the Create Transaction endpoint to create the transaction.

4. Add your documents to the transaction

Proof supports .pdf files supplied as URLs or base64 encoded local files. You can also pass a document with PDF bookmarks so each bookmark becomes its own individual document in the transaction. If you do so, set the pdf_bookmarked attribute to true.

If you pass a pdf_bookmarked document, it may take Proof additional time to split it. Proof will respond with a 200 response indicating the document upload is in progress. To set document parameters on a pdf_bookmarked document, wait for the upload to complete, retrieve the document object from the transaction, and use the returned document ID to update the document flags.

A full list of supported document parameters is available in the Add Document to Transaction endpoint. These parameters allow you to set document-level permissions such as notarization_required or witness_required.

5. Monitor the transaction

Use Proof Webhooks to monitor transaction state changes. Several events may be sent, including events for when a signer receives the transaction email, opens the transaction, and completes signing.

6. Retrieve the completed transaction

The Retrieve Transaction endpoint returns links to completed documents. Alternatively, the binary file content for each document can be returned using the Retrieve Document endpoint.

Best practices

  • Test API workflows in a non-production environment before live deployment.
  • Confirm transaction parameters before sending invitations to signers.
  • Use webhooks instead of manual polling whenever possible.
  • Validate document-level flags before sending the transaction.
  • Securely store credentials and rotate them according to your organization’s policy.

Troubleshooting

  • If you cannot create a transaction, confirm your organization has API access enabled and that your credentials are valid.
  • If document upload is delayed, check whether the document was submitted with pdf_bookmarked set to true.
  • If webhook events are not received, confirm your webhook endpoint is active, reachable, and configured to accept Proof webhook events.
  • If completed documents are unavailable, confirm the transaction has completed before calling the retrieve endpoints.

Summary Checklist

  • Generate your API key or configure an OAuth client application.
  • Set draft_sign: true in your transaction parameters.
  • POST to the Create Transaction endpoint to initialize the transaction.
  • Add your PDF documents and set document-level flags, such as notarization_required.
  • Set up webhooks to monitor transaction state changes.
  • Use the Retrieve Transaction or Retrieve Document endpoint to access completed files.
i
Still unsure? For full technical specifications, see the API Endpoint Reference, or contact Proof Support for help.

Updated

Was this article helpful?

0 out of 1 found this helpful