What's new in SignHero API


Version 4.0

Released: 24.09.2020
Document management and access to "Me" signers
What's new?

SignHero API v4 is a brand new version that introduces new API methods for document management and interaction with account owners. Additionally, we've taken into consideration a lot of feedback to make the API more pleasant to work with.

API v4 is available in parallel with v3, read about API versioning in Overview to find out more.

Download our latest Postman collection ang give the API a spin!


Main changes from version 3:
  • OAuth2 scopes added. Check Request an authorisation code section to find out more
  • A brand new Document upload request added
  • Search and Delete unattached documents with new document management requests
  • Signing process creation request changed to allow creating processes with account owner as a participant
  • Create signing URLs to complete signing processes without forcing users to leave your application
  • A brand new Document download request added
  • Retrieve user profile info
  • code_key values in log_list entries are now numbers instead of strings:
    "code_key": "200" => "code_key": 200
  • Access tokens are no longer replicated in each API response. Additionally, auth_key key was dropped for client-credentials tokens. From now on, both types of access tokens are passed into requests with the access_token key:
    "trans_map": { "access_token": "9YWx0ivNwUtLSHld3H0XfduxdEoPVH0NlmoBM" }

Version 3.0

Released: 27.03.2019
Will deprecate: 03.2021
OAuth2 release
What's new?

SignHero API v3 features OAuth2 functionalities by enabling the authorisation code grant type. Now, depending on your needs, it’s possible to manage signature processes through your own SignHero account or do that on behalf of any other user.


Main changes from version 2:

Version 2.0

Deprecated
More stability and control over signature processes
What's new?

SignHero API v2 is an improvement release fixing known issues and adding new features to searching through signature processes.


Version 2 documentation:
Download

Version 1.0

Deprecated
The first release

The first release of SignHero API, allowing users to automate signature process management within their own accounts.


Overview


API design principles

All requests and responses, with exception of download and upload methods, are designed using JSON-pure principles.

  • All character sets are UTF-8.
  • All requests use HTTP POST.
  • All requests have MIME type application/json, except document uploads, which have MIME type multipart/form-data in API v3 and application/pdf in API v4.
  • All responses are JSON objects with MIME type application/json, except document downloads, which are binary streams with MIME type application/pdf.

For example:

curl -X POST https://api.signhero.io/signatures \
-H 'Content-Type: application/json' \
-d '{
    "action_str": "retrieve",
    "data_type": "signature_flows",
    "trans_map": {
        "access_token": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {
        "status": "pending"
    }
}'
API versioning

Currently, two versions of the API are available: v3.0.0 and v4.0.0. To specify which version you want to use, put respective major version number in endpoint path:

curl -X POST https://api.signhero.io/3/signatures  # POST to the API v3 signatures endpoint
curl -X POST https://api.signhero.io/4/documents  # POST to the API v4 documents endpoint
  

When you don't specify an API version in the path, the default version (v3) is used:

curl -X POST https://api.signhero.io/3/signatures
curl -X POST https://api.signhero.io/signatures  # The two lines refer to the same API version
  

Authentication


You need an authentication token every time you make a call to SignHero API. SignHero API offers two authorisation grants for your application to authenticate users: Client credentials and Authorisation code.

Authorisation grants - Client credentials


Use this grant when your application needs to access its own processes.

Request an access token

v3 v4

To obtain an access token, present your credentials at the authentication endpoint:

POST /4/auth HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "create",
    "data_type": "access_token",
    "request_map": {
        "client_id": "signhero.tester@signhero.io",
        "client_secret": "1498b03d760b233673953a11268bb486ab29"
    }
}
{
    "action_str": "created",
    "data_type": "access_token",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "access_token created",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "trans_map": {
        "auth_keyaccess_token": "YWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    }
}

Access tokens expire in 7 days. To make SignHero API calls, add the obtained access token to the auth_keyaccess_token field in the request:

POST /4/signatures HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "retrieve",
    "data_type": "signature_flow",
    "trans_map": {
        "auth_keyaccess_token": "YWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {
        "process_id": "ae3b5221-0272-11e7-a154-46787cfede40"
    }
}

Revoke tokens

v3 v4

To disable your current access token, send a request to the authentication endpoint:

POST /4/auth HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str" : "delete",
    "data_type" : "access_token",
    "trans_map": {
        "auth_keyaccess_token": "YWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {}
}
{
    "action_str": "deleted",
    "data_type": "access_token",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "access_token deleted",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "response_map": {},
    "trans_map": {}
}

