---
title: "Attach documents to process"
method: POST
path: "/api/process/{processId}/attach"
tags: ["Process: create"]
---

# Attach documents to process

`POST /api/process/{processId}/attach`

## Request

- Base URL: `https://sign.swisscom.ch/system`
- URL: `https://sign.swisscom.ch/system/api/process/{processId}/attach`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://sign.swisscom.ch/realms/swisscom-public/protocol/openid-connect/token` scopes: `sswp:process:create`
- TypeScript: <https://skmtc.dev/swisscom/apis/swisscom-sign-integration-api/docs/api/process/:processId/attach/post.ts> (a function with typed inputs; its response is checked against the schema)

Attaches one or more PDF files to the specified process. You may repeat this call up to a maximum of 100 files.
Only `application/pdf` is supported, and each file must not exceed 40MB in size.

**Preconditions:**
- The process status must be `CREATED`.

## Path parameters

- `processId` string, uuid, required

## Request body

- FileAttachment: Represents the configuration for attaching a PDF to a Process
  - `id` string, uuid: Server-assigned file identifier.
  - `name` string, required: Original filename of the PDF. The name is sanitized before it is stored: * Directory parts are removed. * Only letters (including umlauts and accented characters), digits, spaces, `.`, `_` and `-` are kept. All other characters are removed. * Repeated whitespace is collapsed to a single space; leading dots and trailing dots, spaces, `_` and `-` are removed. * Any extension is replaced by `.pdf`. * Reserved Windows device names such as `CON` are prefixed with `document_`. * The stored name is truncated to at most 120 characters including `.pdf`. * An empty name, or a name that is empty after sanitizing, is stored as `document.pdf`. Example: `Vertrag (Kopie).PDF` is stored as `Vertrag Kopie.pdf`.
  - `content` string, byte, required: Content of the PDF as Base64 (OpenAPI format: byte). Max 40 MiB raw.
  - `contentType` string, required: MIME type of the uploaded file. Must be 'application/pdf'.
  - `externalIdentifier` string: Optional client-defined identifier to reference this file.
  - `signaturePositions` union[]: Optional signature positions for this PDF (write-only). Each entry is either a CoordinateSignaturePosition or a TagSignaturePosition. Omitting 'locator' defaults to COORDINATES.
    - union
      - CoordinateSignaturePosition: Signature position defined by explicit page and coordinates (PDF points). Default when 'locator' is absent.
        - `locator` 'COORDINATES' | 'TAG', required: Discriminator. Omit or set to 'COORDINATES'.
        - `signer` string, required: Identifier of the signer (UUID or externalIdentifier).
        - `pageNumber` integer, required: Zero-based page index. Negative values count from the end: -1 = last page.
        - `positionX` integer, required: X-coordinate in PDF points from the left edge of the page.
        - `positionY` integer, required: Y-coordinate in PDF points from the top edge of the page.
        - `stickerProvider` 'VISUAL_SIGNATURE_PROVIDER' | 'CUSTOM_VISUAL_SIGNATURE_PROVIDER': Sticker renderer to use. Default: VISUAL_SIGNATURE_PROVIDER.
      - TagSignaturePosition: Signature position located by searching for a default tag string in the PDF (\s1\ for index 0, \s2\ for index 1, etc.). The tag marks the upper-left corner of the signature field.
        - `locator` 'COORDINATES' | 'TAG', required: Discriminator. Must be 'TAG'.
        - `signer` string, required: Identifier of the signer (UUID or externalIdentifier).
        - `offsetX` integer: Optional X offset in PDF points applied to the resolved tag position. Positive = shift right, negative = shift left. Range: -200 to 200.
        - `offsetY` integer: Optional Y offset in PDF points applied to the resolved tag position. Positive = shift down, negative = shift up. Range: -200 to 200.
        - `stickerProvider` 'VISUAL_SIGNATURE_PROVIDER' | 'CUSTOM_VISUAL_SIGNATURE_PROVIDER': Sticker renderer to use. Default: VISUAL_SIGNATURE_PROVIDER.

## Response `201`

The file has been attached successfully.

- FileAttachResponse: Response object returned when a file is attached to a process.
  - `fileId` string, uuid: System-assigned identifier of the attached file.

## Other responses

- `400`: Invalid request – the process ID is no UUID or the request body failed validation.
- `401`: Authorization information is missing or invalid.
- `403`: Forbidden – the token lacks the scope `sswp:process:create`.
- `404`: Process not found, or it does not belong to the organization of the token.
- `409`: Occurs when there is a general error.
- `415`: Unsupported PDF – dynamic XFA forms cannot be signed.

---

[API](https://skmtc.dev/swisscom/apis/swisscom-sign-integration-api.md) - [All operations](https://skmtc.dev/swisscom/apis/swisscom-sign-integration-api/llms.txt) - [OpenAPI document](https://skmtc.dev/swisscom/apis/swisscom-sign-integration-api/revisions/c7d25e820106?raw)