Overview

SignatureID
SignatureID Overview CONTENTS

Contents
1 Purpose of SignatureID 2
1.1 Signature types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 Simple Electronic Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.2 Advanced Electronic Signature (AES) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.3 Qualified Electronic Signature (QES) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 The Signing Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.1 Signing the Hash of a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.2 Concurrent Signing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Identities 5
2.1 Creating an Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.1 From a VideoID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.2 From a SmileID enrollment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.3 From information already collected by other systems . . . . . . . . . . . . . . . . . . . . . 6
2.2 Updating an Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.3 Retrieving an Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.1 By Identity ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.2 By phone number, email, personal identification number or identification identifier . . . . . 8
2.4 Attaching an identification to an Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.4.1 From a verified VideoID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.4.2 From a requested verification of VideoID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.5 Deleting an Identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 Documents 10
3.1 Uploading a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2 Downloading a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3 Deleting a Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4 Signatures 11
4.1 Requesting a Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 Retrieving Signature Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3 Canceling Signature Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.4 Performing the Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.5 Retrieving Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.6 Retrieving Signatures information by identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.7 Signature Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.7.1 Validation of signed PDF document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.7.2 Validation of signed PDF document already present in repository . . . . . . . . . . . . . . 36

5 Webhooks 36
5.1 Configuring the Webhook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
5.2 Sample Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6 Evidences and Verification 39

6.1 Electronic Signature Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.1.1 Downloading a Signature Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

1
SignatureID Overview 1 PURPOSE OF SIGNATUREID

1 Purpose of SignatureID
The purpose of the signature API is to electronically sign documents in PDF format by using identities that
represent the signers.

1.1 Signature types

There are different types of signatures:

1. Simple Electronic Signature.

2. Advanced Electronic Signature (AES).

3. Qualified Electronic Signature (QES).

The API does not differentiate between types of signature but the final result arises from the combination
of different elements that are detailed in the signature request. These are:

• Identity type: OnSite, SmileID, Verified Video.

• Certificate type: Qualified, Not Qualified.

• Document type: Complete, Hash.

• Second factor authentication type: SMS, Email, Voice, SmileID and Graph.

• Number of signers: One, Several, Several and Concurrent.

Only certain combinations of these elements can be used if what is needed is a qualified signature. Same
for advanced signatures. We can see it in the following table:

Type of
Certificate Identity 2nd factor Documents #signers
signature
SMS, email,
One, several, several
Simple Not qualified OnSite/SmileID voice, SmileID, Complete, Hash
and concurrent
graph
SMS, email, One, several, several
Advanced Not qualified Verified Video Complete, Hash
voice, SmileID and concurrent
Qualified Qualified Verified Video SMS Complete One

1.1.1 Simple Electronic Signature

Simple signing can be used to sign the document or its hash using a not qualified certificate and an OnSite/S-
mileID identity. The second factor authentication can be communicated by SMS, Email, Voice, SmileID or
Graph and there may be one or more signers.

1.1.2 Advanced Electronic Signature (AES)

Advanced signing can be used to sign the document or its hash using a not qualified certificate and a Verified
Video identity. The second factor authentication can be communicated by SMS, Email, Voice or SmileID and
there may be one or more signers.

2
SignatureID Overview 1 PURPOSE OF SIGNATUREID

1.1.3 Qualified Electronic Signature (QES)

Qualified signing can be used to sign the document using a qualified certificate and a Verified Video identity.
The second factor authentication can be communicated by SMS and there may be only one signer.
When performing a QES signature, the type parameter must be set with a value provided by EID support
and the following settings must be enabled for the corresponding VideoID configuration:

• Captcha: enabled for an SMS OTP (six digits), after the face phase.

• Biometrics and Liveness detection check: enabled (hologram phase is optional).

• Security Checks: enabled (reflective surface is optional).

Sample VideoID Settings

{
"retentionPolicy": {
"failed": {
"retention":"permanent"
},
"completed": {
"retention":"permanent"
}
},
"biometrics": {
"enabled":true,
"required":false,
"minSimilarityLevel":"Medium"
},
"faceSpoofing": {
"enabled":true,
"required":false,
"attempts":3
},
"ocr": {
"minConfidenceLevel":"High",
"nonMrzDataExtraction": {
"enabled":true,
"required":false
}
},
"hologram": {
"enabled":false,
"required":false,
"timeout":30
},
"liveness": {
"enabled":true,
"required":false

3
SignatureID Overview 1 PURPOSE OF SIGNATUREID

},
"captcha": {
"enabled":true,
"required":true,
"attempts":3,
"phase":"Face",
"phasePrecedence":"After",
"type":"Sms",
"challengeCode": {
"length":6,
"charset":"numeric"
},
"sms": {
"phonePrefix":"+34"
}
},
"securityChecks": {
"dataIntegrity": {
"enabled":true,
"required":true
},
"sideMatch": {
"enabled":true,
"required":true
},
"reflectiveSurface": {
"enabled":false,
"required":false
},
"notBWCopy": {
"enabled":true,
"required":true
}
}
}
}

1.2 The Signing Process

In general, the signing process consists of the following steps:

1. Upload the document/s to sign. (see section ’Uploading a Document’).

2. Create the identity. (see section ’Creating an Identity’).

3. Make a signature request. (see section ’Requesting a Signature’).

4. Sign the document/s. (see section ’Performing the Signature’).

4
SignatureID Overview 2 IDENTITIES

1.2.1 Signing the Hash of a Document

The hash of a file can be signed using a simple or and advanced signature. For this process there is no need
to upload the document. The steps to obtain the hash are the following:

1. Convert the file to BASE64. Online tool to do it: https://base64.guru/converter/encode/pdf.

2. Calculate the hash 256, 384 or 512. Online tool to do it: https://passwordsgenerator.net/
sha512-hash-generator.

3. Convert the hash to BASE64. Online tool to do it: https://base64.guru/converter/encode/

hex.

The request must be accompanied by the hashSignature parameter with true value. When signing, you
must indicate the value (hash of the encoded file) and algorithm (sha-256, sha-384 or sha-512) parameters.

1.2.2 Concurrent Signing

In the concurrent signature process various identities sign the same document. All the signatures are part of
the same process and it will only be completed when all of the identities have completed the signing.
Before the signature requests of each participant, a concurrent signature process must be created including
their identities and the documents to be signed.

2 Identities
An Identity encapsulates all of a person’s known information, and can be accessed with an ID that uniquely
identifies it.

2.1 Creating an Identity

There are three methods to create an Identity.

2.1.1 From a VideoID

- POST /v2/identities/video

