Skip to navigation

SSN verification extension contract reference

View as Markdown

The SSN verification extension enables real-time verification of an individual’s Social Security number. This extension can only be used to verify a Social Security number issued by the United States Social Security Administration to U.S. citizens and residents.

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 Social Security Number.

SSN verification extension in form-based registration

If you register the extension app using an app manifest file, set the extensions.template value in your app manifest to Verify.Version3.SocialSecurityNumber.

This extension has one action. The action name you specify when you register an extension app depends on whether you register the app using a form or using an app manifest file. The app manifest file value listed here appears in the actions.template property.

Form-Based Action NameApp Manifest File Value
Verify Social Security NumberVerify.Version3.SocialSecurityNumber

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

This contract describes the parameters that Docusign will pass to the external SSN verification service as well as the parameters expected in the response. You specify the URL for the verification service in the form-based UI or in the extension app manifest.

Verify Social Security Number 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.Version3.SocialSecurityNumber.

HTTP method

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

Request

{
"socialSecurityNumber": "123-45-6789",
"firstName": "Francis",
"lastName": "Beagle",
"dateOfBirth": "2015-10-09"
}
PropertyTypeDescription
socialSecurityNumberstringThe nine-digit social security number.
firstNamestringThe first name of the individual.
lastNamestringThe last name of the individual.
dateOfBirthstringThe date of birth of the individual.

Response

Successful case

{
"verified": true,
"responseCode": 'VERIFIED',
"providerResponseCode": 'OK',
}
Unsuccessful case
{
"verified": false,
"responseCode": 'NOT_VERIFIED',
"providerResponseCode": 'FAILED_BECAUSE_REASONS',
}
PropertyTypeOccurrenceDescription
verifiedbooleanRequiredWhether the social security number was successfully verified.
responseCodestringRequiredContains a code that indicates the type of response. If verification failed, this code will contain an error code.
providerResponseCodestringOptionalContains response code produced from the app indicating the reasons for success or failure.