r-mikolajuk

Full REST API documentation

0 votes
Hi! Do you have anywhere online full REST API documentation with all possible request payload fields defined? For example, there is a http://docs.e-signlive.com/doku.php?id=esl:api:e-signlive_templates#post_packages_packageid_clone (POST /packages/{packageId}/clone) but the list of fields is very basic. I found https://www.esignlive.com/blog/e-signlive-for-new-users-how-to-create-and-send-your-first-package-rest-api/ where there is more fields in example. But couldn't find any place where they all are listed and described.

Approved Answer

Reply to: Full REST API documentation

0 votes
What is the exact JSON you sent with your latest clone request? Your documents and everything for your package is already defined in your template. You shouldn't need to do anything with those, if you're just replacing your placeholder "Signer".

- Michael

Director, Partner and Developer Technologies, OneSpan

Facebook - Twitter - LinkedIn


Reply to: Full REST API documentation

0 votes
Unfortunately, no, we don't have a listing of all the properties somewhere with descriptions of all of them. This is something that we'll be looking at, in the near future, at least with the developer community. Documentation is also something that we're always looking at improving, and I agree that what you're looking for would be very nice to have. It won't get you a description of each property, but one thing you could do would be to create a package through the API or UI and then GET that package through the REST API. This should return you the full package payload, with all of the different settings. Posting questions in the developer community (as you just did), would be a good way to get clarification on a particular property, until there is a resource available to describe every property in detail. Let me know if there is something particular you're trying to figure out with the JSON payload.

- Michael

Director, Partner and Developer Technologies, OneSpan

Facebook - Twitter - LinkedIn


Reply to: Full REST API documentation

0 votes
Thank you for your fast response. The documentation for the REST API in my opinion is crucial, because without it coding looks like hacking your system ;) I'm having problems with POST /packages/{packageId}/clone I've prepared template, with additional fields (screen esignlive_fields.png) for signer to be defined later (screen esignlive_template.png). Unfortunatelly I'm getting this error:

HTTP/1.1 400 Bad Request
Connection: keep-alive
Content-Type: application/json
Server: nginx
Transfer-Encoding: chunked
X-Powered-By: Undertow 1

{
    "code": 400, 
    "entity": null, 
    "message": "There is a role with no signer.", 
    "messageKey": "error.validation.packageActivation.unassignedRole", 
    "name": "Validation Error", 
    "packageId": null, 
    "technical": null
}
I'm sending this values:

{
    "autocomplete": true, 
    "description": "Agreement", 
    "documents": [
        {
            "approvals": [
                {
                    "accepted": null, 
                    "data": null, 
                    "name": "", 
                    "role": "Signer", 
                    "signed": null
                }, 
                {
                    "accepted": null, 
                    "data": null, 
                    "name": "", 
                    "role": "Signer", 
                    "signed": null
                }
            ]
        }
    ], 
    "due": null, 
    "emailMessage": "Test content", 
    "language": "en", 
    "name": "TEST", 
    "roles": [
        {
            "attachmentRequirements": [], 
            "data": null, 
            "emailMessage": {
                "content": "Test content"
            }, 
            "id": "Signer", 
            "index": 0, 
            "locked": false, 
            "name": "Signer", 
            "reassign": false, 
            "signers": [
                {
                    "address": null, 
                    "auth": {
                        "challenges": [], 
                        "scheme": "NONE"
                    }, 
                    "company": "", 
                    "data": null, 
                    "delivery": {
                        "download": true, 
                        "email": false, 
                        "provider": false
                    }, 
                    "email": "[email protected]", 
                    "external": null, 
                    "firstName": "Test", 
                    "group": null, 
                    "id": "Signer", 
                    "knowledgeBasedAuthentication": null, 
                    "language": "en", 
                    "lastName": "user", 
                    "name": "", 
                    "phone": "", 
                    "professionalIdentityFields": [], 
                    "signature": null, 
                    "specialTypes": [], 
                    "title": "", 
                    "userCustomFields": []
                }
            ], 
            "specialTypes": [], 
            "type": "SIGNER"
        }
    ], 
    "settings": {
        "ceremony": {
            "inPerson": false
        }
    }, 
    "status": "SENT", 
    "type": "PACKAGE"
}
I can't find it in docs, so let me ask here. - Do I need to pass all custom fields added in template? - What parameters are required to pass the validation? - What is the documents section for? I've defined two documents in my template (default plus added by me), do I need to define approvals for both of them in the request? - Should I set the Signer id to [Signer] as this is how it's shown in the panel?

Attachments

Reply to: Full REST API documentation

0 votes
Okay. Let me take a look at this. I'll recreate your setup and let you know. :)

- Michael

Director, Partner and Developer Technologies, OneSpan

Facebook - Twitter - LinkedIn


Reply to: Full REST API documentation