We can use a verification (with parameter verificationId) or a verification request (using parameter verifi-
cationRequestId) from VideoID.
If a verification request is used, identity identification will first have a pending status until the verification is
completed (valid or rejected). The identity data will be updated automatically once the verification is completed.
Likewise, the pending signature processes associated with the identification will be finalized.
A parameter updateIdentityIfExists can be used to indicate if it is possible that there may be an identity
with the same personal number and, in that case, a new identification attached to identity should be created. If
this parameter is not used, an exception will be thrown if an identity with same personal number already exists.

Sample Request

$ curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/identities/video \
-H ’authorization: Bearer <Access-Token>’ \

5
SignatureID Overview 2 IDENTITIES

-H ’content-type: application/json’ \
-d ’{
"verificationId": "afcb339c-0126-44ce-a722-654584e50a75",
"email": "...", // optional
"phone": "...", // optional
"externalReference": "...", // optional
"updateIdentityIfExists": true // optional
}’

2.1.2 From a SmileID enrollment

- POST /v2/identities/smileid

Using information from SmileID enrollment.

Sample Request

$ curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/identities/smileid \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"enrollmentId": "190509de-6028-4c69-8138-1e96a76f6cf0",
"email": "...", // optional
"phone": "..." // optional
}’

2.1.3 From information already collected by other systems

- POST /v2/identities/onsite

This information is typically collected in a face-to-face or other type of identification process.

Sample Request

$ curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/identities/onsite \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"email": "pedro@domain.com",
"nif": "12345678Z",
"phone": "666666666",
"primaryName": "Pedro",
"secondaryName": "Perez Hernandez"
}’

The response is the same for all cases: an Identity with its associated data, including the Identity ID:

6
SignatureID Overview 2 IDENTITIES

Sample Response

{
"id": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"identificationId": "b5642903-8a87-4aca-aebc-13ace642b74b",
"nif": "12345678Z",
"primaryName": "Pedro",
"secondaryName": "Perez Hernandez",
"email": "pedro@domain.com",
"phone": "666666666",
"isNewIdentity" : true
}

In all three cases there is an optional parameter called externalReference. The purpose of this attribute
is to provide room for external identifiers, usually related with the integration process, so that it is possible to
relate the IdentityId with an external reference.
The returned parameter isNewIdentity indicates if a new identity has been created or if an existed identity
has been updated and a new identification has been related to it.

2.2 Updating an Identity

- PUT /v2/identities/<id>

The email and phone fields of an Identity can be updated.

Sample Request

curl -X PUT \
https://etrust-sandbox.electronicid.eu/v2/identities/5bd0e169-2256-4d43... \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"phone": "600600600"
}’

Sample Response

{
"id": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"identificationId": "b5642903-8a87-4aca-aebc-13ace642b74b",
"nif": "12345678Z",
"primaryName": "Pedro",
"secondaryName": "Perez Hernandez",
"email": "pedro@domain.com",
"phone": "600600600"
}

7
SignatureID Overview 2 IDENTITIES

2.3 Retrieving an Identity

2.3.1 By Identity ID

- GET /v2/identities/<id>

Sample Request

curl -X GET \
https://etrust-sandbox.electronicid.eu/v2/identities/5bd0e169-2256-4d43... \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’

2.3.2 By phone number, email, personal identification number or identification identifier

- GET /v2/identities?phone=%2b34600600600

- GET /v2/identities?email=pedro@domain.com

- GET /v2/identities?nif=12345678Z

- GET /v2/identities?identificationId=b5642903-8a87-4aca-aebc-13ace642b74b

Sample Request

curl -X GET \
’https://etrust-sandbox.electronicid.eu/v2/identities?phone=%2b34600600600’ \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’

The response is, in all cases, the data associated to the Identity, including a list of all its identifications.

2.4 Attaching an identification to an Identity

Any identity has an associated identification from which it has been created. Besides, new identifications from
a requested verification or verified VideoID can be added to an existing Identity.

2.4.1 From a verified VideoID

- POST /v2/identities/<id>/video

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/identities/5bd0e169-2256-4d43-a812-
,→ 3c66d6dfba7c/video \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"verificationId": "bf1756d7-e0b6-429a-8f9e-fea5c50db9e0"
}’

8
SignatureID Overview 2 IDENTITIES

2.4.2 From a requested verification of VideoID

- POST /v2/identities/<id>/video

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/identities/5bd0e169-2256-4d43-a812-
,→ 3c66d6dfba7c/video \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"verificationRequestId": "bf1756d7-e0b6-429a-8f9e-fea5c50db9e0"
}’

In both cases there is an optional parameter called externalReference that can be used to save any
information associated to the Identity. The response is the created identification, including Identity ID fields
and Identification ID:

Sample Response

{
"id": "96b638c5-7aed-4791-bafe-87a314fb945f",
"type": "video",
"nif": "12345678Z",
"documentType": "IdCard",
"identity": {
"id": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"primaryName": "Pedro",
"secondaryName": " P r e z H e r n n d e z ",
"email": "pedro@domain.com",
"phone": "600600600"
}
}

2.5 Deleting an Identity

- DELETE /v2/identities/data/<id>

It is possible to delete an identity, and all its identifications, with the obfuscation of its personal data. If any
related information with the identity or its identifications is requested an error will be returned.

Sample Request

curl -X DELETE \
https://etrust-sandbox.electronicid.eu/v2/identities/5bd0e169-2256-4d43... \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’

9
SignatureID Overview 3 DOCUMENTS

3 Documents
SignatureID provides the functionality to electronically sign PDF documents. For this process to happen, an
Identity (associated to the signer of the document) must have been previously created, and a document must
have been uploaded.

3.1 Uploading a Document

- POST /v2/documents

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/documents \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"name": "document.pdf",
"document": "Document encoded in Base64"
}’

Sample Response

{
"documentId": "76304548-7246-489a-b7b6-a88a550d0d49",
"name": "document.pdf",
"creationDate": 1499088026477,
"size": 14990
}

3.2 Downloading a Document

- GET /v2/documents/<id>

Sample Request

curl -X GET \
https://etrust-sandbox.electronicid.eu/v2/documents/633a0c8c-b004-43c9... \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’

The response is the document itself.

3.3 Deleting a Document

- DELETE /v2/documents/<id>

A document that is not related to any signature request or process can be deleted.

10
SignatureID Overview 4 SIGNATURES

Sample Request

curl -X DELETE \
https://etrust-sandbox.electronicid.eu/v2/documents/633a0c8c-b004-43c9... \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’

The response will be an HTTP 200 if all goes ok or an error if it is produced.

Sample Response

