AJAX API Transaction Controls

While the main FlexAPI calls allow you to handle sending transactions, downloading documents and popping up the SIGNiX interface in your application, SIGNiX also allows you to control aspects of in-progress, individual transactions without having to send users to the Wizard in GetAccessLink-Submitter calls. In other words, you can programmatically change elements like a incorrect signer email or mobile phone number, resend a pickup link email or even suspend and cancel a transaction.

digital signature faq

Contents


digital signature faq

 

Sessionless API Request Format

The sessionless API is part of the SIGNiX B2B interface. This method works like other methods in this API. Since requests like this one contain your corporate user ID and password, you must always send them from a secure server, and never from a Web page. There are two forms of this method, single request and multi-request. In both forms, if the JSON request causes changes to a transaction, the changes are automatically saved. It is not necessary to send any explicit save request. In the sessionless API, the transaction is set up and closed once for each B2B request. In addition, it is not necessary to log out of the sessionless B2B API. Each request in this API automatically opens its own isolated session on a transaction, runs its batch of Embedding API requests, saves the working copy if there were updates, and logs out. It is not necessary to include any save or logout commands in the batch of Embedding API requests.

SIGNiX also offers a session-based API, which information can be provided from SIGNiX directly.

 

Single Request/Response Format

This format can be used to send a single JSON request. The SubmitAjax method is called as follows:

 

 

<?xml version="1.0" ?>
<SubmitAjaxRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo>                          Occurs once only

<Sponsor>oem</Sponsor>            Assigned by SIGNiX When Client is set up (Case Sensitive)

<Client>oemclient</Client>       Assigned by SIGNiX when Client is set up (Case Sensitive)

<UserId>oemclient</UserId>        Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

<Data>                  Occurs once only


<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID> Identifies the document set with an opaque identifier. This value is the same as the unique <DocumentSetID> value included in the original SubmitDocument response. Note that <TransactionID> can also be used here.

OR

<TransactionID>aefd45aa-6a36-4ab5-8cc8-4dc6e895fa21</TransactionID> Required. Length must be exactly 36 characters

<Request>...XML-Encoded JSON...</Request>

 

</Data>

 

</SubmitAjaxRq>

 

When the <Data> element of the B2B request contains a singleton <Request> element, the <Data> section of the B2B response contains a single <Response> element as follows:


<?xml version="1.0" ?>
<SubmitAjaxRs xmlns="urn:com:signix:schema:sdddc-1-1">

<Status>

<StatusCode>0</StatusCode>
<StatusDesc>success</StatusDesc>

</Status>

 

<Data>

<Response>...XML-Encoded JSON Response...</Response>

</Data>

 

</SubmitAjaxRs>

 

In case of failure, the StatusCode will be non-zero and the Data section will be absent. See the AJAX Status Codes section below for more information on failure codes.


The StatusCode indicates only whether or not the server received and ran the JSON request. The outcome of the request itself is indicated by the JSON response.

 

[Back to top]

 

Multiple Request Format

This format allows multiple JSON requests to be sent in a single API request.

IMPORTANT: Do NOT send requests that rely on being completed in sequential order when sending in a multiple request format. Only requests that do not need to be run sequentially should be included in the multiple request format. For example, sending a Suspend, Edit Email AND Resume all in one AJAX request is NOT supported, as those requests may not be executed in sequential order, causing a myriad of possible errors. Rather, use the single request format for items like Suspend, Resume and Cancel.

The SubmitAjax method is called as follows:

 

<?xml version="1.0" ?>
<SubmitAjaxRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo>                          Occurs once only

<Sponsor>oem</Sponsor>            Assigned by SIGNiX When Client is set up (Case Sensitive)

<Client>oemclient</Client>       Assigned by SIGNiX when Client is set up (Case Sensitive)

<UserId>oemclient</UserId>        Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

<Data>                  Occurs once only


<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID> Identifies the document set with an opaque identifier. This value is the same as the unique <DocumentSetID> value included in the original SubmitDocument response. Note that <TransactionID> can also be used here.

OR

<TransactionID>aefd45aa-6a36-4ab5-8cc8-4dc6e895fa21</TransactionID> Required. Length must be exactly 36 characters

<Requests> As specified above, only include requests in this format that do not rely on execution in a sequential order.

<Request>...XML-Encoded JSON for Request 1 (i.e. Change signer email)...</Request>

<Request>...XML-Encoded JSON for Request 2 (i.e. Change signer mobile number)...</Request>

...

</Requests>

 

</Data>

 

</SubmitAjaxRq>

 

The response for this format is as follows:

 

<?xml version="1.0" ?>
<SubmitAjaxRs xmlns="urn:com:signix:schema:sdddc-1-1">

<Status>

<StatusCode>0</StatusCode>
<StatusDesc>success</StatusDesc>

</Status>

<Data>

<Responses>

