Changing the Language of a Consent Document

  • Published on May 1, 2026
  • 9 minute(s) read
Prev Next

Java SDK

A consent document is a document used to confirm that a person agrees to the terms of the transaction and wishes to continue with the process.

OneSpan Sign automatically includes the Electronic Disclosures and Signatures Consent agreement in all its transactions. All signers must accept the terms of this agreement before they can access transaction documents.

This section explains how to change the language of the electronic consent document.

The language of the consent document can be updated in the following ways:

  1. Independently, by transaction. This allows you to manually change the language of the consent document for a specific transaction, regardless of what the actual language of the transaction is.

  2. Automatically, to match the transaction language. With this approach the language of the consent document is automatically updated if the language of the transaction is changed.

Use this method when you want to change the language of the default consent document independently of the transaction language.

Here is some sample code that can help you do this:

// Create payload to localize existing consent document
ConsentLocalizationPayload localizationPayload = new ConsentLocalizationPayload.Builder()
    .withLanguage(LocaleConverter.convertToString(Locale.FRENCH))
    .build();
  
try {
    // Executes a single POST against the localize-consent REST endpoint 
    ConsentLocalizationData consentLocalizationData = eslClient.getPackageService().localizeDefaultConsentDocument(packageId, localizationPayload);
} catch (EslServerException exception) {

            // Example of handling the most common request errors  
            ServerError serverError = exception.getServerError();
            
            // Handle HTTP 409 with a common business case: The consent document cannot be updated because the associated transaction includes at least 1 signer who has already accepted consent.
            if (HttpStatus.SC_CONFLICT == serverError.getCode()) {
                log.warn("Document Consent modification is not allowed for the specified transaction: " + serverError.getMessage());
            }
            // Handle HTTP 422 with possible reasons:
            else if (HttpStatus.SC_UNPROCESSABLE_ENTITY == serverError.getCode()) {
                // - No consent template configuration for the requested language
                if ("error.unprocessableEntity.defaultConsent.i18nConfiguration.notFound".equals(serverError.getMessageKey())) {
                    log.warn(serverError.getMessage() + " To enable consent configuration for the specified language contact our Support Team.");
                }
                // - No default document consent for the requested transaction
                // - Operation is requested for a non-default document consent
                else {
                    log.warn(serverError.getMessage());
                }
            }
}

On successful completion, the process returns the language state for both the package and the consent document. If the process is not completed successfully, the following is a list of possible errors:

Code

Message Key

Error Description

400

error.validation.defaultConsent.unsupportedLanguage

Invalid/Not supported language value

401

N/A

Not Authorized error

403 

error.forbidden.cannotEditDeletePkg

Access Denied error

404

error.validation.packageDoesNotExist

Transaction Not found error

409

error.conflict.defaultConsent.accepted

The Default Document Consent cannot be updated: the transaction has at least 1 signer with accepted consent

422

  1. error.unprocessableEntity.defaultConsent.i18nConfiguration.notFound

  2. error.unprocessableEntity.defaultConsent.notExist

  3. error.unprocessableEntity.defaultConsent.notUsed

  1. No consent template configuration for the requested language. To enable consent configuration for the specified language contact our Support Team.

  2. No default document consent for the requested transaction

  3. Operation is requested for a non-default document consent

500 

N/A

Internal server error

You can configure your account so that it automatically changes the Consent Document to match the transaction language. With this approach the language of the consent document is automatically updated if the language of the transaction is changed.

Here is some sample code that can help you do this:

// Giving: there is existing DocumentPackage sdkPackage to update
// Change the transaction language as a part of transaction update operation
sdkPackage.setLanguage(Locale.FRENCH);
// Update package and syncronize consent document language with transaction language
PackageUpdateWorkflowResult result = eslClient.getPackageService().updatePackageAndLocalizeConsent(packageId, sdkPackage);

If the process is not completed successfully, the following is a list of possible errors:

PackageUpdateWorkflowResult.ConsentInfo.Status

PackageUpdateWorkflowResult.ConsentInfo.Message

SKIPPED