{
"errorId": "6b80e169-2256-4d43-a812-3c66d6dfba7c",
"creationDate": 1499093506000,
"error": 1304,
"message": "The document is being used in a signature. DocumentId: 633a0c
,→ 8c-b004-43c9-8a04-4b29fbe3ccd9"
}

4 Signatures
To sign a document, a signature must be requested with a valid Identity ID and Document ID. Depending on
the type of signature process, an OTP (challenge code) might be sent to the person that corresponds to the
Identity through email, SMS or voice. With this code, the user will complete the signature process. More than
one document can be signed at once, with the same challenge code.

4.1 Requesting a Signature

- POST /v2/signatures/request/<otp-type>

The parameter <otp-type> specifies the type of OTP to be performed for signature process, and can be
one of: sms, email, email-sms, voice, graph or smileid.
For the first four types of signature processes, a challenge code is sent to the user via SMS, email, email
and SMS, or a phone call, respectively. For Graph signatures, an image of the hand-written user’s signature is
used as the second authentication factor and no verification code is sent. For SmileID signatures, the biometry
of the user is used as the second authentication factor (through an on-demand SmileID authentication).
Common parameters for all six types of requests include:

• documentsId (Required only for full document signing)

The IDs of the documents to be signed.

• hashSignature (Required only for hash signing. Available for AES signatures)
Boolean value that indicates if signature of a document hash is requested.

• identityId or identificationId (Required one of them)

The ID of the identity or identification performing the signature.

• ttl (Optional)
Indicates, alongside ttlUnit, the time during which the signature request will be valid. If not provided, the
request never expires.

11
SignatureID Overview 4 SIGNATURES

• ttlUnit (Optional)
Indicates the time unit used to interpret the ttl value. It can have one of the following values: s (seconds),
m (minutes), h (hours) or d (days). If not provided, h is assumed.

• externalReference (Optional)
String relative to the client reference identifier for the process. It can have a maximum of 255 characters.

Common parameters for requests involving OTPs include:

• challengeCode (Optional)
Configures the format of the challenge code sent to the user by specifying:

– length: Defaults to 6 for SMS messages, and to 32 for email messages.

– charset: One of alpha, numeric or alphanumeric. Defaults to alphanumeric.

For these types of requests, the placeholder *|challengeCode|* must be used to insert the challenge code
in the message the user will receive. Additionally, the optional *|ttl|* placeholder is available to make explicit to
the user the expiration time of the signature request.
For instance, for the SMS signature request created on the next code snippet, the user would receive a text
message like: "Sign with code: y8e2. Valid for 15m.".

Signature by SMS

- POST /v2/signatures/request/sms

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/request/sms \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"documentsId": [
"633a0c8c-b004-43c9-ac7a-f6127df12162"
],
"identityId": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"message": {
"phone": "666666666",
"text": "Sign with code: *|challengeCode|*. Valid for *|ttl|*.",
"from": "YOUR_COMPANY"
},
"challengeCode": {
"charset": "alphanumeric",
"length": 4
},

"ttl": 15,
"ttlUnit": "m",

12
SignatureID Overview 4 SIGNATURES

"externalReference": "externalID"
}’

If hash of a document needs to be signed, then documentsId parameter must be replaced by hashSigna-
ture attribute with true value.

"hashSignature": true,

The phone and from parameters are optional. If not provided, the phone associated to the Identity and the
Company Name configured on your Dashboard will be used.
For this type of signature, optional type parameter is available to generate qualified electronic certificates.
The value for this parameter must be provided by eID Support Team. Qualified signature requires a quali-
fied certificate, the signer identity has to be created from a VideoID, and phone and email must have been
specified.
There are other optional parameters available:

• challengeCodeReuse, with a boolean value which indicates if VideoID captcha is reused as signa-
ture OTP. In order to reuse the challenge code, it is necessary that the VideoID has been completed a
maximum of 30 minutes ago and a captcha has been validated in the same phone number as the one
associated with the identity in that process.

• verificationFields, parameters to configure additional validations to do with some elements of the pro-
cess. A field video can be added to specify the expiration of the correspondant VideoID process, per-
formed to identify the signer. This parameter only affects to QES requests. This configuration requires
two parameters:

– validityTime: value for the time along VideoID will be valid.

– validityTimeUnit: indicates the time unit used to interpret the validityTime value. It can have one
of the following values: s (seconds), m (minutes), h (hours) or d (days).

Besides, a global configuration by tenant can be made to set the expiration time for VideoID process
related with signer identification. This configuration must be setted by eID support team.

Signature Request with optional parameters

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/request/sms \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"documentsId": [
"633a0c8c-b004-43c9-ac7a-f6127df12162"
],
"identityId": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"message": {
"phone": "666666666",
"text": "Sign with code: *|challengeCode|*. Valid for *|ttl|*.",
"from": "YOUR_COMPANY"
},
"challengeCode": {

13
SignatureID Overview 4 SIGNATURES

"charset": "alphanumeric",
"length": 4
},
"ttl": 15,
"ttlUnit": "m",
"type": "<uuid-provided-by-support>",
"challengeCodeReuse": true,
"verificationFields": {
"video": {
"validityTime": 8,
"validityTimeUnit": "h"
}
}
}’

Signature by Email

- POST /v2/signatures/request/email

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/request/email \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"attachDocuments": true,
"documentsId": [
"633a0c8c-b004-43c9-ac7a-f6127df12162"
],
"identityId": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"message": {
"body": "Sign with code: *|challengeCode|*. Valid for *|ttl|*.",
"subject": "Sign the document",
"to": "pedro@domain.com",
"from": "YOUR_COMPANY_EMAIL",
"fromName": "YOUR_COMPANY"

},
"challengeCode": {
"charset": "alphanumeric",
"length": 4
},
"ttl": 15,
"ttlUnit": "m",
"externalReference": "externalID"
}’

14
SignatureID Overview 4 SIGNATURES

If hash of a document needs to be signed, then documentsId parameter must be replaced by hashSigna-
ture attribute with true value.

"hashSignature": true,

The to, from and fromName parameters are optional. If not provided, the email associated to the Identity,
the Company Email and the Company Name configured on your Dashboard will be used, respectively.
The optional attachDocuments parameter controls whether to attach the documents to be signed to the
email

Signature by Email and SMS

