> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/digital-signatures/digital-sign.md).

# Digital Sign

This service allows adding globally trusted digital signatures and timestamps to PDF documents. Certificates and signing keys are securely stored on FIPS-compliant cloud hardware devices.

#### Security features

* **Authentication**: The signer's identity is validated by a trusted public certification authority (CA).
* **Integrity**: The document has not been altered after being signed.
* **Non-repudiation**: The signer cannot deny having signed the document.
* **Long-term Validation (LTV)**: Signatures include long-term validation, ensuring they remain valid even after the certificate expires or is revoked.

The service is fully compatible with Adobe products (including Acrobat) and Microsoft Office products (including Word) on platforms such as Windows and Linux.

### Endpoint

```
POST /services/digitalSign
```

### Headers

| Name          | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| **x-api-key** | string | **Yes**  | Access authorization API Key. |

### Request body

**Content-Type:** `application/json`

#### Parameters

| Parameter                              | Type    | Required | Description                                                                              |
| -------------------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------- |
| `endUserContactInfo`                   | string  | **Yes**  | Email address to contact the end user.                                                   |
| `file`                                 | string  | **Yes**  | PDF file encoded in **Base64** to be signed.                                             |
| `signingData`                          | object  | **Yes**  | Object with the signing data.                                                            |
| `signingData.facialAuthenticationHash` | string  | **Yes**  | Hash of the facial authentication process.                                               |
| `signingData.serviceTransactionId`     | string  | **Yes**  | Transaction ID of the previous authentication service.                                   |
| `signingLocation`                      | object  | **Yes**  | Object with the signing location.                                                        |
| `signingLocation.city`                 | string  | **Yes**  | City where the signing takes place.                                                      |
| `signingLocation.country`              | string  | **Yes**  | Country code in format **ISO 3166-1 alpha-3**.                                           |
| `signingLocation.geoLocationPosition`  | string  | No       | Geographic coordinates (optional). Use `"null"` if unavailable.                          |
| `signingLocation.ipAddress`            | string  | No       | Signer IP address (optional). Use `"null"` if unavailable.                               |
| `signingType`                          | string  | **Yes**  | Type of signature to perform. Value: `"1"` for default signature.                        |
| `signatureData`                        | object  | No       | Optional object to include handwritten signature image, page number, and field position. |
| `signatureData.handSignature`          | string  | No       | Image encoded in **Base64** of the handwritten signature.                                |
| `signatureData.pageNumber`             | integer | No       | Page number where the signature should be placed (0-indexed).                            |
| `signatureData.signatureFieldPosition` | string  | No       | Signature field position and size in format `"x,y,width,height"`.                        |

#### Request example

```json
{
  "endUserContactInfo": "user@email.com",
  "file": "JVBERi0xLjUKJbXtrvsKNCAwIG9iag...",
  "signingData": {
    "facialAuthenticationHash": "facialAuthenticationHash",
    "serviceTransactionId": "serviceTransactionId"
  },
  "signingLocation": {
    "city": "City",
    "country": "ISO Alpha-3",
    "geoLocationPosition": "null",
    "ipAddress": "null"
  },
  "signingType": "1",
  "signatureData": {
    "handSignature": "iVBORw0KGgoAAAANSUhEUgAAAEoAAABKCAYAA...",
    "pageNumber": 0,
    "signatureFieldPosition": "100,160,50,50"
  }
}
```

### Responses

#### `200` Success

#### Response parameters

| Parameter              | Type    | Description                                                                                                          |
| ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `serviceTransactionId` | string  | Unique transaction identifier to track the signing operation.                                                        |
| `serviceResultCode`    | integer | Code that indicates the **overall result** of the service execution. See [Service Result Code](#service-result-code) |
| `serviceResultLog`     | string  | Descriptive message related to the result of the operation.                                                          |
| `timestamp`            | string  | Date and time when the signing operation was completed in format **ISO 8601**.                                       |
| `serviceDocument`      | string  | Signed PDF document encoded in **Base64**.                                                                           |

#### Service Result Code

The `serviceResultCode` indicates the overall result of the service execution:

| serviceResultCode | Description                                                                       | HTTP code |
| ----------------- | --------------------------------------------------------------------------------- | --------- |
| 0                 | The service execution was successful, the module processed the request correctly. | 200       |

#### Response example

```json
{
  "serviceTransactionId": "19624424-018c-4e48-b0d6-498c3a497792",
  "serviceResultCode": 0,
  "serviceResultLog": "Executed OK",
  "timestamp": "2025-02-11T11:46:32.190Z",
  "serviceDocument": "JVBERi0xLjUKJbXtrvsK...."
}
```

#### `400` Bad Request

```json
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}
```

#### `401` Unauthorized

```json
{
  "message": "Unauthorized"
}
```

#### `403` Forbidden

```json
{
  "Message": "User is not authorized to access this resource with an explicit deny"
}
```

#### `502` Bad Gateway

```json
{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}
```

#### `504` Gateway Timeout

```json
{
  "message": "Endpoint request timed out"
}
```