<!-- Note that all responses are XML-encoded JSON -->
<Response responseCode="0" responseDesc="success">...Request 1 response...</Response>
<Response responseCode="0" responseDesc="success">...Request 2 response...</Response>
...

</Responses>

</Data>

</SubmitAjaxRs>

 

The XML response has the following features:
· There is a Response element for each JSON request, listed in the same order as the requests.
· Each response contains attributes that describe whether the corresponding request succeeded or failed.
· The status of the B2B response indicates the overall result of the individual JSON requests.

 

The StatusCode of the B2B response has the following meaning.
· 0: All JSON requests were processed and returned non-error responses.
· 2: One or more JSON requests were processed. The last one processed failed, and any following it were not processed. There will be response elements for each request up to and including the one that failed. Requests after the failed request were not run, and no responses are included for them. The working copy is not saved, so any successful updates were rolled back.
· >=100: The XML request failed before any JSON was processed. The Data element will not be present.

 

Each <Response> element has a responseCode attribute, with the following meanings:
0: The JSON for this request was processed and returned a non-error response. The JSON response is in the element content.
· 2: The JSON for this request was processed, but returned an error. The JSON error response is in the element content. No further requests were executed after this one.
· >=100: This request failed before its JSON was processed. No further requests were executed after this one.

 

[Back to top]

digital signature faq

 

 

Cancel Transaction

This function is used when there is a need to cancel (void) a transaction.

 

<?xml version="1.0" ?>
<SubmitAjaxRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo>                          Occurs once only

<Sponsor>oem</Sponsor>            Assigned by SIGNiX When Client is set up (Case Sensitive)

<Client>oemclient</Client>       Assigned by SIGNiX when Client is set up (Case Sensitive)

<UserId>oemclient</UserId>        Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

<Data>                  Occurs once only


<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID> Identifies the document set with an opaque identifier. This value is the same as the unique <DocumentSetID> value included in the original SubmitDocument response. Note that <TransactionID> can also be used here.

OR

<TransactionID>aefd45aa-6a36-4ab5-8cc8-4dc6e895fa21</TransactionID> Required. Length must be exactly 36 characters