- POST /v2/signatures/request/email-sms

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/request/email-sms \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"attachDocuments": true,
"documentsId": [
"633a0c8c-b004-43c9-ac7a-f6127df12162"
],
"identityId": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"emailMessage": {
"body": "Sign with code: *|challengeCode|*. Valid for *|ttl|*.",
"subject": "Sign the document",
"to": "pedro@domain.com",
"from": "YOUR_COMPANY_EMAIL",
"fromName": "YOUR_COMPANY"
},
"smsMessage": {
"phone": "666666666",
"text": "Sign with code: *|challengeCode|*. Valid for *|ttl|*.",
"from": "YOUR_COMPANY"
},
"emailChallengeCode": {
"charset": "alphanumeric",
"length": 10
},
"smsChallengeCode": {
"charset": "numeric",
"length": 4
},
"ttl": 15,

15
SignatureID Overview 4 SIGNATURES

"ttlUnit": "m",
"externalReference": "externalID"
}’

If hash of a document needs to be signed, then documentsId parameter must be replaced by hashSigna-
ture attribute with true value.

"hashSignature": true,

Signature by Voice

- POST /v2/signatures/request/voice

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/request/voice \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"documentsId": [
"633a0c8c-b004-43c9-ac7a-f6127df12162"
],
"identityId": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"message": {
"phone": "666666666",
"from": "666666666",
"text": "Hi. This is a message from ACME, Inc.. Please take note
of your verification code to complete the signature
process: *|challengeCode|*. We repeat, your
verification code to complete the signature process is
*|challengeCode|*.",
"language": "en"
},
"challengeCode": {
"charset": "alphanumeric",
"length": 4
},
"ttl": 15,
"ttlUnit": "m",
"externalReference": "externalID"
}’

If hash of a document needs to be signed, then documentsId parameter must be replaced by hashSigna-
ture attribute with true value.

"hashSignature": true,

16
SignatureID Overview 4 SIGNATURES

The phone and from parameters are optional. If not provided, the phone associated to the Identity will be
used. The required language parameter specifies the language of the text message to be read on the phone
call, and can be one of: en (English), es (Spanish), it (Italian), fr (French), pt (Portuguese) or de (German).

Signature by Graph

- POST /v2/signatures/request/graph

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/request/graph \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"documentsId": [
"633a0c8c-b004-43c9-ac7a-f6127df12162"
],
"identityId": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"ttl": 15,
"ttlUnit": "m",
"externalReference": "externalID"
}’

If hash of a document needs to be signed, then documentsId parameter must be replaced by hashSigna-
ture attribute with true value.

"hashSignature": true,

Signature by SmileID

- POST /v2/signatures/request/smileid

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/request/smileid \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"documentsId": [
"633a0c8c-b004-43c9-ac7a-f6127df12162"
],
"identityId": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"ttl": 15,
"ttlUnit": "m",
"externalReference": "externalID"
}’

17
SignatureID Overview 4 SIGNATURES

If hash of a document needs to be signed, then documentsId parameter must be replaced by hashSigna-
ture attribute with true value.

"hashSignature": true,

In all six cases, a Signature Request is returned. It is important to note down its requestId, since it will be
needed to complete the signature:

Sample Response

{
"requestId": "69e7a596-f4e2-4875-a656-9e04908e592e",
"creationDate": 1499097724441,
"status": "AwaitingConfirmation",
"ttl": 15,
"ttlUnit": "m",
"type": "<uuid-provided-by-support>",
"identity": {
"id": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"identificationId": "b5642903-8a87-4aca-aebc-13ace642b74b",
"nif": "12345678Z",
"primaryName": "Pedro",
"secondaryName": " P r e z H e r n n d e z ",
"email": "pedro@domain.com",
"phone": "600600600"
},
"documents": [{
"documentId": "633a0c8c-b004-43c9-ac7a-f6127df12162",
"name": "document.pdf",
"creationDate": 1499093506000,
"size": 14990
}],
"email": "pedro@domain.com",
"phone": "666666666",
"externalReference": "externalID"
}

The type field is only returned if type parameter is specified in request for SMS or Email signatures.
In case of hash signature, documents information is not returned in response, rather than public key of
signing certificate in base64 format is returned.

Sample Response

{
... // Other Signature Request fields omitted
"certificate": {
"publicKey": ""MIIGOzCCBCOgAwIBAgITOQAAB3SIGXCI5yv3TQA ... "
}

18
SignatureID Overview 4 SIGNATURES

For SmileID Signatures, an additional authorization field is returned. This is the authorization code that
must be used on the SmileID client (web or mobile SDK) to launch the SmileID the user will be prompted with.
(More information on SmileID signatures below).

Sample Response

{
... // Other Signature Request fields omitted
"authorization": "3fXRl3631LmmgIjQReVZfrmpaBpQ9iy1mz64gnxJAaxcwz6J ... "
}

4.2 Retrieving Signature Requests

- GET /v2/signatures/request/<otp-type>/<id>

The parameter <otp-type> depends on the process, and can be one of: sms, email, email-sms, voice,
graph or smileid.

Sample Request

curl -X GET \
https://etrust-sandbox.electronicid.eu/v2/signatures/request/email/69e7... \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’

Sample Response

{
"requestId": "69e7a596-f4e2-4875-a656-9e04908e592e",
"creationDate": 1499097724441,
"status": "AwaitingConfirmation",
"ttl": 15,
"ttlUnit": "m",
"externalReference": "externalID",
"type": "<uuid-provided-by-support>",
"identity": {
"id": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"identificationId": "b5642903-8a87-4aca-aebc-13ace642b74b",
"nif": "12345678Z",
"primaryName": "Pedro",
"secondaryName": " P r e z H e r n n d e z ",
"email": "pedro@domain.com",
"phone": "600600600"
},
"documents": [{

19
SignatureID Overview 4 SIGNATURES

"documentId": "633a0c8c-b004-43c9-ac7a-f6127df12162",
"name": "document.pdf",
"creationDate": 1499093506000,
"size": 14990
}],
"email": "pedro@domain.com",
"phone": "666666666"
}

The type field is only returned if type parameter is specified in request for SMS or Email signatures.
The status field describes the state of the signature process and can be one of:

• Requested: Newly made signature request.

• AwaitingConfirmation: Initial processing is done (OTPs sent, etc.) and the process is ready to be
completed via a call to the /sign endpoint.

• Pending: Completion of the signature process has been requested but it is pending of verification of
signer’s identification to be successfully completed.

• Completed: The signature process has been successfully completed. For these cases, response will
include an additional signatureId field with signature process identifier.

• Cancelled: The signature process has been cancelled via a call to the /cancel endpoint.

• Expired: The request has expired, as per its ttl configured value.

• Failed: The signature process has failed. For these cases, the returned request will contain an additional
failureReason field will information about the error:

Sample Response

{
"failureReason": {
"errorId": "6b80e169-2256-4d43-a812-3c66d6dfba7c",
"creationDate": 1499093506000,
"error": 1650,
"message": "Unable to send challenge code via SMS."
}
... // Other Signature Request fields omitted
}

4.3 Canceling Signature Requests

- POST /v2/signatures/cancel

Sample Request

20
SignatureID Overview 4 SIGNATURES

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/cancel \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"requestId": "521a0c8c-b004-43c9-ac7a-f6127df12162"
}’

