> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL.
>
> Documentation indexes by section:
> - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt
> - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt
> - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt
> - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt
>
> Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth
> Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks
>
> OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json
> MCP server: https://docusign.docs.buildwithfern.com/_mcp/server

# Postal address verification extension contract reference

> Learn about the requirements to implement the postal address verification extension.

This extension enables real-time verification and reformatting of a postal address. After installing the extension, users will be able to add envelope tabs that automatically verify and reformat address fields.

> **Note**
>
> This extension verifies specific types of values. See [Connected fields extension overview](/extension-apps/extension-apps-101/supported-extensions/connected-fields) for information about an extension that can verify any type of value against an organization’s system of record.

You can include this extension when you [register an extension app](/extension-apps/build-an-extension-app/register). If you register the extension app [using a form](/extension-apps/build-an-extension-app/register/use-form), select the **Data Verification** extension in the form-based UI. Then select a verification type of **Postal Address**.

![Form-based app registration for postal address verification](/_fern-files/_img/d9cb15408eff1d4a93da1ed09059988525e4eea68e901701959430ef4215eab5.webp)

If you register the extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), set the `extensions.template` value in your app manifest to `Verify.Version2.PostalAddress`.

This extension has two actions.  The action names you specify when you register an extension app depend on whether you register the app using a form or using an app manifest file. The app manifest file values listed here appear in the `actions.template` property.

| Form-Based Action Name | App Manifest File Value            |
| ---------------------- | ---------------------------------- |
| Verify Postal Address  | `Verify.Version1.PostalAddress`    |
| Address Typeahead      | `Typeahead.Version1.PostalAddress` |
| Address Suggest        | `Suggest.Version1.PostalAddress`   |