0 votes
Okay. All you need to pass to get a template like the one you have is something like this:
{
  "roles": [
    {
      "id": "23891037-97af-4e01-b1dd-fe0d73874e25", //this is not "Signer" as you defined the user's name. The role actually has an id. You can grab this from the template or cloned package (if you do status of DRAFT)
      "signers": [
        {
          "firstName": "Test",
          "lastName": "user",
          "email": "[email protected]",
          "specialTypes": []
        }
      ],
      "name": "Signer"
    }
  ],
  "status": "SENT"
}
Anything else you want to add like a name for the package and message info for the signer can then be added on top of this. BTW, I grabbed the role by grabbing the template and simply finding the roleId and put it statically into my JSON payload. You can obviously find this with the API as well, but should work static, since it will always be the same coming from the template you're cloning. Hope this helps. Let me know if you have questions.

- Michael

Director, Partner and Developer Technologies, OneSpan

Facebook - Twitter - LinkedIn


Reply to: Full REST API documentation

0 votes
Thank you very much. That helped with the error I was having. But... There is another one:

HTTP/1.1 400 Bad Request
Connection: keep-alive
Content-Type: application/json
Date: Wed, 16 Mar 2016 21:22:53 GMT
Server: nginx
Transfer-Encoding: chunked
X-Powered-By: Undertow 1

{
    "code": 400, 
    "entity": null, 
    "message": "Cannot send package without approvals.", 
    "messageKey": "error.validation.sendPackage.noApprovals", 
    "name": "Validation Error", 
    "packageId": null, 
    "technical": null
}
I've fetched the JSON for the template, there is a section with approvals:

"documents": [
        {
            "approvals": [], 
            "data": null, 
            "description": "Must be accepted and agreed to before starting the signing process.", 
            "external": null, 
            "extract": false, 
            "fields": [], 
            "id": "default-consent", 
            "index": 0, 
            "name": "Electronic Disclosures and Signatures Consent", 
            "pages": [
                {
                    "height": 1030.0, 
                    "id": "default-consent_1.png", 
                    "index": 0, 
                    "left": 0.0, 
                    "top": 0.0, 
                    "version": 185499, 
                    "width": 796.0
                }
            ], 
            "size": 0, 
            "status": ""
        }, 
        {
            "approvals": [
                {
                    "accepted": null, 
                    "data": null, 
                    "fields": [
                       // List of custom fields defined
                    ], 
                    "id": "mSoe6kk2fF08", 
                    "name": "", 
                    "role": "951818c4-a318-4d6b-af76-8f75834c3b07", 
                    "signed": null
                }
            ], 
So there are two documents (the default one and this added by me). So I tried with this payload:

"documents": [
        {
            "approvals": [
                {
                    "accepted": null, 
                    "data": null, 
                    "name": "", 
                    "role": "951818c4-a318-4d6b-af76-8f75834c3b07", 
                    "signed": null
                }
            ]
        }, 
        {
            "approvals": [
                {
                    "accepted": null, 
                    "data": null, 
                    "name": "", 
                    "role": "951818c4-a318-4d6b-af76-8f75834c3b07", 
                    "signed": null
                }
            ]
        }
    ], 
With no success. I found this on https://www.esignlive.com/blog/e-signlive-for-new-users-how-to-create-and-send-your-first-package-rest-api/
The next section of the package JSON string is the “documents” object. Inside this, you will set items like the “name” and the “approvals” (signature blocks). In the “approvals”, the main items to set would be the “type”, “subtype”, “role”, “page”, and the location settings. These will define the signatures required in each document.
Which make me think that I need to pass all the custom fields inside the documents => approvals => fields.

Reply to: Full REST API documentation

0 votes
Your documents and everything for your package is already defined in your template. You shouldn’t need to do anything with those, if you’re just replacing your placeholder “Signer”.
Great, thank you! I've removed the whole documents section from JSON payload and it worked.

Reply to: Full REST API documentation

0 votes
Awesome! Glad it's all working, now.

- Michael

Director, Partner and Developer Technologies, OneSpan

Facebook - Twitter - LinkedIn


Reply to: Full REST API documentation

0 votes
Is the documentation already there because working with the API is really hard without the information, and more tutorials how to implement things. I think if you guys could create 5 to 10 business cause .. that woulde be a hugh help.

Reply to: Full REST API documentation

0 votes
Hi, We are in the current stage of assessing potential e-signature based products for our Financial Services firm. I am the Lead Architect for this organization and we are in a preliminary stage. I badly need your e-SignLive documents explaining the API and integration approaches which will be helpful for us to assess and generate a POC, also does E-SignLive has got any predefined integration with Mulesoft similar to Salesforce and MS-Dynamics? Please help us in this regard.

Hello! Looks like you're enjoying the discussion, but haven't signed up for an account.

When you create an account, we remember exactly what you've read, so you always come right back where you left off