Sample Response

{
"status": "Cancelled",
... // Other Signature Request fields omitted
}

4.4 Performing the Signature

- POST /v2/signatures/sign/<otp-type>

The param <otp-type> depends on the process, and can be one of: sms, email, email-sms, voice, graph
or smileid.
Common parameters for all six types of requests include:

• requestId (Required)
The ID of the signature request to be completed.

• hash (Required only for hash signing)

Hash algorithm (SHA-256, SHA-384 or SHA-512) and hash value of the document to be signed. If no
hash algorithm is specified, then SHA-512 is assumed. Stamp and stamps are not required in this case.

• stamp (Optional)
Configures whether a visible signature stamp will appear on the signed PDF document (see image be-
low).
Its location field comprises:

– page: The number of the page of the document where the stamp will appear.
– left: The distance to the left border of the page.
– top: The distance to the upper border of the page.
– width: The width of the signature stamp.
– height: The height of the signature stamp.

Its additionalFields argument configures whether certain optional fields will be visible on the signature
stamp. Currently supported values include documentId and certificationAuthority.
Its textSettings field comprises:

– dateFormat: date format that will be reflected in the date of stamp. This field is optional, format will
be yyyy/MM/dd HH:mm by default.

21
SignatureID Overview 4 SIGNATURES

– timeZone: time zone format that will be reflected in the date of stamp. This field is optional, timezone
will be GMT+2 by default.
– language: language that will be reflected in the literals of stamp. The value of this parameter must
be in ISO-639-1 standard format. The default value is English, with value en.
– encodingStamp: the encoding of the content of the stamp, “western” (Cp1252) by default. Other
values can be:

* central european (Cp1250)

* cyrilic (Cp1251)
* greek (Cp1253)
* turkish (Cp1254)
* hebrew (Cp1255)
* arab (Cp1256)
* baltic (Cp1257)
* vietnameses (Cp1258)
– encodingSubject: the encoding of the subject of the stamp. Accepted and by default values as in
encodingStamp.

In addition to the location parameter, also a placeholder (searches text in PDF document) can be
specified for the stamp parameter, which will cause signature stamp be displayed at the specified position
on the signed document.
Placeholder parameter requires a text which must be a word existing in document (one or more times)
in which position signature stamp will be displayed. Dimensions for the image can be optionally defined
by width and height parameters. If any of these parameters are not specified default values will be used,
200 for width and 60 for height. In the event that the location and placeholder parameters are indicated,
the signature will be hosted in the position indicated by location parameter but if, on the other hand,
only the placeholder parameter is indicated, that signature will be hosted in the last found location of the
placeholder.
For SMS signatures with qualified certificates, additionalFields, placeholder and textSettings param-
eters are not supported. If this is specified its value will be ignored.
If the stamp parameter is omitted, no visible signature stamp will be added to the signed document. If it
is included, but no location is specified, the values will default to a stamp on the upper left corner of the
first page.

• stamps (Optional)
In the case where multiple documents are specified as part of the signature request, setting the stamp
parameter described in the previous point will add the signature stamp at the same position in every
document. If more flexibility is required, the stamps parameter can be used instead, allowing a specific
configuration to be defined for each document:

22
SignatureID Overview 4 SIGNATURES

{
"requestId": "18e77bce-d7ac-44f2-933f-a56697f4bd56",
"challengeCode": "y8e2",
"stamps": [ // optional
{
"documentId": "84c2bd64-d7aa-438d-b4be-14372a4c112e",
"location": {
"page": 1,
"left": 30,
"top": 30,
"width": 220,
"height": 60
},
"placeholder": {
"text": "placeholderText",
"width": 220,
"height": 60,
},
"textSettings": {
"dateFormat": "dd/MM/yyyy HH:mm",
"timeZone": "GMT+1",
"language": "es"
}
},
{
"documentId": "4878694c-dbab-4cb0-a48b-d2e1397ee18",
"location": {
"page": 3,
"left": 100,
"top": 400,
"width": 200,
"height": 60
},
"additionalFields": {
"documentId": true
}
}
]
}

Common parameters for requests involving OTPs include:

• challengeCode (Required)
The challenge code, as introduced by the user.

23
SignatureID Overview 4 SIGNATURES

Signature by SMS

- POST /v2/signatures/sign/sms

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/sign/sms \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"requestId": "18e77bce-d7ac-44f2-933f-a56697f4bd56",
"challengeCode": "y8e2",
"stamp": { // optional
"location": {
"page": 1,
"left": 30,
"top": 30,
"width": 200,
"height": 60
},
"additionalFields": {
"documentId": true,
"certificationAuthority": true
}
}
}’

For this signature type, challengeCode parameter will not be required only in case challenge code reuse
has been requested.
If hash signature is performed will be also required hash parameter:

"hash": {
"value": "siHZ27CDp/M0KNfCo8MZiuklYU1wIQ4ocWzKp81N23k=",
"algorithm": "SHA-256" // optional
}

Signature by Email

- POST /v2/signatures/sign/email

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/sign/email \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{

24
SignatureID Overview 4 SIGNATURES

"requestId": "ca5169c6-f47a-4259-8bdc-e0460f25d4b7",
"challengeCode": "6t8a",
"stamp": { // optional
"location": {
"page": 1,
"left": 30,
"top": 30,
"width": 200,
"height": 60
},
"additionalFields": {
"documentId": true,
"certificationAuthority": true
}
}
}’

If hash signature is performed will be also required hash parameter:

"hash": {
"value": "siHZ27CDp/M0KNfCo8MZiuklYU1wIQ4ocWzKp81N23k=",
"algorithm": "SHA-256" // optional
}

Signature by Email and SMS

- POST /v2/signatures/sign/email-sms

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/sign/email-sms \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"requestId": "ca5169c6-f47a-4259-8bdc-e0460f25d4b7",
"emailChallengeCode": "6t8a",
"smsChallengeCode": "y8e2",
"stamp": { // optional
"location": {
"page": 1,
"left": 30,
"top": 30,
"width": 200,
"height": 60
},
"additionalFields": {
"documentId": true,

25
SignatureID Overview 4 SIGNATURES

"certificationAuthority": true
}
}
}’

