OneSpan Sign Developers: Manage Sender’s Transactions – Part 2

Admin Accounts are for those entrusted with administering the Application, which empowers the admin to do much more than regular senders. These privileges include managing other sender’s transactions, checking the signing status, downloading signed documents, and so on. 

In the Part 1 blog, we explored how to grant your admin user proper permissions and send transactions on their behalf. We will continue where we left off and walk through more operations you can do to manage other senders’ transactions. Without further delay, let’s get started!

Managing Senders’ Transactions

To manage all your senders’ transactions, make sure the admin user has been granted proper permissions:

• If your account has the Roles & Permissions feature enabled, make sure the admin user has been assigned an account role with at least “API Access” and “Manage users' transactions, templates, layouts (API)” permissions
• Otherwise, grant manager rights to your admin user as shown in the screenshot below

If you have a transaction ID by hand, no matter if the transaction was created by another sender or by an admin on the sender’s behalf, you will have direct API access to the transaction if you authenticate your API/SDK call as the admin user:

HTTP Request

GET /api/packages/{packageId}

HTTP Headers

Authentication: Basic {api_key} / Bearer {api_token}
Accept: application/json

Since the admin user has full access to the transaction resource, you’ll be able to invoke other APIs under the “/api/packages” endpoint, such as updating an existing signer’s information:

HTTP Request

PUT /api/packages/{packageId}/roles/{roleId}

HTTP Headers 

Authentication: Basic {api_key} / Bearer {api_token}
Accept: application/json   
Content-Type: application/json   

Request Payload

{
  "type": "SIGNER",
  "signers": [
    {
      "email": "[email protected]",
      "firstName": "Mary",
      "lastName": "Doe"
    }
  ]
}

Or to download signed documents:

HTTP Request

GET /api/packages/{packageId}/documents/zip

HTTP Headers

Authentication: Basic {api_key} / Bearer {api_token}
Accept: application/zip 

List All Transactions

However if you didn’t record the transaction ID locally, you will still be able to list all the transactions created by a certain sender:

HTTP Request

GET /api/packages?from=1&to=100&ownerUserId={sender_id}
GET /api/packages?from=1&to=100&ownerEmail={sender_email}

HTTP Headers

Authentication: Basic {api_key} / Bearer {api_token}
Content-type: application/json
Accept: application/json

Parameter

• ownerUserId & ownerEmail: By default, this API call only returns transactions of the API caller. However, when specifying either the ownerUserId or ownerEmail as a query parameter, this API will return the transactions of the specified user.

The example above gives you a brief idea how to build the API URL. There are actually more parameters which give you extra flexibilities of retrieving a sender’s transactions:

• query: Query a certain status of transactions. The available values are ARCHIVED, COMPLETED, DRAFT, SENT, EXPIRED, OPTED_OUT, DECLINED, and TRASHED. The TRASH action doesn’t count for a transaction status. Considering responses of other statuses will exclude the TRASH transaction, you still have to search trashed transactions with this parameter.
• from & to: Specify the number of transactions returned for the purposes of pagination. For example, if your page size is 100, your query could be “&from=1&to=100”, “&from=101&to=200”, and so on. A maximum of 100 transactions can be returned in a single call. 
• lastUpdatedStartDate & lastUpdatedEndDate: Returns transactions that are last updated within this time range. Queries are precise to the day, and the date format should follow “yyyy-MM-dd”.
• search & searchtype: The keyword of the “search” parameter will be used to search transaction name or description, or a signer’s first/last name and the email address. In conjunction with “searchtype”, the API caller can choose whether to do the wild-card search (when searchtype is empty), or more restrictive search (when searchtype is “exact” or “exactname”).

We Appreciate Your Feedback

This concludes today’s blog. As long as you have granted the admin user sufficient permissions, it saves you the complexity of retrieving individual sender’s API key and allows for direct control over other sender’s transactions. Learning the best practices covered in this blog could be extremely helpful when managing your account users’ transactions.

If you have any questions regarding this blog or anything else concerning the integration of OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today