Postal address verification extension contract reference | Docusign

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.

This extension verifies specific types of values. See Connected fields extension overview 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. If you register the extension app using a 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

If you register the extension app using an app manifest file, 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 for information about defining actions using the form-based registration process. See Action schema 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. If you register your extension app using an app manifest file, 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

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

{
   "verified": true
}

Unsuccessful case

{
    "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. If you register your extension app using an app manifest file, 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.

HTTP method

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

Request

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

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

{
    "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.

An image of the postal address verification UI showing an address being suggested to replace the provided invalid address.

Address Suggest is the label for this action that appears when you register an extension app using a form. If you register your extension app using an app manifest file, 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

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

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

{
    "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.