If hash signature is performed will be also required hash parameter:

"hash": {
"value": "siHZ27CDp/M0KNfCo8MZiuklYU1wIQ4ocWzKp81N23k=",
"algorithm": "SHA-256" // optional
}

Signature by Voice

- POST /v2/signatures/sign/voice

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/sign/voice \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"requestId": "18e77bce-d7ac-44f2-933f-a56697f4bd56",
"challengeCode": "y8e2",
"stamp": { // optional
"location": {
"page": 1,
"left": 30,
"top": 30,
"width": 200,
"height": 60
},
"additionalFields": {
"documentId": true,
"certificationAuthority": true
}
}
}’

If hash signature is performed will be also required hash parameter:

"hash": {
"value": "siHZ27CDp/M0KNfCo8MZiuklYU1wIQ4ocWzKp81N23k=",
"algorithm": "SHA-256" // optional
}

26
SignatureID Overview 4 SIGNATURES

Signature by Graph

- POST /v2/signatures/sign/graph

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/sign/graph \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"requestId": "89e77bce-d7ac-44f2-933f-a56697f4bd56",
"stamp": { // optional
"location": {
"page": 1,
"left": 30,
"top": 30,
"width": 200,
"height": 60
},
"additionalFields": {
"documentId": true,
"certificationAuthority": true
}
},
"biometricData": "String with biometric data information from graph
,→ signature",
"graph": {
"image": "Signature image encoded in Base64",
"location": { // optional
"page": 1,
"left": 250,
"top": 30,
"width": 200,
"height": 60
},
"placeholder": {
"text": "placeholderText",
"width": 200,
"height": 60
}
}
}’

If hash signature is performed will be also required hash parameter:

"hash": {
"value": "siHZ27CDp/M0KNfCo8MZiuklYU1wIQ4ocWzKp81N23k=",
"algorithm": "SHA-256" // optional

27
SignatureID Overview 4 SIGNATURES

For Graph signatures, the image of the hand-written signature of the user must be supplied as the value
of the required graph.image parameter. Images must be less than 2 MB in size, at least 100x100 pixels and
conform to one of the following formats: JPG, JPEG, PNG, BMP, GIF or WBMP. This signature also has an
optional parameter biometricData which can be used to add biometric data information from graph signature
as an attachment in signed document. The value can be a free text of up to 1000 characters.
For Graph requests, in addition to the stamp parameter, either one or both of the location and placeholder
(searches text in PDF document) can be specified for the graph parameter, which will cause the image of
the user’s signature provided as part of the request to be displayed at the specified position on the signed
document:

Placeholder parameter requires a text which must be a word existing in document (one or more times) in
which position graph image will be displayed. Dimensions for the image can be optionally defined by width
and height parameters. If any of these parameters are not specified default values will be used, 80 for width
and 60 for height.
If more flexibility is required, a locations parameter can be used instead, allowing a specific graph config-
uration to be defined for each document:
{
"requestId": "89e77bce-d7ac-44f2-933f-a56697f4bd56",
...
"graph": {
"image": "Signature image encoded in Base64",
"locations": [ // optional
{
"documentId": "84c2bd64-d7aa-438d-b4be-14372a4c112e",
"location": {
"page": 1,
"left": 30,
"top": 30,
"width": 200,
"height": 60
},
"placeholder": {
"text": "placeholderText",
"width": 200,
"height": 60
}
},
{
"documentId": "4878694c-dbab-4cb0-a48b-d2e1397ee18",
"location": {

28
SignatureID Overview 4 SIGNATURES

"page": 3,
"left": 100,
"top": 400,
"width": 200,
"height": 60
},
"placeholder": {
"text": "wordToSearchInDocument"
}
}
]
}
}

Signature by SmileID

- POST /v2/signatures/sign/smileid

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/sign/smileid \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"requestId": "89e77bce-d7ac-44f2-933f-a56697f4bd56",
"smileId": "d386477-30bc-43d4-98ea-aa31fd168eb9",
"stamp": { // optional
"location": {
"page": 1,
"left": 30,
"top": 30,
"width": 200,
"height": 60
}
}
}’

If hash signature is performed will be also required hash parameter:

"hash": {
"value": "siHZ27CDp/M0KNfCo8MZiuklYU1wIQ4ocWzKp81N23k=",
"algorithm": "SHA-256" // optional
}

For SmileID signatures, the ID of the SmileID the user has just completed must be supplied as the value
of the required smileId parameter. Note that, in order for this SmileID to be valid to perform the signature, it

29
SignatureID Overview 4 SIGNATURES

must have been launched by supplying the client (web or mobile SDK) with the authorization returned as part
of the response of the signature request call. The following steps summarize this process:

1. Perform the Signature Request

POST /v2/signatures/request/smileid
An authorization is returned as part of the response.

2. Perform the SmileID

(a) Prompt the user with a SmileID authentication (via web or mobile SmileID SDK).
(b) Make sure to use the authorization obtained in the previous step (as opposed to obtaining a fresh
one).
(c) Make sure the user has been previously enrolled on the SmileID service (refer to the SmileID docu-
mentation for more details).

3. Complete the Signature

POST /v2/signatures/sign/smileid
Supply the id of the SmileID completed in the previous step.

In all six cases, a Signature is returned except if deferred signatured is executed. It contains the data
related to the electronic certificate used on the signature process and the IDs of the signed documents, which
can be used to download them.

Sample Response

{
"id": "a218f240-5a1c-44de-947c-11fc58fff8bb",
"requestId": "69e7a596-f4e2-4875-a656-9e04908e592e",
"certificate": {
"serialNumber": "5300000afe372dfd93ab87eaee000000000afe",
"issueDate": 1499099452214,
"revocationDate": 1499099452995,
"type": "SIM",
"isLocked": false,
"owner": {
"id": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"identificationId": "b5642903-8a87-4aca-aebc-13ace642b74b",
"nif": "12345678Z",
"primaryName": "Pedro",
"secondaryName": "Perez Hernandez",
"email": "pedro@domain.com",
"phone": "600600600"
},
"rauthority": {
"name": "Company"
}
},
"signDate": 1499099452951,
"status": "Completed",

30
SignatureID Overview 4 SIGNATURES

"documents": [
{
"signatureId": "a218f240-5a1c-44de-947c-11fc58fff8bb",
"originalDocument": {
"documentId": "633a0c8c-b004-43c9-ac7a-f6127df12162",
"name": "document.pdf",
"creationDate": 1499093506000,
"size": 14990
},
"signedDocument": {
"documentId": "f866ef11-3147-4696-b692-afb6b3063d49",
"name": "document.pdf",
"creationDate": 1499099452263,
"size": 21990
}
}
],
"externalReference": "externalID"
}