<Request>{'objectType':'Transaction_Cancel'</Request> 

 

</Data>

 

</SubmitAjaxRq>

 

 

[Back to top]

 

digital signature faq

 

 

 

Suspend / Resume Transaction

This function is used when there is a need to suspend or resume a transaction.

 

<?xml version="1.0" ?>
<SubmitAjaxRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo>                          Occurs once only

<Sponsor>oem</Sponsor>            Assigned by SIGNiX When Client is set up (Case Sensitive)

<Client>oemclient</Client>       Assigned by SIGNiX when Client is set up (Case Sensitive)

<UserId>oemclient</UserId>        Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

<Data>                  Occurs once only


<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID> Identifies the document set with an opaque identifier. This value is the same as the unique <DocumentSetID> value included in the original SubmitDocument response. Note that <TransactionID> can also be used here.

OR

<TransactionID>aefd45aa-6a36-4ab5-8cc8-4dc6e895fa21</TransactionID> Required. Length must be exactly 36 characters

<Request>{'objectType':'Transaction_Suspend'</Request> 

OR

<Request>{'objectType':'Transaction_Resume'</Request> 

 

</Data>

 

</SubmitAjaxRq>

 

 

[Back to top]

 

digital signature faq

 

Change Signer Email

This function is used when there is a need to modify a specific signer's email address in an in-process SIGNiX transaction. Note that changing the email address via this function only changes it in this transaction and of course does not change information in other systems of record.

 

<?xml version="1.0" ?>
<SubmitAjaxRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo>                          Occurs once only

<Sponsor>oem</Sponsor>            Assigned by SIGNiX When Client is set up (Case Sensitive)

<Client>oemclient</Client>       Assigned by SIGNiX when Client is set up (Case Sensitive)

<UserId>oemclient</UserId>        Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

<Data>                  Occurs once only


<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID> Identifies the document set with an opaque identifier. This value is the same as the unique <DocumentSetID> value included in the original SubmitDocument response. Note that <TransactionID> can also be used here.

OR

<TransactionID>aefd45aa-6a36-4ab5-8cc8-4dc6e895fa21</TransactionID> Required. Length must be exactly 36 characters

<Request>{ "objectType":"Transaction_SaveDeltas","deltas":[ {"objectType":"Transaction_UpdateRole","role": {"id": "REF112233","objectType": "TransactionRole","party": {"objectType":"PersonData","emailAddressTable": {"REF112233": {"address": "AAAAAAAAAAAAA@test.com","objectType": "EmailAddress","type": "Home"} } } } }]}</Request> Note that "id" refers to the RefID of the party in question, based on the original SubmitDocument call, and the email specified in this request is the NEW email, not the ORIGINAL. IMPORTANT: Although the request grammar is similar, do NOT attempt to change both email and phone number in the same "Transaction_SaveDeltas" statement. Only one element of a party/signer should be changed in a single request.

 

</Data>

 

</SubmitAjaxRq>

 

 

[Back to top]

 

digital signature faq

 

 

Re-send Signer Pickup Email

This function is best used after changing a signer's email to let the signer at the updated email address know they have documents to review and sign.

 

<?xml version="1.0" ?>
<SubmitAjaxRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo>                          Occurs once only

<Sponsor>oem</Sponsor>            Assigned by SIGNiX When Client is set up (Case Sensitive)

<Client>oemclient</Client>       Assigned by SIGNiX when Client is set up (Case Sensitive)

<UserId>oemclient</UserId>        Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

<Data>                  Occurs once only


<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID> Identifies the document set with an opaque identifier. This value is the same as the unique <DocumentSetID> value included in the original SubmitDocument response. Note that <TransactionID> can also be used here.

OR

<TransactionID>aefd45aa-6a36-4ab5-8cc8-4dc6e895fa21</TransactionID> Required. Length must be exactly 36 characters

<Request>{"objectType":"Transaction_SendPartyEmail","includeLink":true,"subject":"","message":"","transactionId":"","to":[{"objectType":"TxRoleAddressee","Id":"First Signer","name":"","emailAddress":""}]}</Request> The subject and message can be customized if needed, but if nothing is added, the subject and message will default to those in the standard pick-up email sent to all signers.   Note that "id" refers to the RefID of the party in question, based on the original SubmitDocument call.

 

</Data>

 

</SubmitAjaxRq>

 

 

[Back to top]

digital signature faq

 

 

Change Signer Mobile Phone Number

This function is used when there is a need to modify a specific signer's mobile phone number in an in-process SIGNiX transaction for the purposes of authentication, for example. Note that changing the mobile number via this function only changes it in this transaction and of course does not change information in other systems of record.

 

<?xml version="1.0" ?>
<SubmitAjaxRq xmlns="urn:com:signix:schema:sdddc-1-1">

<CustInfo>                          Occurs once only

<Sponsor>oem</Sponsor>            Assigned by SIGNiX When Client is set up (Case Sensitive)

<Client>oemclient</Client>       Assigned by SIGNiX when Client is set up (Case Sensitive)

<UserId>oemclient</UserId>        Assigned by SIGNiX when Client is set up (Case Sensitive)

<Pswd>your-password-here</Pswd> Assigned by SIGNiX when Client is set up (Case Sensitive)

</CustInfo>

<Data>                  Occurs once only


<DocumentSetID>-147fb68b:1043a5db9ca:-7f5fid11or</DocumentSetID> Identifies the document set with an opaque identifier. This value is the same as the unique <DocumentSetID> value included in the original SubmitDocument response. Note that <TransactionID> can also be used here.

OR

<TransactionID>aefd45aa-6a36-4ab5-8cc8-4dc6e895fa21</TransactionID> Required. Length must be exactly 36 characters

<Request>{"objectType": "Transaction_SaveDeltas","deltas": [{"objectType": "Transaction_UpdateRole","role": {"id": "P01","objectType": "TransactionRole","party": {"objectType": "PersonData","phoneTable": {"Mobile1": {"objectType": "PhoneNumber","id": "Mobile","type": "","number": "2221231234"}}}}}]}</Request> Note that "id" refers to the RefID of the party in question, based on the original SubmitDocument call, and the PhoneNumber specified in this request is the NEW number, not the ORIGINAL. IMPORTANT: Although the request grammar is similar, do NOT attempt to change both email and phone number in the same "Transaction_SaveDeltas" statement. Only one element of a party/signer should be changed in a single request.

 

</Data>

 

</SubmitAjaxRq>

 

 

[Back to top]

 

 

digital signature faq

 

AJAX Status Codes

In addition to the typical Status Codes shown on the main FlexAPI documentation page, AJAX calls also may have their own unique Response Values, as shown below.

 

RESPONSE VALUES

  • SC_OK = 0
  • SC_SUCCESS_WITH_WARNING = 1 (StatusMessage and Data section may provide more info)
  • SC_PARTIAL_SUCCESS = 2 (Data section should indicate what succeeded and what failed)

 

WARNINGS - SUSPEND

"This transaction has already been suspended and cannot be suspended again."
"This transaction has already been completed and cannot be suspended."

 

WARNINGS - RESUME

“This transaction has already been completed and cannot be resumed."

 

WARNINGS - CANCEL

When Transaction has ‘Expired’ Status:
"This transaction has expired and cannot be cancelled."


When Transaction has ‘Cancelled’ Status:
"This transaction has cancelled and cannot be cancelled."


When Transaction has ‘Complete’ Status:
"This transaction has already been completed and cannot be cancelled.")

 

 

 

 

 

 

[Back to top]