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.
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.
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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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.
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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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.
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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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>
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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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>
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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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>
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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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>
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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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>
In most cases, the standard SubmitDocument call can be used to add all documents to a transaction at once. However, there may be cases where the integrator wishes to only upload one document at a time or may need to comply with specific application limitations on API request size. In this case, the AJAX calls below can be used.
There are specific prerequisites to the use of these calls:
<?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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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": "Library_CreateDocument",
"mimeType": "application/pdf",
"fileName": "Portrait_LB.pdf",
"title": "Portrait_LB",
"documentBytes64": "JVBERi0xLjcNCiW1tbW1DQoxIDAgb2JqDQo8P..."
}
</Request> The "fileName" and "title" properties are technically optional, but HIGHLY recommended as they populate UX elements during signing, and may confuse the signer during the signing experience if omitted. The "documentBytes64" property must include the base64 encoded string of the PDF document. See the SubmitDocument request for additional information.
</Data>
</SubmitAjaxRq>
Note that the Response here is extremely important to store and keep track of, as it will provide you with a PDF ID that will be used in the follow-up call, we well as later calls to download the documents.
<?xml version="1.0" ?>
<SubmitAjaxRs xmlns="urn:com:signix:schema:sdddc-1-1">
<Status>
<StatusCode>0</StatusCode>
<StatusDesc>success</StatusDesc>
</Status>
<Data>
<Response>{"id":"PDF:18b39c97c76:-7b52:-38a0d2b0:-hkq0ax","objectType":"ObjectCreated"}</Response>
</Data>
</SubmitAjaxRs>
<?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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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",
"id":"18b39c97c76:-7b70:-38a0d2b0:-hkq0a0", Required. DocumentSetID.
"deltas":[
{
"objectType": "Transaction_CreateDocument",
"document": {
"objectType": "TransactionDocument",
"id": "18b39c97c76:-7b70:-38a0d2b0:-hkq0a0", Required. DocumentSetID.
"documentId": "PDF:18b39c97c76:-7b38:-38a0d2b0:-hkq0ax", Required. PDF ID from the previous response.
"refId": "LB", Required. Similar to the RefID from SubmitDocument.
"title": "Portrait_LB", Required. Set to exact same as "title" from Library_CreateDocument call above.
"fileName": "Portrait_LB.pdf" Required. Set to exact same as "fileName" from Library_CreateDocument call above.
}
}
]
</Request>
</Data>
</SubmitAjaxRq>
<?xml version="1.0" ?>
<SubmitAjaxRs xmlns="urn:com:signix:schema:sdddc-1-1">
<Status>
<StatusCode>0</StatusCode>
<StatusDesc>success</StatusDesc>
</Status>
<Data>
<Response>{"error":null,"id":null,"objectType":"TransactionDeltas","postDeltas":[null],"preDeltas":null}</Response>
</Data>
</SubmitAjaxRs>
For this, only one call is necessary.
<?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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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",
"id":"18b39c97c76:-7b70:-38a0d2b0:-hkq0a0", Required. DocumentSetID.
"deltas":[
{
"objectType": "Transaction_DropDocument",
"id": "PDF:18b39c97c76:-7b38:-38a0d2b0:-hkq0ax", Required. PDF ID from the previous response - NOT DocumentSetID.
"dropTasks":{
"objectType": "Bool","value":true
}
}
]
}
</Request>
</Data>
</SubmitAjaxRq>
Note that after downloading all documents from the transaction, SIGNiX strongly recommends that the integrator call the typical SIGNiX DownloadDocument and ConfirmDocument calls to inform SIGNiX that all documents have been properly downloaded and custom retention policies can be implemented.
<?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>18b39c97c76:-7b70:-38a0d2b0:-hkq0a0</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": "Document_Download",
"documentId": "PDF:18b39c97c76:-7b38:-38a0d2b0:-hkq0ax" Required. Reference the PDF Id from Library_CreateDocument Response
}
</Request>
</Data>
</SubmitAjaxRq>
<?xml version="1.0" ?>
<SubmitAjaxRs xmlns="urn:com:signix:schema:sdddc-1-1">
<Status>
<StatusCode>0</StatusCode>
<StatusDesc>success</StatusDesc>
</Status>
<Data>
<Response>
{
"contentType": "application/pdf",
"data": "JVBERi0xLjcNCiW1tbW1DQoxIDAgb2JqDQo8P...", Base64 encoded document string.
"fileName": "Portrait_LB.pdf",
"objectType": "File"
}
</Response>
</Data>
</SubmitAjaxRs>
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.
"This transaction has already been suspended and cannot be suspended again."
"This transaction has already been completed and cannot be suspended."
“This transaction has already been completed and cannot be resumed."
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.")