Default document consent modification is not allowed: the transaction has at least one signer who has accepted the default consent.

SKIPPED

Consent localization not required because language did not change.

SKIPPED

Consent localization could not be determined: updatedPackage is not available.

FAILURE

Failed to localize default consent: The default document consent does not exist.

FAILURE

Failed to localize default consent: Default consent document modification is not allowed: no localized consent template configuration found.

FAILURE

Failed to localize default consent: The default document consent is not used.

.NET SDK

A consent document is a document used to confirm that a person agrees to the terms of the transaction and wishes to continue with the process.

OneSpan Sign automatically includes the Electronic Disclosures and Signatures Consent agreement in all its transactions. All signers must accept the terms of this agreement before they can access transaction documents.

This section explains how to change the language of the electronic consent document.

The language of the consent document can be updated in the following ways:

  1. Independently, by transaction. This allows you to manually change the language of the consent document for a specific transaction, regardless of what the actual language of the transaction is.

  2. Automatically, to match the transaction language. With this approach the language of the consent document is automatically updated if the language of the transaction is changed.

Use this method when you want to change the language of the default consent document independently of the transaction language.

Here is some sample code that can help you do this:

try 
{
    // Executes a single call against the localize-consent REST endpoint
    result = ossClient.LocalizeConsent(packageId, "fr");
}
catch (OssServerException e)
{
    // Example of handling the most common request errors
    ServerError serverError = e.ServerError;

    // Handle HTTP 409: The consent document cannot be updated because at least one signer has already accepted consent
    if (serverError.Code == 409)
    {
        // Log a warning for business case conflict
        Console.WriteLine("Document Consent modification is not allowed for the specified transaction: " + serverError.Message);
    }
    // Handle HTTP 422: Unprocessable Entity
    else if (serverError.Code == 422)
    {
        // No consent template configuration for the requested language
        if ("error.unprocessableEntity.defaultConsent.i18nConfiguration.notFound".Equals(serverError.MessageKey))
        {
            Console.WriteLine(serverError.Message + " To enable consent configuration for the specified language contact our Support Team.");
        }
        // Other unprocessable entity cases
        else
        {
            Console.WriteLine(serverError.Technical);
        }
    }
    else {
        Console.WriteLine(serverError.Technical);
    }
}

On successful completion, the process returns the language state for both the package and the consent document. If the process is not completed successfully, the following is a list of possible errors:

Code

Message Key

Error Description

400

error.validation.defaultConsent.unsupportedLanguage

Invalid/Not supported language value

401

N/A

Not Authorized error

403

error.forbidden.cannotEditDeletePkg

Access Denied error

404

error.validation.packageDoesNotExist

Transaction Not found error

409

error.conflict.defaultConsent.accepted

The Default Document Consent cannot be updated: the transaction has at least 1 signer with accepted consent

422

  1. error.unprocessableEntity.defaultConsent.i18nConfiguration.notFound

  2. error.unprocessableEntity.defaultConsent.notExist

  3. error.unprocessableEntity.defaultConsent.notUsed

  1. No consent template configuration for the requested language. To enable consent configuration for the specified language contact our Support Team.

  2. No default document consent for the requested transaction

  3. Operation is requested for a non-default document consent

500

N/A

Internal server error

You can configure your account so that it automatically changes the Consent Document to match the transaction language. With this approach the language of the consent document is automatically updated if the language of the transaction is changed.

Here is some sample code that can help you do this:

// Giving: there is existing DocumentPackage with packageId to update
// Change the transaction language as a part of transaction update operation
packageToUpdate = PackageBuilder.NewPackageNamed(UPDATED_PACKAGE_NAME)
                   .WithLanguage(CultureInfo.GetCultureInfo("fr"))
                   .Build();
// Update package and syncronize consent document language with transaction language                   
PackageUpdateWorkflowResult updateWorkflowResult = ossClient.UpdatePackageAndLocalizeConsent(packageId, packageToUpdate);

If the process is not completed successfully, the following is a list of possible errors:

PackageUpdateWorkflowResult.ConsentInfo.Status