In case of hash signing, no documents information is returned in response. Only original and signed hashes
are returned.

"data": {
"originalHash": "siHZ27CDp/M0KNfCo8MZiuklYU1wIQ4ocWzKp81N23k=",
"signedHash": "ZhCWfi9UAzxpYuyD0lj5yCt3eqPaZUd+MCL1Wug6k6..."
}

For qualified signatures, generated by SMS, certificate information returned will be slightly different. The
following image shows information returned for this field.

"certificate": {
"serialNumber": "68991b0909e1517a",
"issuer": "2.5.4.97=VATES-B86681533, CN=ELECTRONIC IDENTIFICATION CA1
,→ , OU=PSC-EID, O=Electronic Identification S.L., L=MADRID, C=ES",
"subject": "CN=Pedro Perez Hernandez, 2.5.4.5=IDCES-12345678Z, 2.5.4.
,→ 42=Pedro, 2.5.4.4=Perez Hernandez, C=ES",
"issueDate": 1610983740000,
"expirationDate": 1611070140000,
"type": "OTC",
"owner": {
"id": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"identificationId": "b5642903-8a87-4aca-aebc-13ace642b74b",
"nif": "12345678Z",
"primaryName": "Pedro",
"secondaryName": "Perez Hernandez",
"email": "pedro@domain.com",
"phone": "600600600"
},

31
SignatureID Overview 4 SIGNATURES

"rauthority": {
"name": "Company"
}
}

When the request is built with an identity with its verification pending, the sign method response will only
include the signature request ID field and the status of the process field, for as long as the verification is
not completed (accepted/rejected). Signature process will be completed automatically when identification’s
verification is accepted and a SignatureCompletedEvent will be thrown:

{
"requestId": "69e7a596-f4e2-4875-a656-9e04908e592e",
"status": "Pending"
}

4.5 Retrieving Signatures

- GET /v2/signatures/sign/<id>

The parameter <id> is the signature process identifier. A complete signature is returned, containing the
data related to the electronic certificate used on the signature process and the IDs of the signed documents,
which can be used to download them.

Sample Request

curl -X GET \
https://etrust-sandbox.electronicid.eu/v2/signatures/sign/a218f240-5a1c... \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’

Sample Response

{
"id": "a218f240-5a1c-44de-947c-11fc58fff8bb",
"requestId": "69e7a596-f4e2-4875-a656-9e04908e592e",
"certificate": {
"serialNumber": "5300000afe372dfd93ab87eaee000000000afe",
"issueDate": 1499099452214,
"revocationDate": 1499099452995,
"type": "SIM",
"isLocked": false,
"owner": {
"id": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"identificationId": "b5642903-8a87-4aca-aebc-13ace642b74b",
"nif": "12345678Z",
"primaryName": "Pedro",
"secondaryName": "Perez Hernandez",

32
SignatureID Overview 4 SIGNATURES

"email": "pedro@domain.com",
"phone": "600600600"
},
"rauthority": {
"name": "Company"
}
},
"signDate": 1499099452951,,
"status": "Completed",
"documents": [
{
"signatureId": "a218f240-5a1c-44de-947c-11fc58fff8bb",
"originalDocument": {
"documentId": "633a0c8c-b004-43c9-ac7a-f6127df12162",
"name": "document.pdf",
"creationDate": 1499093506000,
"size": 14990
},
"signedDocument": {
"documentId": "f866ef11-3147-4696-b692-afb6b3063d49",
"name": "document.pdf",
"creationDate": 1499099452263,
"size": 21990
}
}
],
"externalReference": "externalID"
}

4.6 Retrieving Signatures information by identity

- GET /v2/signatures/request/identity/<id>

The parameter <id> is the identity identifier. A paginated list of signature requests information related with
identity is returned. The results are sorted by signature request creation date in descending order.
Some optional filters can be applied to the search:

• startCreationDate, corresponds with start date of creation of the signature requests for the search. It
must be specified in format YYYY/MM/dd.

• endCreationDate, corresponds with end date of creation of the signature requests for the search. It must
be specified in format YYYY/MM/dd.

• status, indicates the state of the signature process to filter by. The possible status values are: AWAIT-
ING_CONFIRMATION, PENDING, CANCELLED, EXPIRED, COMPLETED, FAILED.

• pageNumber, sets page number of the search result to return. First page is indicated by 0.

• pageSize, sets page size of the search result to return. Default value is 20, and it cannot be greater than
100.

33
SignatureID Overview 4 SIGNATURES

Sample Request

curl -X GET \
https://etrust-sandbox.electronicid.eu/v2/signatures/request/identity/5bd0e16
,→ 9-2256-4d43-a812-3c66d6dfba7c?pageNumber=1&pageSize=3 \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’

Sample Response

{
"items": [
{
"requestId": "03144beb-abef-47c3-9d00-8900a99cded6",
"identificationId": "16d92468-2901-4998-a7df-a8d2654e6c9d",
"status": "Completed",
"creationDate": 1651574490000,
"signatureId": "47532558-0306-411d-bd83-e2a759eda52a",
"signDate": 1651574562000
},
{
"requestId": "08c2beec-b275-49ec-8483-2000d7b53679",
"identificationId": "16d92468-2901-4998-a7df-a8d2654e6c9d",
"status": "AwaitingConfirmation",
"creationDate": 1649167936000,
"externalReference": "extRef047368"
},
{
"requestId": "0ec97582-2301-4847-8d2b-a9a4b3e21b02",
"identificationId": "16d92468-2901-4998-a7df-a8d2654e6c9d",
"status": "Expired",
"creationDate": 1648552629000
}
],
"page": 1,
"size": 3,
"totalPages": 9,
"totalItems": 26
}

The signatureId and signDate fields are only returned if signature request item has a Completed status.

4.7 Signature Validation

4.7.1 Validation of signed PDF document

- POST /v2/signatures/verify

34
SignatureID Overview 4 SIGNATURES

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/verify \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’ \
-d ’{
"document": "<Base64 encoded signed PDF document>",
}’

Sample Response

{
"revisions": [
{
"revision": 1,
"signatureName": "Signature1",
"isTsp": true,
"signCertificate": {
"serialNumber": "d74af664bb5690d",
"issuer": "ACCV",
"subjectName": "TSA1 ACCV 2016",
"signatureAlgorithm": "SHA256WITHRSA",
"notAfter": 1866731870000,
"notBefore": 1456763870000
},
"verifications": [
"Revocation",
"RootCertificate",
"Integrity",
"Signature"
],
"verificationResult": "Valid"
}
],
"verificationResult": "Valid"
}

