apidocs.sign.gonitro.com Open in urlscan Pro
3.85.178.40 Public Scan

Back to summary

URL:
https://apidocs.sign.gonitro.com/
Submission Tags: phishingrod
Submission: On September 01 via api (September 1st 2024, 3:56:33 am UTC) from DE — Scanned from DE

Form analysis
0 forms found in the DOM

Text Content

* Body
* Headers (1)

Public

Documentation Settings

ENVIRONMENT
No Environment

LAYOUT
Double Column

LANGUAGE
cURL - cURL

Nitro Sign Premium - Public API
Introduction
v7.5 - Documentation
v7.6 - Documentation

NITRO SIGN PREMIUM - PUBLIC API

V7.5 - DOCUMENTATION

Last updated 13/10/2023

INTRODUCTION

This document describes the technical specifications of the Nitro Sign Premium
API v4.

The Nitro Sign Premium API is a REST API. It is a web service that allows
external systems to make requests for Nitro Sign Premium sources through URL
paths. More concretely, it allows external systems to interact with the Nitro
Sign Premium platform and use its features to create and manage signing flows.

DISCLAIMERS

Only the described use cases are supported. All other use cases, even though
possibly technically feasible with the API, are explicitly not supported and
should not be implemented as such.

In case of discrepancies between examples and the description of the parameters
section, the description of the parameters section prevails.

The descriptions of error codes in this document or the actual error message
fields returned by the API are subject to change. External applications should
rely on the returned error code values, anything else is only for diagnostic
purposes.

All documents uploaded to the API must comply with the standards corresponding
of that format. Conversions are based on a best-effort approach. The behavior of
uploading non-compliant documents and / or conversions in an environment where
required fonts, color profiles etc. are missing is undefined.

The URLs of the REST API in this document were changed to v4 in Nitro Sign
Premium version 6.0. The support period for the API with v3 URLs outlined in the
Nitro Sign Premium version 5.x API Technical Documentation is governed by the
Nitro Sign Premium support Contract.

The API calls with v2 URLs are no longer supported since version 6.0.

Be aware that the agile nature of JSON for the REST services supports adding
optional parameters to the request or new parameters to the responses. The only
actions that are considered breaking changes of the API are adding required
parameters, changing existing parameters in the requests, or parameters missing
from responses.