You can also disable all your access tokens with one request:

POST /4/auth HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "delete",
    "data_type": "access_tokens",
    "trans_map": {
        "auth_keyaccess_token": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {}
}
{
    "action_str": "deleted",
    "data_type": "access_tokens",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "access_tokens deleted",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "response_map": {},
    "trans_map": {}
}

Authorisation grants - Authorisation code


Use this grant when your application wants to obtain limited access to SignHero API on behalf of users. You'll need to create an OAuth2 application in your SignHero integration settings before getting started.

Create an application


Before using authorisation code grant, you need to create an OAuth2 application.

Log into SignHero portal, open the side menu and select Integrations.

In the integrations list, select Add application.

Fill in application name and optionally description both of which will be present on the user consent page. If you choose to provide a description, explain what your application does and how it is going to use the access granted by the user.

In the following section provide your servers's domain name and at least one redirect URI to which users will be redirected after giving consent. Authorisation code will be added as a query parameter in the redirect URL.

After creating an application you'll see it in the integrations list. The status of the app will be Inactive.

Inactive means that you haven't yet verified the ownership of app's domain. Select your app in the list to proceed.

On the bottom of the application page you will find app's client ID and secret. This is the moment when you should copy the secret and safely store it somewhere. After refreshing the page, the secret won't be visible anymore. If you lost your secret, click on Change secret to generate a new one.

In the Manage redirect URI section you should see your domain name with a warning sign, which means that your domain is not verified. Below the domain name text field you will see instructions on how to verify the domain.

After you've successfully verified your domain, the waring will disappear. In the integrations list, your application will become Active

Congratulations! Now your OAuth2 application can be used to create access tokens using authorisation code grant.

Request an authorisation code


Your application should redirect the user to the authorisation endpoint which will display a consent page.

The authorisation URL should have the following format:

https://signhero.io/oauth2/authorize?client_id={{client_id}}&redirect_uri={{redirect_uri}}&response_type=code&scope={{scopes}}&state={{state}}

The parameters in the query:

client_id Your application's client identifier.
redirect_uri The URI to which SignHero will redirect the user after authorisation. This URI must be specified as a valid redirect URI in your application configurations.
response_type The value must be "code".
scope Space-delimited list of API scopes requested from a user. URL-encoded space character is either + or %20. Available scopes:

  • basic: Create signing processes and manage them. Default scope.
  • profile: Retrieve user profile information.
  • signing_url: Create URLs that open the signing page.
state A unique string value to prevent CSRF. This value is optional but highly recommended.

If the user approves your request, the user will be redirected to {{redirect_uri}}, and the authorisation code will be part of the redirect URI:

https://example.io/oauth2/callback?&code={{code}}&scope=basic+profile&state={{state}}

If the user choses to cancel, or the request fails, the user will be redirected to {{redirect_uri}} with an error:

https://example.io/oauth2/callback?&error={{error}}&state={{state}}

The parameters in the query:

error One of the following errors described in Error responses.
state A unique string value to prevent CSRF. This value is optional but highly recommended.

Exchange the authorisation code to an access token

v3 v4

Next the authorisation code must be exchanged for an access token that can be used to call SignHero API. To exchange the authorisation code, send a request to the token endpoint:

POST /4/token HTTP/1.1
  Host: api.signhero.io
  Content-Type: application/json

  {
      "action_str": "create",
      "data_type": "access_token",
      "request_map" : {
          "client_id": "5e5b2260-d3a7-11e8-a608-92030a9483f4",
          "client_secret": "qSHofvOzKlAI7kYCNW3CmleZxmYF5nUiG1RZayDJsM",
          "grant_type": "authorization_code",
          "code": "obweYepSsNTvPTXLlS44umklgq2eArlKm3qPQe0GlXg",
          "redirect_uri": "https://example.io/oauth2/callback"
      }
  }
  

The parameters in the request map:

client_id Your application's client identifier.
client_secret Your application's client secret.
grant_type The value must be "authorization_code".
code The authorisation code.
redirect_uri The URI to which SignHero will redirect the user after authorisation. This URI must be specified as a valid redirect URI in your application configurations.

If the request is valid and authorised, the response includes an access token and refresh token.