The revisions array contains the result of individual signatures in a PDF document e.g. If there are two
signatures in a PDF document, then there will be two elements of revisions array.
Each revision contains result of individual signature validation along with other information about the signa-
ture. The other information includes revision number, signature field name, signing certificate information and
the steps performed as part of signature validation.
The VerificationResult element contains result of the complete signed PDF document. Its value is Valid only
if all the signatures in a PDF document are Valid.

35
SignatureID Overview 5 WEBHOOKS

4.7.2 Validation of signed PDF document already present in repository

- POST /v2/signatures/verify/<documentId>

Sample Request

curl -X POST \
https://etrust-sandbox.electronicid.eu/v2/signatures/verify/f866ef11-3147-469
,→ 6-b692-afb6b3063d49 \
-H ’authorization: Bearer <Access-Token>’

Sample Response

{
"revisions": [
{
"revision": 1,
"signatureName": "Signature1",
"isTsp": true,
"signCertificate": {
"serialNumber": "d74af664bb5690d",
"issuer": "ACCV",
"subjectName": "TSA1 ACCV 2016",
"signatureAlgorithm": "SHA256WITHRSA",
"notAfter": 1866731870000,
"notBefore": 1456763870000
},
"verifications": [
"Revocation",
"RootCertificate",
"Integrity",
"Signature"
],
"verificationResult": "Valid"
}
],
"verificationResult": "Valid"
}

5 Webhooks
The SignatureID API uses Webhooks to notify whenever certain events happen. Currently supported event is:

- Signature.Completed: Sent when an asynchronous signature process is completed.

You will need to configure a Webhook listener in your application (over HTTPS) that will receive the notifi-
cation of the event, along with its associated data.

36
SignatureID Overview 5 WEBHOOKS

The listener must respond with a 200 HTTP code to consider the notification as successfully received. If
a different HTTP code is received, or if your listener fails to respond, another attempt to send the notification
will be repeated after 10 minutes, and this process will continue until a 200 HTTP code is received or the 5th
attempt is reached.

5.1 Configuring the Webhook

There is an area in the Dashboard where the configuration of the Webhooks can be done. You can find it the
Settings section:

Parameters:

• Url: Endpoint (your endpoint) where you have configured your listener and the notification will be sent.
Only the port 443 is allowed. Note that the prefix https:// is already included and you don’t need to add it
with your endpoint.

• Authorization Header: A secret passphrase to be sent in the Authorization header.

All events are configured in the same way, and you can use the same URL for more than one event.

5.2 Sample Notifications

Signature.Completed

Sample when signature process completes successfully:

{
"id": "b8924b08-1653-4327-84ea-cb9f58894699",
"tenantId": "4dc0dfd0-cd16-483f-9ae0-b56014043156",
"date": 1625221663736,
"event": "Signature.Completed",
"data": {

37
SignatureID Overview 5 WEBHOOKS

"tenantId": "4dc0dfd0-cd16-483f-9ae0-b56014043156",
"signatureRequestId": "69e7a596-f4e2-4875-a656-9e04908e592e",
"status": "Completed",
"signature": {
"id": "a218f240-5a1c-44de-947c-11fc58fff8bb",
"requestId": "69e7a596-f4e2-4875-a656-9e04908e592e",
"certificate": {
"serialNumber": "68991b0909e1517a",
"issuer": "2.5.4.97=VATES-B86681533, CN=ELECTRONIC IDENTIFICATION
,→ CA1, OU=PSC-EID, O=Electronic Identification S.L., L=MADRID, C=ES",
"subject": "CN=Pedro Perez Hernandez, 2.5.4.5=IDCES-12345678Z
,→ , 2.5.4.42=Pedro, 2.5.4.4=Perez Hernandez, C=ES",
"issueDate": 1610983740000,
"expirationDate": 1611070140000,
"type": "OTC",
"owner": {
"id": "5bd0e169-2256-4d43-a812-3c66d6dfba7c",
"identificationId": "b5642903-8a87-4aca-aebc-13ace642b74b
,→ ",
"nif": "12345678Z",
"primaryName": "Pedro",
"secondaryName": "Perez Hernandez",
"email": "pedro@domain.com",
"phone": "600600600"
},
"rauthority": {
"name": "Company"
}
},
"signDate": 1625221669836,
"status": "Completed",
"externalReference": "externalID",
"documents": [
{
"signatureId": "a218f240-5a1c-44de-947c-11fc58fff8bb",
"originalDocument": {
"documentId": "633a0c8c-b004-43c9-ac7a-f6127df12162",
"name": "document.pdf",
"creationDate": 1499093506000
},
"signedDocument": {
"documentId": "f866ef11-3147-4696-b692-afb6b3063d49",
"name": " document.pdf",
"creationDate": 1499099452263
}
}
]

38
SignatureID Overview 6 EVIDENCES AND VERIFICATION

}
}
}

Sample when signature process fails:

{
"id": "b8924b08-1653-4327-84ea-cb9f58894699",
"tenantId": "4dc0dfd0-cd16-483f-9ae0-b56014043156",
"date": 1625221663736,
"event": "Signature.Completed",
"data": {
"tenantId": "4dc0dfd0-cd16-483f-9ae0-b56014043156",
"signatureRequestId": "69e7a596-f4e2-4875-a656-9e04908e592e",
"status": "Failed",
"externalReference": "externalID",
"failureReason": {
"id": "3e60cef3-ea4d-4760-ad44-06ccf557487f",
"date": 1625221602940,
"error": 1088,
"message": "Identification is not valid for signature."
}
}
}

6 Evidences and Verification

6.1 Electronic Signature Certificates

Electronic Signature Certificates are PDF documents containing legal and technical information regarding the
signature processes and all the signatures contained in the document.

39
SignatureID Overview 6 EVIDENCES AND VERIFICATION

6.1.1 Downloading a Signature Certificate

- GET /v2/documents/voucher/<language>/<id>

The parameter <language> is the language of the voucher (en, es, etc. If the parameter is not a language
supported by the service the voucher will be generated in Spanish by default) and <id> is the ID of the signed
document whose Signature Certificate is going to be downloaded.

Sample Request

curl -X GET \
https://etrust-sandbox.electronicid.eu/v2/documents/voucher/es/f866ef11... \
-H ’authorization: Bearer <Access-Token>’ \
-H ’content-type: application/json’

Sample Response

The certificate itself.

40