You provide the details required for action execution when you register an extension app. See [Update extension and action settings](/extension-apps/build-an-extension-app/register/use-form/integration-details#update-extension-and-action-settings) for information about defining actions using the form-based registration process. See [Action schema](/extension-apps/extension-app-reference/app-manifest-reference/action) for information about action properties in the app manifest file.

## Action contracts

#### Verify Postal Address (Verify.Version1.PostalAddress)

This action returns whether a supplied postal address is valid. The returned properties will be translated into the user’s preferred localization in the UI.

Verify Postal Address is the label for this action that appears when you register an extension app [using a form](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), the `actions.template` property value for this action is `Verify.Version1.PostalAddress`.

### HTTP method

This action initiates a POST request to the external API service.

### Request

```text
{
    "street1": "123 Main Street",
    "locality": "new york",
    "postalCode": "10001",
    "countryOrRegion": "United States",
    "subdivision": "ny"
}
```

| Property              | Type     | Description               |
| --------------------- | -------- | ------------------------- |
| `street1`             | `string` | The first address line.   |
| `street2 (optional)*` | `string` | The second address line.  |
| `locality`            | `string` | The name of the locality. |
| `postalCode`          | `string` | The postal code.          |
| `countryOrRegion`     | `string` | The country or region.    |
| `subdivision`         | `string` | The subdivision.          |

*\*Not always included in the JSON request. Your API proxy must handle the case in which this property is not present.*

### Response

#### Successful case

```text
{
   "verified": true
}
```

#### Unsuccessful case

```text
{
    "verified": false,
    "verifyFailureReason": "Invalid State"
}
```

| Property              | Type      | Occurrence | Description                                                                                               |
| --------------------- | --------- | ---------- | --------------------------------------------------------------------------------------------------------- |
| `verified`            | `boolean` | Required   | Whether the address was successfully verified.                                                            |
| `verifiedAddress`     | `object`  | Optional   | A JSON object representing the address. The current version of the action does not require this property. |
| `verifyFailureReason` | `string`  | Optional   | When `verified` is `false`, provide an explanation of why the action failed.                              |

#### Address Typeahead (Typeahead.Version1.PostalAddress)

Given a postal address, this action should return a list of suggested addresses in corrected formatting. This action should be used for actively suggesting addresses as a user enters their address in order to support autocomplete. Typeahead requires at least 3 numeric characters and one alpha character to provide address suggestions.

Address Typeahead  is the label for this action that appears when you register an extension app [using a form](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), the `actions.template` property value for this action is `Typeahead.Version1.PostalAddress`.

![An image of the address verification UI showing suggested addresses being displayed as a user types.](/_fern-files/_img/8d71921454902b9cba4aea5302d3fb73844ca4d5af6fae21f01121130c0a7c92.webp)

### HTTP method

This action initiates a POST request to the external API service.

### Request

```text
{
    "street1": "123 Main Street",
    "locality": "new york",
    "postalCode": "10001",
    "countryOrRegion": "United States",
    "subdivision": "ny"
}
```

| Property              | Type     | Description               |
| --------------------- | -------- | ------------------------- |
| `street1`             | `string` | The first address line.   |
| `street2 (optional)*` | `string` | The second address line.  |
| `locality`            | `string` | The name of the locality. |
| `postalCode`          | `string` | The postal code.          |
| `countryOrRegion`     | `string` | The country or region.    |
| `subdivision`         | `string` | The subdivision.          |

*\*Not always included in the JSON request. Your API proxy must handle the case in which this property is not present.*

### Response

#### Successful case

```text
{
    "suggestions": [{
        "street1": "123 Main Street",
        "street2": "Apt 1",
        "locality": "New York",
        "postalCode": "10001-0001",
        "countryOrRegion": "United States",
        "subdivision": "NY"
    },
    {
        "street1": "123 Main Street",
        "street2": "Apt 2",
        "locality": "New York",
        "postalCode": "10001-0001",
        "countryOrRegion": "United States",
        "subdivision": "NY"
    }
}
```

#### Unsuccessful case

```text
{
    "failureReason": "No suggestions found"
}
```

| Property        | Type     | Description                                                                                                                                                                                                                      |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `suggestions`   | `array`  | A list of objects representing the reformatted addresses. Each object can have the following properties, all of type `string`:- `street1`
- `street2 (optional)`
- `locality`
- `subdivision`
- `countryOrRegion`
- `postalCode` |
| `failureReason` | `string` | When no suggestions are retrieved, provide an explanation of why the action failed.                                                                                                                                              |

#### Address Suggest (Suggest.Version1.PostalAddress)

Given a postal address, this action should return a list of suggested addresses in corrected formatting similar to the provided address.  It is triggered when a user-supplied address verification fails: a modal is displayed prompting the user to check their address and run Address Suggest.

![An image of the postal address verification UI showing the text displayed when address verification fails, but another address can be suggested.](/_fern-files/_img/00c138584e471dd9105f8674a227f6d876dafb8ce29dc3f05c92ff1b79e3d471.webp)![An image of the postal address verification UI showing an address being suggested to replace the provided invalid address.](/_fern-files/_img/3b95aa8f907351d991a01856f35fbc79b0b80167a1d66ddf3b6239c7f2d24527.webp)

Address Suggest is the label for this action that appears when you register an extension app [using a form](/extension-apps/build-an-extension-app/register/use-form). If you register your extension app [using an app manifest file](/extension-apps/build-an-extension-app/register/use-manifest), the `actions.template` property value for this action is Suggest.Version1.PostalAddress.

#### HTTP method

This action initiates a POST request to the external API service.

### Request

```text
{
    "street1": "123 Main Street",
    "locality": "new york",
    "postalCode": "10001",
    "countryOrRegion": "United States",
    "subdivision": "ny"
}
```

| Property              | Type     | Description               |
| --------------------- | -------- | ------------------------- |
| `street1`             | `string` | The first address line.   |
| `street2 (optional)*` | `string` | The second address line.  |
| `locality`            | `string` | The name of the locality. |
| `postalCode`          | `string` | The postal code.          |
| `countryOrRegion`     | `string` | The country or region.    |
| `subdivision`         | `string` | The subdivision.          |

*\*Not always included in the JSON request. Your API proxy must handle the case in which this property is not present.*

### Response Successful case

```text
{
    "suggestions": [{
        "street1": "123 Main Street",
        "street2": "Apt 1",
        "locality": "New York",
        "postalCode": "10001-0001",
        "countryOrRegion": "United States",
        "subdivision": "NY"
    },
    {
        "street1": "123 Main Street",
        "street2": "Apt 2",
        "locality": "New York",
        "postalCode": "10001-0001",
        "countryOrRegion": "United States",
        "subdivision": "NY"
    }
}
```

### Unsuccessful case

```text
{
    "failureReason": "No suggestions found"
}
```

| Property        | Type     | Description                                                                                                                                                                                                                      |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `suggestions`   | `array`  | A list of objects representing the reformatted addresses. Each object can have the following properties, all of type `string`:- `street1`
- `street2 (optional)`
- `locality`
- `subdivision`
- `countryOrRegion`
- `postalCode` |
| `failureReason` | `string` | When no suggestions are retrieved, provide an explanation of why the action failed.                                                                                                                                              |