E-signature integrations

You can connect Adobe Acrobat Sign or DocuSign to the archive, so that your documents are archived after they're signed. Your own code doesn't call these endpoints. You register their URLs in Acrobat Sign or DocuSign, and the e-signature service calls them when something happens.

Each signed agreement, envelope, or file becomes a package in the archive. Docbyte sets up the integration with you.

The calls that archive content need an access token whose tenant claim names your tenant: the Acrobat Sign notification, DocuSign Connect, and the DocuSign file archive call.

To get the address of your Archive API, go to General information. In the URLs here, it's https://api.example.com.

Adobe Acrobat Sign

When an agreement is signed or approved, Acrobat Sign sends a webhook notification to the archive. The archive answers at once, and then fetches the agreement from Acrobat Sign and archives it in the background.

What gets archived

The archive only archives agreements with the status SIGNED or APPROVED. It ignores notifications for every other status.

Each agreement becomes one package. Its package ID is the agreement ID, with special characters replaced. The package holds:

• The signed PDF, named after the agreement.

• Descriptive metadata with the agreement's name as the title.

• The agreement details from Acrobat Sign, such as the sender, the dates, the signature type, and each signer with their role and status.

• Values from the agreement's form fields, if Docbyte mapped them to a metadata schema for you.

Each agreement is archived only once. If Acrobat Sign sends another notification for an agreement that's already archived, or that's being archived, nothing happens. If the archive couldn't fetch the agreement or build its package, the next notification for that agreement tries again.

Set up Acrobat Sign

Before you begin, ask Docbyte to:

• Give you the client ID and client secret that Acrobat Sign uses to get an access token.

• Register the client ID of your Acrobat Sign application. The archive only accepts webhook calls from that application.

• Set up the archive's access to your Acrobat Sign account, so that the archive can download the signed agreements.

Then register these URLs in Acrobat Sign, together with Docbyte:

The notifications must include the agreement info, because the archive reads agreement.id and agreement.status from them.

Get an access token

Acrobat Sign calls this endpoint to get an access token for the webhook calls. The archive passes the request on to the identity provider and returns its answer.

POST /v2/acrobat-sign/token

The body is form data (application/x-www-form-urlencoded):

Response: 200 OK with a token.

If the identity provider refuses the request, you get its status code back, for example 401 for a wrong client secret.

Verify the webhook URL

Acrobat Sign calls this endpoint to check that the webhook URL belongs to a service that expects its notifications.

GET /v2/acrobat-sign/webhook

Required role: any valid access token.

Headers:

Response: 200 OK. The archive sends the client ID back in the X-AdobeSign-ClientId response header and in the body:

{
  "xAdobeSignClientId": "CBJCHBCAABAAexampleclientid"
}

Errors that you can get:

• 403 with reason WEBHOOK_CLIENT_MISMATCH: the client ID isn't the one that the archive expects.

Receive a notification

Acrobat Sign calls this endpoint for each event that the webhook subscribes to. The body is the webhook notification from Acrobat Sign.

POST /v2/acrobat-sign/webhook

Required role: any valid access token.

Headers:

Response: 204 No Content, with the client ID in the X-AdobeSign-ClientId response header. The archive answers before it archives the agreement, so this response doesn't mean that the agreement is in the archive yet.

Errors that you can get:

• 403 with reason WEBHOOK_CLIENT_MISMATCH: the client ID isn't the one that the archive expects.

• 401 with reason TENANT_CLAIM_MISSING: the access token has no tenant claim.

DocuSign

You can archive DocuSign documents in two ways:

• DocuSign Connect: DocuSign sends a notification when an envelope is completed, and the archive archives the envelope's documents.

• File IO extension: DocuSign's extension for storing files in an outside system. The archive shows up as a drive in DocuSign, and each file that DocuSign sends to it becomes a package.

For both, the account behind the access token needs permission to add content to the archive.

Archive completed envelopes with DocuSign Connect

Register https://api.example.com/v2/docusign/connect as the URL of a Connect configuration in DocuSign. The configuration must send JSON, send the envelope-completed event, and include the documents, because the archive takes the PDFs from the notification itself.

DocuSign then calls this endpoint:

POST /v2/docusign/connect

Required role: any valid access token, for an account that can add content to the archive.

The body is the DocuSign Connect notification. The archive reads:

For an envelope-completed event, the archive creates one package for the envelope, with a new package ID. The package holds:

• Each document of the envelope as a PDF file.

• The envelope details from the notification, as a JSON file, without the document content.

• Descriptive metadata with the name of the envelope's first content document as the title, or the envelope ID if it has no content document.

Response: 200 OK. The message field holds the package ID of the new package:

{
  "message": "uuid-3f6a1c2e-8b4d-4e9f-a7c5-2d1b0e9f8a76"
}

For any other event, you also get 200 OK, with the message Only envelope-completed event supported, and nothing is archived.

The ingest of the package continues after the response. To follow it, go to Ingest API.

Errors that you can get:

• 403 with reason PERMISSION_DENIED: the account can't add content to the archive.

• 401 with reason TENANT_CLAIM_MISSING: the access token has no tenant claim.

Store files with the File IO extension

With the File IO extension, DocuSign users can send files to the archive. The extension uses these three endpoints:

List drives

POST /v2/docusign/listdrives

Required role: any valid access token.

The archive shows up as one drive, whatever the request holds:

{
  "containerType": "drive",
  "data": [
    {
      "containerId": "docbyte",
      "containerName": "Docbyte Archive"
    }
  ]
}

List directory contents

POST /v2/docusign/listdirectorycontents

Required role: any valid access token.

The drive has no folders. The response sends back the parentId from the request, with an empty list:

{
  "parentId": "docbyte",
  "data": []
}

Archive files

Each file becomes its own package, with a new package ID.

POST /v2/docusign/filearchive

Required role: any valid access token, for an account that can add content to the archive.

Body fields:

Response: 200 OK with the files that the archive received, with the basename and path that you sent:

{
  "filesWritten": [
    {
      "basename": "contract.pdf",
      "path": "/docbyte"
    }
  ]
}

The ingest of each package continues after the response.

Errors that you can get:

• 403 with reason PERMISSION_DENIED: the account can't add content to the archive.

• 401 with reason TENANT_CLAIM_MISSING: the access token has no tenant claim.