Skip to main content

​
Overview

You can attach external data to signing packages and documents to help integrate with your existing systems. This allows you to associate your internal identifiers or metadata with the packages and documents managed through our API.

​
Attaching external data to packages

When creating a signing package, you can attach external data to it using the externalData field in the add package request. This data can be any set of JSON-serializable key-value pairs and will be stored with the package.
Request
POST /packages/add
{
    "name": "New Package",
    "type": "concurrent",
    "signers": [
        {
            "firstName": "Signer",
            "lastName": "One",
            "email": "signer.one@example.com"
        }
    ],
    "documents": [
        {
            "fileName": "document.pdf",
            "fileId": "51400d7a-4f34-4844-9138-46a365130f97"
        }
    ],
    "externalData": {
        "internalId": "12345",
        "customerId": "67890"
    },
    "returnPackage": false
}
When you call future package-related endpoints, such as retrieving package details or checking the package status, the externalData field will be included in the response.
Request
GET /packages/{packageId}/status
Response
{
    "packageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    ...
    "externalData": {
        "internalId": "12345",
        "customerId": "67890"
    }
}
Package related webhooks will also include the externalData field in their payloads, allowing you to access this information during webhook processing.
Payload
{
	"packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
    "externalData": {
        "internalId": "12345",
        "customerId": "67890"
    },
	"action": "package_add",
	"eventId": "e9b8fe63-4a19-4446-bd6e-cb34b72b411e",
	"eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
	"eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
	"eventTime": "2022-02-23T20:19:28.9357901Z"
}

​
Attaching external ID to documents

You can also attach an external ID to individual documents within a package using the externalId query parameter when uploading files.
Request
POST /files/upload?externalId=doc12345
Content-Type: multipart/form-data
Content-Disposition: form-data; filename="document.pdf"
<FILE_CONTENTS>
Response
{
  "files": [
    {
      "fileId": "5997903d-2975-4c71-84d4-536255529b66",
      "externalId": "doc12345",
      "name": "document.pdf",
      "fileName": "document.pdf",
      "type": "temporary"
    }
  ]
}
When you later retrieve package details, the externalId will be included in the response.
Request
GET /packages/{packageId}/status
Response
{
    "packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
    ...
    "documents": [
        {
            "documentId": "ad8eac67-94e9-481b-a799-7396b447b8eb",
            "externalId": "doc12345",
            "fileName": "document.pdf",
            ...
        }
    ]
}