PackageUpdateWorkflowResult.ConsentInfo.Message

SKIPPED

Default document consent modification is not allowed: the transaction has at least one signer who has accepted the default consent.

SKIPPED

Consent localization not required because language did not change.

SKIPPED

Consent localization could not be determined: updatedPackage is not available.

FAILURE

Failed to localize default consent: The default document consent does not exist.

FAILURE

Failed to localize default consent: Default consent document modification is not allowed: no localized consent template configuration found.

FAILURE

Failed to localize default consent: The default document consent is not used.

REST API

A consent document is a document used to confirm that a person agrees to the terms of the transaction and wishes to continue with the process.

OneSpan Sign automatically includes the Electronic Disclosures and Signatures Consent agreement in all its transactions. All signers must accept the terms of this agreement before they can access transaction documents.

You can configure your account so that it automatically changes the Consent Document to match the transaction language. With this approach the language of the consent document is automatically updated if the language of the transaction is changed.

Here is some sample code that can help you do this:

HTTP Request

 POST `/api/packages/{packageId}/documents/localize-consent`

HTTP Headers

Accept: application/json 
Content-Type: application/json 
Authorization: Basic api_key

Path Parameters

Parameter

Type

Required

Description

packageId

string

Yes

The target transaction identifier.

Request Payload

{
  "language": "fr"
}

Request Payload Table

For a complete description of each field, see the Request Payload table below.

Property

Type

Required

Default

Sample Values

Description

language

string

Yes

n/a

en, fr

Language code used to localize the default consent document. Must be non-blank.

Response Payload

{
  "consentId": "default-consent",
  "consentMetadata": {
    "packageInfo": {
      "uid": "71c3b7f0-1f2b-4a54-9f62-2fb6c2df6e2b",
      "language": "fr"
    },
    "properties": {
      "accountId": "acc_0011223344",
      "language": "fr"
    },
    "document": {
      "accountId": "acc_0011223344",
      "language": "en"
    }
  },
  "alerts": [
    {
      "severityLevel": "WARNING",
      "code": "warning.defaultConsent.language.mismatch",
      "defaultMessage": "The consent title language 'fr' doesn't match the consent document language 'en'.",
      "parameters": {
        "titleLanguage": "fr",
        "documentLanguage": "en"
      }
    }
  ]
}

Response Payload Table

Property

Type

Description

consentId

string

The identifier of the localized consent document (for default consent this is typically `default-consent`).

consentMetadata

object

Metadata describing the package and localized resources.

consentMetadata.packageInfo

object

Package identifier + package language.

consentMetadata.packageInfo.uid

string

The package UID.

consentMetadata.packageInfo.language

string

The package language at the time of localization.

consentMetadata.properties

object

Metadata for the “properties” consent resource.

consentMetadata.properties.accountId

string

Account identifier owning the resource.

consentMetadata.properties.language

string

Language for the properties resource.

consentMetadata.document

object

Metadata for the document consent resource.

consentMetadata.document.accountId

string

Account identifier owning the resource.

consentMetadata.document.language

string

Language for the document resource.

alerts

array

Optional system alerts (may be omitted/empty). Typically returned if a warning condition is detected (e.g., language mismatch).

If the process is not completed successfully, the following is a list of possible errors:

Code

Message Key

Error Description

400

error.validation.defaultConsent.unsupportedLanguage

Invalid/Not supported language value

401

N/A

Not Authorized error

403

error.forbidden.cannotEditDeletePkg

Access Denied error

404

error.validation.packageDoesNotExist

Transaction Not found error

409

error.conflict.defaultConsent.accepted

The Default Document Consent cannot be updated: the transaction has at least 1 signer with accepted consent

422

  1. error.unprocessableEntity.defaultConsent.i18nConfiguration.notFound

  2. error.unprocessableEntity.defaultConsent.notExist

  3. error.unprocessableEntity.defaultConsent.notUsed

  1. No consent template configuration for the requested language. To enable consent configuration for the specified language contact our Support Team.

  2. No default document consent for the requested transaction

  3. Operation is requested for a non-default document consent

500

N/A

Internal server error