Important: Always use conforming JSON data in the requests. When the Web
Application Firewall in front of Nitro Sign Premium is enabled, the firewall
validates all JSON passing through it and does not accept invalid JSON (e.g.
which contains embedded comments such as // or /* */ and extra commas).

Optional fields that are not used must be left out of the request message. An
empty string or dummy value for optional fields is also a value, and hence may
trigger an error in the current version or a future version.

There is no dedicated error code for packages which exceed a given file size
other than HTTP code 404.13 returned by IIS. However, as a practical guideline a
document must not exceed 30 MB. Packages must not be larger than 150 MB in total
and should not contain more than 15 documents. Note that large files might
affect signing performance, depending on the user's Internet connections.

REST SERVICE

The services are plain REST based services, maintaining no state whatsoever. All
data exchanges, in and out, are handled in JSON data format and using UTF-8
encoding.

The default URL is:

https://[servername]:[port]/esig/webportalapi/v4/

Important note about MTLS:

When the setting IsMtlsEnabled is enabled in the Configuration Index, API users
must make sure that an HTTP/1.1 connection is established and that the following
header is sent in all Nitro Sign Premium API calls:

Plain Text

Expect: 100-continue

The client should then wait for the HTTP 100 Continue response before sending
the actual payload.

Failing to do so will cause problems with large payloads (e.g. when uploading
PDF documents). In such a case the payload will fill the server’s receiving
buffer before proper mutual authentication is finished, the connection will
never be established and the request will time out as a result.

If for some reason such HTTP/1.1 connection is not feasible, API users can also
try to send a HEAD request using their HTTP client object before doing the
actual file upload request with the same client. This workaround is not
recommended however, since the client may decide to reset the connection in
between the two different calls.

HTTP STATUSES

Below you find an overview of the HTTP statuses that are returned, and their
meaning.

SUCCESSFUL RESPONSES

200 OK
The response body contains a representation of the requested / created resource.

201 Created
The request led to the creation of a resource. The created resource is in the
body of the response and its location is found in the Location header.

204 No Content
The request was successful and there is no additional content to send in the
response body.

CLIENT ERROR RESPONSES

400 Bad Request
The server cannot or will not process the request due to something that is
perceived to be a client error (e.g. failed validation).

401 Unauthorized
The request has not been applied because it lacks valid authentication
credentials for the target resource.

404 Not Found
The origin server did not find a current representation of the target resource.

409 Conflict
The request could not be completed due to a conflict with the current state of
the target resource. This code is used in situations where the user might be
able to resolve the conflict and resubmit the request.

SERVER ERROR RESPONSES

500 Internal Server Error
The server encountered an unexpected condition that prevented it from fulfilling
the request.

CONCEPTS OVERVIEW

This section explains the different concepts that are used in the Nitro Sign
Premium API.

Package
Packages lie at the core of Nitro Sign Premium. A package is a container for
digital documents that are sent for signing.

A package may contain one or more documents that need to be signed. A package
may also have multiple stakeholders who will take actions on the package's
documents.

Document
A document is a digital file that is sent for signing. A document is always part
of a package and is signed by a stakeholder.

A document may contain multiple elements. This element could be a signing field
or a form field (e.g. textbox field, checkbox field and radio buttons) and as of
7.0.0 it can also be a UnplacedElement (e.g. not attached to a document yet)

Element
An element is an item that is placed on a document and may be assigned to an
actor. For instance, a signing field that can be assigned to a signer actor or a
form field that can be assigned to a form filler actor.

Stakeholder
A stakeholder is an entity that has an interest in a package. A single
stakeholder may contain multiple actors, i.e. actions the stakeholders must do.
For instance, form fill, approve, sign or receive.

A stakeholder may be a single person, or a group of people. When a group of
people is defined, any member of the group will be able to form fill, approve or
sign on behalf of the entire group.

Actor
An actor is a single action that a stakeholder must do on a package.

The different actor types are: form filler, approver, signer and receiver.

Process and process steps
A package's process defines which stakeholder will do their action at which
moment in time. A process may consist of multiple process steps. This way, you
can set up parallel, sequential or complex flows in which actors can form fill
and approve or sign. All actors that are put in the same process step will be
completed in parallel.

Tip: Consult the Glossary section for an overview of more Nitro Sign Premium
related terms.

AUTHENTICATION AND SECURITY

AUTHENTICATION

BASIC AUTHENTICATION

The Nitro Sign Premium API supports ‘Basic Authentication’ via a username and
password combination that must be placed in the header of every request.

The default credentials, which must be changed through configuration at
installation time should have been communicated to you by email or sms.

Note: depending on the Configuration Index settings, the use of an Mtls Client
certificate might be required.

AUTHENTICATION USING JWT ACCESS TOKEN

Authentication can be done using a JWT access token following the Oauth 2.0
protocol using the "Client Credentials Grant" flow.

The access token can be retrieved by calling the token endpoint of the
authentication server. The Url of the token endpoint can be retrieved from the
discovery endpoint available at /.well-known/openid-configuration.

The access token should be cached and reused for its lifetime. A new access
token should be retrieved using the refresh token when it is expired.

Getting the token with curl:

View MorePlain Text

View More
Plain Text

curl -A "ClientApplication/1.0" -d "grant_type=client_credentials&client_id=${client_id}&client_secret=${client_secret}&scope=${scope}" "${token_endpoint}"

client_id is the value of the client id (also called application id) provided by
Nitro client_secret is the "password" for the client id, provided by Nitro scope
must contain "https://connective.eu/scopes/esignatures" for Nitro Sign Premium
token_endpoint is the token endpoint on the authentication server

The response is a json document of the form:

View Morejson

json

{
"access_token": "eyJhb.........A",
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": "eyJhb...........A",
"token_type": "bearer",
"not-before-policy": 1591634674,
"session_state": "0f65368c-90df-4e2f-b039-5320a0b34871",
"scope": "email https://connective.eu/scopes/esignatures profile"
}

When calling the API, the access token must be placed in an Authorization HTTP
Header of type “Bearer”. See https://tools.ietf.org/html/rfc6750

NB: a valid User Agent string is required for calls. The default user agent for
curl or wget can be blocked by the Web Application Firewall protecting the
application.

SECURITY THROUGH ONE-TIME URLS

The URL lifetime is by default limited to one-time use (unless the administrator
disabled the IsOneTimeUrlEnabled setting in the Config Index, which is not
recommended). It is therefore recommended to request the stakeholder's actor
links just before redirecting them. This way, you make sure they receive the
latest generated link.

When end users open an action URL they already used, they will either see a
warning or be redirected to a given URL (if available). The only way to achieve
this is to request a new URL and provide it to the user. You can do this by
retrieving the Actor information via any of the API status calls.

When end users try to take action on a document that has been deleted, a 404 Not
found error will occur. This cannot be recovered from, since all information has
been purged from Nitro Sign Premium.

ERROR HANDLING RESPONSES

Nitro Sign Premium API v4 uses HTTP error codes to give an idea of whether a
call succeeded or failed, and a system of error codes in the response body to
give more information in case things went wrong.

The used error codes for each call are listed in that call’s section. The
meaning of each error code is further explained in Error Code Descriptions.

The error responses are JSON containing the following list of objects:

Parameter Content / Description Type Errors (array of objects) List of the
errors Array ErrorCode Error code with variable information String Message Error
message detail text, not localized String

A Nitro Sign Premium error code is always displayed as follows:

Resource.Error:parameter

E.g. Package.NotFound:00000000-0000-0000-0000-000000000000. The GUID behind the
colon is the packageId that wasn't found.

Error codes can be reused: if the HTTP response code is HTTP 400 Bad Request, an
error code like “Document.InvalidTargetFormat” indicates a value that is not
supported by Nitro Sign Premium. If the HTTP response code is HTTP 409 Conflict,
an error code like “Document.InvalidTargetFormat” means that the request value
can currently not be used because the configuration forbids it.

Note: any HTTP 500 Server Error or other 50x responses might deviate from the
format described in this section as they are not part of the API.

FULL ERROR CODE DESCRIPTIONS

https://connectivecommunities.force.com/s/article/API-v4-Error-code-descriptions

CONFIGURATION

Retrieving information about the configuration

GETGETS ALL CONTACT GROUPS

{{baseUrl}}/contactGroups?continuationToken=<string>&maxQuantity=20&sortOrder=desc&sortField=code

StartFragment

GET CONTACTGROUPS

DESCRIPTION

This call retrieves all the contact groups, and their code, that are currently
created in the eSignatures WebPortal.

The ContactGroup code can be entered as a request parameter when doing a Create
Package call. Any member of the requested contact group will be able to sign the
package for the entire group.

URL

https://[servername]:[port]/esig/webportalapi/v4/contactgroups

HTTP METHOD

GET

MIME TYPE

application/json

QUERY PARAMETERS

Parameter Occurrence Content/Description Type ContinuationToken Optional Token
which holds information about which set of records needs to be returned. String
MaxQuantity Optional Maximum number of records Int SortField Optional Sort the
returned records by the field which is specified. Possible values: 'code' or
'name'. String SortOrder Optional ‘asc’ or ‘desc’ to specify in which way
sorting happens. String

RESPONSE PARAMETERS

Parameter Content/Description Type ContinuationToken Token which holds
information about which set of records needs to be returned. String Items List
of contact groups Array of objects Name Name of the contact group String Code
Unique id of the contact group String MaxQuantity Maximum number of records Int

RESPONSE CODES

Response status code Description 200 OK The contact groups list gets returned
successfully. 400 Bad request A request parameter was invalid.

ERROR CODES

HTTP Code Code None No errors

EndFragment

HEADERS
Accept

application/json

PARAMS
continuationToken

The token to return to request the next page

maxQuantity

The maximum number of results to return

sortOrder

desc

specify how the result is sorted, default is ascending

sortField

code

specify on which field to sort

Example Request
OK

View More
curl

curl --location -g '{{baseUrl}}/contactGroups?continuationToken=%3Cstring%3E&maxQuantity=20&sortOrder=desc&sortField=code'

200 OK
Example Response
* Body
* Headers (1)

View More
json

{
"ContinuationToken": "<string>",
"Items": [
{
"Code": "<string>",
"Name": "<string>"
},
{
"Code": "<string>",
"Name": "<string>"
}
],
"MaxQuantity": "<integer>",
"Total": "<integer>"
}

Content-Type

application/json

GETRETRIEVES ALL DOCUMENT GROUPS TO WHICH PACKAGES CAN BE ASSIGNED

{{baseUrl}}/documentGroups

StartFragment

GET DOCUMENTGROUPS

DESCRIPTION

Some requests need to identify a Document Group in which a document is to be
used. This request allows to list the names of document groups and most
importantly their associated codes.

There is always at least one document group: “My Documents” (the name could be
different) with Code “00001”. This group is special because the documents in
this group are only visible to the eSignatures Portal user who uploaded the
document (in case of an upload made through the API from this document it will
be the user whose email was given as Initiator).

Please note that the Code field is a string. Its value may look numeric but its
leading zeroes are part of the value.

URL

https://[servername]:[port]/esig/webportalapi/v4/documentgroups

HTTP METHOD

GET

MIME TYPE

application/json

RESPONSE PARAMETERS

Parameter Content / Description Type DocumentGroups List of all document groups
Array of objects Name Name or description of the document group String Code A
unique value identifying each document group String

RESPONSE CODES

Response status code Description 200 OK The document groups gets returned
successfully.

ERROR CODES

HTTP code Code None No error messages possible

EndFragment

HEADERS
Accept

application/json

Example Request
OK

curl

curl --location -g '{{baseUrl}}/documentGroups'

200 OK
Example Response
* Body
* Headers (1)

View More
json

{
"DocumentGroups": [
{
"Code": "<string>",
"Name": "<string>"
},
{
"Code": "<string>",
"Name": "<string>"
}
]
}

Content-Type

application/json

GETRETRIEVES ALL LANGUAGES THAT ARE ENABLED IN THE APPLICATION

{{baseUrl}}/languages

StartFragment

GET ENABLED LANGUAGES

DESCRIPTION

This call retrieves the list of languages that have been enabled in the
eSignatures Configuration Index and are thus available in the eSignatures
Portal.

This call is useful for integrators who need to know which languages are
currently enabled in a given eSignatures installation.

URL

https://[servername]:[port]/esig/webportalapi/v4/languages

HTTP METHOD

GET

MIME TYPE

application/json

RESPONSE PARAMETERS

Parameter Content / Description Type EnabledLanguages List of enabled languages
Array of objects DisplayName DisplayName of the language as defined in the
Config Index. String NativeName NativeName of the language as defined in the
Config Index. The NativeName is the name of the language in its actual language.
E.g. français for French. String IsoCultureCode ISO 639-1 language code of the
language. String

RESPONSE CODES

Response status code Description 200 OK The EnabledLanguages list gets returned
successfully.

ERROR CODES

HTTP Code Code None No errors

EndFragment

HEADERS
Accept

application/json

Example Request
OK

curl

curl --location -g '{{baseUrl}}/languages'

200 OK
Example Response
* Body
* Headers (1)

View More
json

{
"EnabledLanguages": [
{
"DisplayName": "<string>",
"NativeName": "<string>",
"IsoCultureCode": "<string>"
},
{
"DisplayName": "<string>",
"NativeName": "<string>",
"IsoCultureCode": "<string>"
}
]
}

Content-Type

application/json

GETRETRIEVES ALL THEMES THAT CAN BE ASSIGNED TO A PACKAGES

{{baseUrl}}/themes?continuationToken=<string>&maxQuantity=20&sortOrder=desc&sortField=code

StartFragment

GET THEMES

DESCRIPTION

This call retrieves all the Themes, and their code, that are currently created
in the Configuration Index.

The theme code can be entered as a request parameter when doing a Create Package
call. The packages in question will then have the requested theming.

URL

https://[servername]:[port]/esig/webportalapi/v4/themes

HTTP METHOD

GET

MIME TYPE

application/json

QUERY PARAMETERS

RESPONSE PARAMETERS

Parameter Content/Description Type ContinuationToken Token which holds
information about which set of records needs to be returned. String Items List
of themes Array of objects Name Name of the theme String Code Unique id of the
theme String MaxQuantity Maximum number of records Int Total Total number of
records Int

RESPONSE CODES

Response status code Description 200 OK The themes list gets returned
successfully. 400 Bad request A request parameter was invalid

ERROR CODES

HTTP Code Code None No errors

EndFragment

HEADERS
Accept

application/json

PARAMS
continuationToken

The token to return to request the next page

maxQuantity

The maximum number of results to return

sortOrder

desc

specify how the result is sorted, default is ascending

sortField

code

specify on which field to sort

Example Request
OK

View More
curl

curl --location -g '{{baseUrl}}/themes?continuationToken=%3Cstring%3E&maxQuantity=20&sortOrder=desc&sortField=code'

200 OK
Example Response
* Body
* Headers (1)

View More
json

{
"ContinuationToken": "<string>",
"Items": [
{
"Code": "<string>",
"Name": "<string>"
},
{
"Code": "<string>",
"Name": "<string>"
}
],
"MaxQuantity": "<integer>",
"Total": "<integer>"
}

Content-Type

application/json

apidocs.sign.gonitro.com Open in urlscan Pro 3.85.178.40 Public Scan

Form analysis 0 forms found in the DOM

Text Content

apidocs.sign.gonitro.com Open in urlscan Pro
3.85.178.40 Public Scan

Form analysis
0 forms found in the DOM