{
    "action_str": "created",
    "data_type": "access_token",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "access_token created",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "response_map": {},
    "trans_map": {
        "access_token": "9YWx0ivNwUtLSHld3H0XfduxdEoPVH0NlmoBM",
        "expires": 1538994375247,
        "refresh_token": "j06Bv5oRTByT5GYiZOuUH4hqm8ZQzaXMdI4XYj1vY"
    }
}

Access tokens expire in 7 days. Refresh tokens never expire.

To make SignHero API calls, add the obtained access token to the access_token field in the request:

POST /4/signatures HTTP/1.1
  Host: api.signhero.io
  Content-Type: application/json

  {
      "action_str": "retrieve",
      "data_type": "signature_flow",
      "trans_map": {
          "access_token": "9YWx0ivNwUtLSHld3H0XfduxdEoPVH0NlmoBM"
      },
      "request_map": {
          "process_id": "ae3b5221-0272-11e7-a154-46787cfede40"
      }
  }
  

Refresh an access token

v3 v4

To refresh an access token, send a request to the token endpoint:

POST /4/token HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "update",
    "data_type": "access_token",
    "request_map": {
        "client_id": "5e5b2260-d3a7-11e8-a608-92030a9483f4",
        "client_secret": "qSHofvOzKlAI7kYCNW3CmleZxmYF5nUiG1RZayDJsM",
        "grant_type": "refresh_token",
        "refresh_token": "j06Bv5oRTByT5GYiZOuUH4hqm8ZQzaXMdI4XYj1vY"
    }
}

The parameters in the request map:

client_id Your application's client identifier.
client_secret Your application's client secret.
grant_type The refresh token issued to your application.
refresh_token The value must be "refresh_token".

On success the response includes a new access token and refresh token:

{
    "action_str": "updated",
    "data_type": "access_token",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "access_token updated",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "response_map": {},
    "trans_map": {
        "access_token": "KZ8oUeAYGjz6HSJRlI8O5zaVKRddXW34tbfbsCKqyKk",
        "expires": 1542376889609,
        "refresh_token": "7gzokMZKMbcJtJIe2XULggUAIiEFDIRJuHwFU8cGE"
    }
}

Revoke tokens

v3 v4

To revoke a token, send the following request to the token endpoint:

POST /4/token HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "delete",
    "data_type": "token",
    "request_map": {
        "client_id": "5e5b2260-d3a7-11e8-a608-92030a9483f4",
        "client_secret": "qSHofvOzKlAI7kYCNW3CmleZxmYF5nUiG1RZayDJsM",
        "token": "7gzokMZKMbcJtJIe2XULggUAIiEFDIRJuHwFU8cGE"
    }
}

The parameters in the request map:

client_id Your application's client identifier.
client_secret Your application's client secret.
token The access or refresh token your applications wants to revoke.
{
    "action_str": "deleted",
    "data_type": "token",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "token deleted",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "response_map": {},
    "trans_map": {}
}

Error responses

v3 v4

On error, the server returns the code_key value 400 (bad_request) and one of the following errors:

access_denied The user or SignHero server denied the request.
invalid_request The request is missing a required parameter, includes an unsupported parameter value or is otherwise malformed.
invalid_client Client authentication failed.
invalid_grant The provided authorisation grant or token is invalid, expired or revoked.
unauthorized_client The authenticated client is not authorised to use this authorisation grant type.
server_error The server encountered an unexpected condition which prevented it from fulfilling the request.
{
    "action_str": "create_fail",
    "data_type": "access_token",
    "log_list": [
        {
            "code_key": "400"400,
            "code_str": "bad_request",
            "error": "invalid_client",
            "user_msg": "Invalid client id or secret",
            "level_int": 3,
            "level_str": "error"
        }
    ],
    "response_map": {},
    "trans_map": {}
}

Upload a document

v3 v4

Scope: basic


To upload a document post a multipart/form-data request to the documents endpoint. The multi-part request needs to include a payload_data field, which contains the document to sign, and an operation_data field, which contains the JSON-Pure object:

curl -X POST \
    https://api.signhero.io/documents \
    -F 'operation_data={"action_str":"create","data_type":"document",
        "trans_map ":{"auth_key":"YYWMtGeygaKCEeahbgX148SD2wAAAVipR"},
        "request_map":{}}' \
    -F 'payload_data=@/Users/signhero/test.pdf;type=application/pdf'

