Authenticating Signers
To add an extra layer of security to your online transactions, Sign offers robust and flexible recipient-authentication options. Specifically, you can select various ways of validating the identity of the recipient of an invitation to a transaction before they are permitted to access the transaction's documents.
General Authentication refers to tools built into Conga Sign that enable you to verify the identity of the recipient through SMS, Email, or a custom Question and Answer format.
Knowledge-Based Authentication (KBA) relies on a third-party KBA provider to perform the authentication. That provider is either Equifax US or Equifax Canada.
KBA questions are generated dynamically, based on information in a signer's personal credit report.
KBA authentication can be used in conjunction with any one of the General authentication methods above.
Using General Authentication
The code below illustrates how to edit the auth object for each authentication method. If you need a comparison with basic document-object creation, or if this is your first time creating a package with the Java SDK, see this Creating a Transaction.
HTTP Request
POST <host domain>/api/sign/v1/cs-packages
HTTP Headers
Accept: application/json Content-Type: application/json Authorization: Bearer access_token
Request Payload
{ "roles": [ { "type": "SIGNER", "index": 0, "signers": [ { "auth": { "scheme": "CHALLENGE", "challenges": [ { "answer": "golf", "question": "What's your favorite sport?", "maskInput": false } ] }, "email": "john.smith@example.com", "firstName": "John", "lastName": "Smith" } ], "name": "Signer1" }, { "type": "SIGNER", "index": 0, "signers": [ { "auth": { "scheme": "SMS", "challenges": [ { "answer": null, "question": "+15515584587", "maskInput": false } ] }, "email": "mary.doe@example.com", "firstName": "Mary", "lastName": "Doe" } ], "name": "Signer2" } ], "status": "DRAFT", "type": "PACKAGE", "name": "Signer Authentication Example" }For a complete description of each field, see the Request Payload Table section below.
Response Payload
{ "id": "9sKhW-h-qS9m6Ho3zRv3n2a-rkI=" } Manually sending an SMS code
A new SMS code is generated and sent each time a signer clicks the email link. If for any reason you need to manually send a new SMS code, the following code will do this:
HTTP Request
POST <host domain>/api/sign/v1/cs-packages/{packageId}/roles/{roleId}/sms_notificationHTTP Headers
Accept: application/json Content-Type: application/json Authorization: Bearer access_token
Using KBA
You can also authenticate a signer with KBA. The sample JSON string below shows you how to edit the signer's object with KBA. The withTimeAtAddress field can be left empty. The following code will do this:
{ "signers":[ { "delivery":{ "email":false }, "email":"signer1@example.com", "firstName":"John", "lastName":"Doe", "auth":{ "scheme":"NONE", "challenges":[ ] }, "knowledgeBasedAuthentication":{ "signerInformationForEquifaxUSA":{ "firstName":"John", "lastName":"Doe", "streetAddress":"2020 Broadway Street", "city":"New York", "zip":"12345", "state":"NY", "timeAtAddress":5, "driversLicenseNumber":"1234567890", "dateOfBirth":"1969-12-09T00:00:00Z", "socialSecurityNumber":"123456789", "homePhoneNumber":"1234567890" } } } ], "reassign":false, "emailMessage":{ "content":"" }, "attachmentRequirements":[ ] }
Request Payload Table
|
Property |
Type |
Editable |
Required |
Default |
Sample Values |
|---|---|---|---|---|---|
|
status |
string |
Yes |
No |
DRAFT |
|
|
type |
string |
Yes |
No |
PACKAGE |
|
|
name |
string |
Yes |
No |
n/a |
|
|
roles |
|||||
|
type |
string |
Yes |
No |
SIGNER |
|
|
index |
index |
Yes |
No |
0 |
0/1/2 ... |
|
name |
string |
Yes |
No |
n/a |
|
|
signers |
|||||
|
|
string |
Yes |
No |
n/a |
|
|
firstName |
string |
Yes |
No |
n/a |
|
|
lastName |
string |
Yes |
No |
n/a |
|
|
auth |
|||||
|
scheme |
string |
Yes |
No |
n/a |
|
|
challenges |
|||||
|
answer |
string |
Yes |
No |
n/a |
|
|
question |
string |
Yes |
No |
n/a |
|
|
maskInput |
boolean |
Yes |
No |
false |
|
