---
title: "Changing the Language of a Consent Document"
slug: "changing-the-language-of-a-consent-document"
updated: 2026-05-01T19:24:09Z
published: 2026-05-01T19:24:09Z
canonical: "docs.onespan.com/changing-the-language-of-a-consent-document"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changing the Language of a Consent Document

## 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](/v1/docs/changing-the-language-of-a-consent-document#manually-changing-a-consent-document-to-a-different-language). 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](/v1/docs/changing-the-language-of-a-consent-document#automatically-change-a-consent-document). With this approach the language of the consent document is automatically updated if the language of the transaction is changed.

### Manually changing a Consent Document to a different language

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:

```java
// 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 |

### Automatically change a Consent Document

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:

```java
// 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](/v1/docs/changing-the-language-of-a-consent-document#manually-changing-a-consent-document-to-a-different-language1). 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](/v1/docs/changing-the-language-of-a-consent-document#automatically-change-a-consent-document1). With this approach the language of the consent document is automatically updated if the language of the transaction is changed.

### Manually changing a Consent Document to a different language

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:

```csharp
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 |

### Automatically change a Consent Document

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:

```csharp
// 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

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

#### HTTP Headers

```http
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

```json
{
  "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

```json
{
  "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 |