The maximum size for a document is 10MB.

The successful response includes the identifier of the document:

{
    "action_str": "created",
    "data_type": "document",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "document created",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "trans_map": {
        "auth_key": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "response_map": {
        "document_id": "d807b62c-08bb-11e7-a142-080027334cc4"
    }
}

To upload a document post it to the document upload endpoint:

curl --X POST 'https://api.signhero.io/4/documents/upload?filename=test.pdf' \
> --header 'Content-Type: application/pdf' \
> --header 'Authorization: Bearer YYWMtGeygaKCEeahbgX148SD2wAAAVipR' \
> --data-binary '@/Users/signhero/test.pdf'

URL query parameters:

file_name Name of the document file in format *.pdf.

Headers:

Content-Type application/pdf
Content-Length Requests with chunked transfer encoding (e.g. those with streamed bodies) don't typically have Content-Length header appended automatically. Make sure to add it manually, if your request doesn't contain it.
Authorization Access token in format Bearer {{access_token}}

The maximum size for a document is 10MB.

The successful response includes the identifier of the document and its name:

{
    "document_id": "d807b62c-08bb-11e7-a142-080027334cc4",
    "file_name": "test.pdf"
}

Search unattached documents

This method is only available in API v4.

Scope: basic


To retrieve documents, which were upload to SignHero but have not beet attached to a signing process yet, send a request to the documents endpoint:

POST /4/documents HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "retrieve",
    "data_type": "unattached_documents",
    "trans_map": {
        "access_token": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {
        "scope": "group"
    }
}

The parameters in the request map:

scope Constrain search results to only documents uploaded by the user. Accepted values are user and group. The user has to have admin rights to use the scope group. Defaults to user.

The successful response includes identifiers, names and creation date of documents:

{
    "action_str": "retrieved",
    "data_type": "unattached_documents",
    "log_list": [
        {
            "code_key": 200,
            "code_str": "ok",
            "user_msg": "unattached_documents retrieved",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "trans_map": {},
    "response_map": {
        "documents": [
            {
              "uuid": "f0de9faa-b0a7-11ea-8ac3-76ad82d12dd4",
              "created": 1592404593537,
              "file_name": "document_1.pdf"
            },
            {
              "uuid": "bd3140e5-b0a7-11ea-8ac3-76ad82d12dd4",
              "created": 1592404506837,
              "file_name": "document_2.pdf"
            }
        ]
    }
}

Delete an unattached document

This method is only available in API v4.

Scope: basic


Before a document has been attached to a signing process, it can be deleted from SignHero. To delete a document, send a request to the documents endpoint:

POST /4/documents HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "delete",
    "data_type": "document",
    "trans_map": {
        "access_token": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {}
}
{
    "action_str": "deleted",
    "data_type": "document",
    "log_list": [
        {
            "code_key": 200,
            "code_str": "ok",
            "user_msg": "document deleted",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "trans_map": {},
    "response_map": {}
}

Create a signing process

v3 v4

Scope: basic


Creating a signing process is a two-part operation: first, upload the documents to sign, second, create the process which signs them.

To create a signing process send a request which lists the identifiers of the uploaded documents as well as the rest of the information about the signing process:

POST /4/signatures HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "create",
    "data_type": "signature_flow",
    "trans_map": {
        "auth_keyaccess_token": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {
        "title": "My first",
        "locale": "en",
        "signature_invitation": {
            "subject": "Signature invitation",
            "message": "Your signature is requested."
        },
        "documents": [
            "d807b62c-08bb-11e7-a142-080027334cc4"
        ],
        "signers": [
            {
                "type": "me"
            },
            {
                "type": "others",
                "name": "SignHero Tester",
                "email": "signhero.tester@signhero.io"
            }
        ]
    }
}

The parameters in the request map:

title A title for the signing process. This value is optional.
locale Specify the language used in the signing pages and emails. Supported locales are en, fi and pl. Defaults to en.
signature_invitation An object presenting the signature invitation.
signature_invitation:subject A custom subject for the email sent to the signers. This value is optional.
signature_invitation:message A custom message in the email sent to the signers. This value is optional.
documents An array containing the identifiers of the documents sent for signature. The maximum number of documents is 20.
signers An array of the signers.
signer:type Type of the signer: me for account owner or others for an invited signer.
signer:name The name of the signer. This value is not allowed for a me signer.
signer:email The email of the signer. This value is not allowed for a me signer.
signer:locale Specify the language used in the signing pages and emails. Supported locales are en, fi and pl. Defaults to the locale of the signing process. This value is not allowed for a me signer.

The successful response includes the identifiers of the process and signers:

{
    "action_str": "created",
    "data_type": "signature_flow",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "signature_flow created",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "trans_map": {
        "auth_key": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "response_map": {
        "process_id": "d7e93169-08bb-11e7-a142-080027334cc4",
        "signers": [
            "2d871e79-0b23-11e7-93dc-42067774ef10"
        ]
    }
}

Create a signing URL

This method is only available in API v4.

Scope: signing_url


It is possible to create a URL that opens the signing page for a me signer. This will allow you to streamline signing of documents directly from your app. To create such URL, send a request to the signatures endpoint:

POST /4/signatures HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "create",
    "data_type": "signing_url",
    "trans_map": {
        "access_token": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {
        "process_id": "f0de9faa-b0a7-11ea-8ac3-76ad82d12dd4"
    }
}

The parameters in the request map:

process_id Identifier of a signing process that has a me signer.

The successful response includes the signing URL:

{
    "action_str": "created",
    "data_type": "signing_url",
    "log_list": [
        {
            "code_key": 200,
            "code_str": "ok",
            "user_msg": "signing_url created",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "trans_map": {},
    "response_map": {
        "signing_url": "https://signhero.io/signing.html?signer=14ae10f6-ec74-11ea-836c-0e4c72c52e02
  &token=KFcWKX3JwUV0-hs7R8jDNf45Rl3H_v9f40RrfG2jM2e61ijeNq1bx2SzdLtMfU97&default_locale=en"
    }
}

Retrieve a signing process

v3 v4

Scope: basic


Retrieves the details and status of a signing process:

POST /4/signatures HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "retrieve",
    "data_type": "signature_flow",
    "trans_map": {
        "auth_keyaccess_token": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {
        "process_id": "d7e93169-08bb-11e7-a142-080027334cc4"
    }
}
{
    "action_str": "retrieved",
    "data_type": "signature_flow",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "signature_flow retrieved",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "trans_map": {
        "auth_key": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "response_map": {
        "uuid" : "d7e93169-08bb-11e7-a142-080027334cc4",
        "title": "My first",
        "created": 1488807723074,
        "modified": 1488807859249,
        "status": "completed",
        "pending_count": 0,
        "signature_invitation": {
            "subject": "Signature invitation",
            "message": "Your signature is requested."
        },
        "locale": "en",
        "documents": [
            {
                "uuid": "d807b62c-08bb-11e7-a142-080027334cc4",
                "file_name": "test.pdf"
            }
        ],
        "signers": [
            {
                "uuid": "2d871e79-0b23-11e7-93dc-42067774ef10",
                "name": "SignHero Tester",
                "email": "signhero.tester@signhero.io",
                "locale": "en",
                "embed": false,
                "status": "signed",
                "signed": 1488807859156
            }
        ],
        "completed": 1488807859156
    }
}

The parameters in the response map:

created Time when the signing process was created.
modified Time when the signing process was last modified.
completed Time when the signing process was completed.
canceled Time when the signing process was canceled.
status Status of the signing process:
  • pending: There is pending signatures.
  • completed: All signers have signed.
  • canceled: The signing process has been canceled or someone declined to sign.
  • inactive: Process creation is ongoing. After this the status will be pending or failed.
  • failed: Process creation failed. All failed signing processes are deleted within 24 hours.
pending_count Number of pending signatures.
documents A list of the documents sent for signature.
signers A list of the signers.
signer:status Status of the signer: pending, signed or declined.
signer:signed Time when the signer signed the documents.
signer:declined Time when the signer declined to sign.

Search signing processes

v3 v4

Scope: basic


You can retrieve all your signing processes or search them based on their status.

POST /4/signatures HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "retrieve",
    "data_type": "signature_flows",
    "trans_map": {
        "auth_keyaccess_token": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {
        "status": "pending",
        "scope": "user",
        "limit": 1
    }
}

The parameters in the request map:

status Filter results based on the status field. Accepted values are pending, completed and canceled.
scope Constrain search results to only processes created by the user. Accepted values are user and group. The user has to have admin rights to use the scope group. Defaults to user.
limit Number of results to return in a single response. The maximum number of results is 1000. Defaults to 10.
cursor Cursor to retrieve the next set of results.
{
    "action_str": "retrieved",
    "data_type": "signature_flows",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "signature_flows retrieved",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "trans_map": {
        "auth_key": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "response_map": {
        "signature_flows": [
            {
                "uuid" : "d7e93169-08bb-11e7-a142-080027334cc4",
                "title": "My first",
                "created": 1488799050744,
                "modified": 1488799050744,
                "status": "pending",
                "pending_count": 1,
                "locale": "en"
            }
        ],
        "cursor": "OikKAfqAMqMjU20wSDdHlwZUtzaWduX3Byb2Nlc3P7gDHS-w=="
    }
}

The parameters in the response map:

cursor Cursor to retrieve the next set of results, in case the number of results is more than limit value.
signature_flows Found signing processes.

Cancel a signing process

v3 v4

Scope: basic


A signing process that has not been completed can be canceled. Signers will not be able to review and sign the documents anymore.

POST /4/signatures HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "update",
    "data_type": "signature_flow",
    "trans_map": {
        "auth_keyaccess_token": "YWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {
        "process_id": "ae3b5221-0272-11e7-a154-46787cfede40",
        "cancel": true
    }
}
{
    "action_str": "updated",
    "data_type": "signature_flow",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "signature_flow updated",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "response_map": {},
    "trans_map": {
        "auth_key": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    }
}

Delete a signing process

v3 v4

Scope: basic


A signing process that has been completed or canceled can be deleted from search results.

POST /4/signatures HTTP/1.1
Host: api.signhero.io
Content-Type: application/json

{
    "action_str": "delete",
    "data_type": "signature_flow",
    "trans_map": {
        "auth_keyaccess_token": "YWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    },
    "request_map": {
        "process_id": "ae3b5221-0272-11e7-a154-46787cfede40"
    }
}
{
    "action_str": "deleted",
    "data_type": "signature_flow",
    "log_list": [
        {
            "code_key": "200"200,
            "code_str": "ok",
            "user_msg": "signature_flow deleted",
            "level_int": 1,
            "level_str": "info"
        }
    ],
    "response_map": {},
    "trans_map": {
        "auth_key": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
    }
}

Download a document

v3 v4

Scope: basic


To get a copy of the current version of a document make a download request to the documents endpoint:

POST /documents HTTP/1.1
  Host: api.signhero.io
  Content-Type: application/json

  {
      "action_str": "retrieve",
      "data_type": "document",
      "trans_map": {
          "auth_key": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
      },
      "request_map": {
          "document_id": "d807b62c-08bb-11e7-a142-080027334cc4"
      }
  }
  

To get a copy of the current version of a document, download it from the documents endpoint using document ID as a path component:

curl 'https://api.signhero.io/4/documents/8e4dc18d-ec84-11ea-8ac3-76ad82d12dd4' \
  > --header 'Authorization: Bearer YYWMtGeygaKCEeahbgX148SD2wAAAVipR'
  

Headers:

Authorization Access token in format Bearer {{access_token}}

The successful response is a binary stream with MIME type application/pdf.

The downloaded document will always be the current version of it, which may have all, some or none signatures depending on how many people have signed already.

Retrieve profile info

This method is only available in API v4.

Scope: profile


To retrieve user's profile info, send a request to the profile endpoint:

POST /4/profile HTTP/1.1
  Host: api.signhero.io
  Content-Type: application/json

  {
      "action_str": "retrieve",
      "data_type": "profile",
      "trans_map": {
          "access_token": "YYWMtGeygaKCEeahbgX148SD2wAAAVipR17t2Xygd71iJDLWO"
      },
      "request_map": {}
  }
  
{
      "action_str": "retrieved",
      "data_type": "profile",
      "log_list": [
          {
              "code_key": 200,
              "code_str": "ok",
              "user_msg": "profile retrieved",
              "level_int": 1,
              "level_str": "info"
          }
      ],
      "trans_map": {},
      "response_map": {
          "name": "John Doe",
          "email": "john.doe@mailprovider.com",
          "locale": "en",
          "is_admin": true,
          "organisation": "John Doe Inc."
      }
  }
  

The parameters in the response map:

name Name of the user.
email Email address of the user.
locale Communication language preference. Can be en, fi or pl.
is_admin Shows whether the user has admin rights.
organisation Organisation name of the user.