Upload PDF file or file metadata

    Method: PUT

    Path: /api/transaction/{transactionId}/file/{fileId}

    Upload either a PDF file or file metadata to a transaction. The Content-Type header determines which endpoint is used:

    • application/pdf: Upload PDF file content
    • application/json: Upload file metadata

    Add a file to the transaction or overwrite an existing file with the same `fileId``.

    The file parameter can either be the PDF document or JSON metadata.

    If your file requires metadata, the JSON metadata MUST be supplied first.

    File digest header

    When uploading a file, it is possible to send a digest header along with the HTTP request. This header should contain a base64-encoded SHA checksum of the uploaded file. For more information on digest headers, refer to RFC 3230 for format instructions and RFC 5843 for the supported algorithms.

    Supported Algorithms

    Currently, only SHA-256 and SHA-512 are accepted as hash algorithms. While RFC 3230 originally included MD5 and SHA-1, these weaker algorithms are no longer supported for security reasons. Using SHA-256 or SHA-512 ensures compliance with modern security standards.

    For example: Digest: SHA-256=HtHRpLOZBEMnTpQS6Zn12veC4uhjtMwamfVAwmPQPmE=

    Parameters

    NameInTypeRequiredDescription
    transactionIdpathstringYes

    The transaction to add the files to

    fileIdpathstringYes

    A unique identifier for the file within the transaction. Must not exceed 255 characters and cannot contain control characters or the following special characters: :, *, ?, </code>, /, ", <, >,

    Content-TypeheaderstringYes

    Content type - either application/pdf for file upload or application/json for metadata

    DigestheaderstringNo

    SHA-256 or SHA-512 checksum of the PDF file for integrity verification (only for PDF uploads)

    Request Body (required)

    Either PDF file content or file metadata JSON

    application/json

    Content-Type: application/json

    Schema: FileMetadata

    Properties

    NameTypeDescription
    DisplayNameStringNull
    DisplayOrderIntegerNull
    DescriptionStringNull
    SetParaphBooleanNull
    SignersObject

    Dictionary mapping signer identifiers to their specific configuration for this file. Each signer can have different form sets and signing requirements for the same document. The key is the signer identifier.

    FormSetsObject

    Nested dictionary structure defining form fields and signing areas within the document. The outer key represents the form set name, and the inner key represents individual field identifiers within that set. Form sets allow grouping related fields together for organization and signer assignment.

    The following characters are allowed as a key / field name: a-z A-Z 0-9 _.

    Map of pdf field definitions.

    application/pdf

    Content-Type: application/pdf

    Type: string

    Responses

    200

    File was updated successfully (PDF upload)

    Content-Type: application/json

    Properties

    NameTypeDescription
    MessageString

    201

    New file was created successfully (PDF upload)

    Content-Type: application/json

    Properties

    NameTypeDescription
    MessageString

    202

    Metadata accepted, waiting for actual file (metadata upload)

    Content-Type: application/json

    Properties

    NameTypeDescription
    MessageString

    400

    Bad request - validation error, digest mismatch, or invalid JSON

    Content-Type: application/json

    Schema: ErrorResponse

    Properties

    NameTypeDescription
    typeString

    A URI reference identifying the problem type. This property is always present in RFC 7807 responses.

    titleString

    A short, human-readable summary of the problem

    detailString

    A human-readable explanation specific to this occurrence of the problem

    statusInteger

    The HTTP status code

    instanceString

    A URI reference that identifies the specific occurrence of the problem

    MessageString

    Deprecated (Legacy Format Only): Contains the error message in the old response format. This property appears alone in legacy error responses and is mutually exclusive with the RFC 7807 properties above. Will be phased out as we complete our transition to RFC 7807.

    Examples:

    digestMismatch:

    {
  "Message": "SHA-256 digest mismatch"
}

    unsupportedAlgorithm:

    {
  "Message": "Hash algorithm [MD5] is not supported."
}

    invalidFileId:

    {
  "Message": "FileId is invalid"
}

    signerNotFound:

    {
  "Message": "Signer 'signer1' not found."
}

    missingContentType:

    {
  "Message": "Unexpected or missing Content-Type header, did you specify 'application/pdf'?"
}

    invalidJson:

    {
  "Message": "Invalid json structure provided."
}

    401

    Unauthorized - user not creator of transaction

    Content-Type: application/json

    Schema: ErrorResponse

    Properties

    NameTypeDescription
    typeString

    A URI reference identifying the problem type. This property is always present in RFC 7807 responses.

    titleString

    A short, human-readable summary of the problem

    detailString

    A human-readable explanation specific to this occurrence of the problem

    statusInteger

    The HTTP status code

    instanceString

    A URI reference that identifies the specific occurrence of the problem

    MessageString

    Deprecated (Legacy Format Only): Contains the error message in the old response format. This property appears alone in legacy error responses and is mutually exclusive with the RFC 7807 properties above. Will be phased out as we complete our transition to RFC 7807.

    Example:

    {
  "Message": "Unauthorized access to this resource."
}

    403

    Forbidden - authorization policy violation

    Content-Type: application/json

    Schema: ErrorResponse

    Properties

    NameTypeDescription
    typeString

    A URI reference identifying the problem type. This property is always present in RFC 7807 responses.

    titleString

    A short, human-readable summary of the problem

    detailString

    A human-readable explanation specific to this occurrence of the problem

    statusInteger

    The HTTP status code

    instanceString

    A URI reference that identifies the specific occurrence of the problem

    MessageString

    Deprecated (Legacy Format Only): Contains the error message in the old response format. This property appears alone in legacy error responses and is mutually exclusive with the RFC 7807 properties above. Will be phased out as we complete our transition to RFC 7807.

    Example:

    {
  "Message": "Access denied by authorization policy."
}

    413

    Payload too large - file exceeds 50MB limit

    Content-Type: application/json

    Schema: ErrorResponse

    Properties

    NameTypeDescription
    typeString

    A URI reference identifying the problem type. This property is always present in RFC 7807 responses.

    titleString

    A short, human-readable summary of the problem

    detailString

    A human-readable explanation specific to this occurrence of the problem

    statusInteger

    The HTTP status code

    instanceString

    A URI reference that identifies the specific occurrence of the problem

    MessageString

    Deprecated (Legacy Format Only): Contains the error message in the old response format. This property appears alone in legacy error responses and is mutually exclusive with the RFC 7807 properties above. Will be phased out as we complete our transition to RFC 7807.

    Example:

    {
  "Message": "Request entity too large."
}

    500

    Internal server error

    Content-Type: application/json

    Schema: ErrorResponse

    Properties

    NameTypeDescription
    typeString

    A URI reference identifying the problem type. This property is always present in RFC 7807 responses.

    titleString

    A short, human-readable summary of the problem

    detailString

    A human-readable explanation specific to this occurrence of the problem

    statusInteger

    The HTTP status code

    instanceString

    A URI reference that identifies the specific occurrence of the problem

    MessageString

    Deprecated (Legacy Format Only): Contains the error message in the old response format. This property appears alone in legacy error responses and is mutually exclusive with the RFC 7807 properties above. Will be phased out as we complete our transition to RFC 7807.

    Example:

    {
  "Message": "An internal server error occurred."
}