# Document Class and Envelope Workflow

This guide walks you through the complete workflow to classify a document using a Document Class and send an envelope via the NSE Integration API. By the end you will have created a document class, created an envelope, uploaded a file, classified it with metadata, verified and applied the linked policies, and sent the envelope.

A Document Class is useful when documents must be categorized (for example "Contract" or "Invoice") and automatically routed through a predefined signing workflow based on policies linked to that category.

## Prerequisites

- Feature flag **DocumentClasses** must be enabled for the organization
- A valid **JWT Bearer token** or **Personal Access Token**
- Your **organization ID** (`organizationId`)
- A document ready to upload


## Step 1 — Create a Document Class

A **Document Class** defines a document category (e.g., "Contract") with a set of typed metadata fields. Once created, it can be reused across envelopes and linked to policies.

In the following request we are adding one document class containing one metadata field of type String. Note that you can add multiple metadata fields to a document class, and that `Number` and `Date` are also available as metadata types.

```http
POST /api/v1/organizations/{organizationId}/document-classes
```

```json
{
  "name": "Contracts",
  "description": "Document class for contracts",
  "metadata": [
    {
      "id": 1,
      "name": "Name",
      "type": "StringType",
      "required": true
    }
  ]
}
```

**Response `201 Created`**

```json
{
  "id": "d4e5f6a7-1234-1234-1234-1234567890ab"
}
```

Save the returned `id` — this is your `documentClassId`, used in Step 4.

## Step 2 — Create an Envelope

For a simple configuration we are just creating an envelope with a name and an expiration date.

```http
POST /api/v1/organizations/{organizationId}/envelopes
```

```json
{
  "name": "Name",
  "expiration": {
    "expiresAt": "2026-05-30T18:30:00.000Z",
    "mode": "absolute"
  }
}
```

**Response `201 Created`**

```json
{
  "id": "a1b2c3d4-1234-1234-1234-ef1234567890"
}
```

Save the returned `id` — this is your `envelopeId` for all subsequent steps.

## Step 3 — Upload a File

Upload a PDF (or other supported format) to the envelope. This endpoint uses `multipart/form-data`, not JSON.

```http
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files
Content-Type: multipart/form-data
```

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `file` | binary | Yes | The document file |
| `documentClassId` | string (UUID) | No | Optional — assign the document class at upload time |


**curl example:**

```bash
curl -X POST \
  "https://demo-eu-ie1-api.namirialsign.com/api/organizations/{organizationId}/envelopes/{envelopeId}/files" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/document.pdf"
```

**Response `201 Created`**

```json
{
  "id": "3fa85f64-1234-1234-1234-2c963f66afa6"
}
```

Save the returned `id` — this is your `fileId`, used in the following steps.

## Step 4 — Add the Document Class with Metadata to the File

Associate the document class created in Step 1 with the uploaded file, and supply values for each metadata field.

```http
PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/files/{fileId}
```

```json
{
  "documentClass": {
    "id": "6a1231231231233f5",
    "metadata": [
      {
        "type": "StringType",
        "value": "TEST",
        "id": 1
      }
    ]
  }
}
```

**Response `204 No Content`**

After this step, the file is classified and its metadata is stored. The system can now evaluate which policies apply based on the document class.

## Step 5 — Verify Policies

Before applying the policy, call the **verify** endpoint to check whether the envelope and its classified documents already satisfy the requirements of the associated policies. No changes are made to the envelope.

```http
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/verify-policies
```

```json
{}
```

**Response `200 OK`**

```json
{
  "compliant": false
}
```

## Step 6 — Apply Policies

Call **apply-policies** to populate the envelope with the workflow defined by the linked policies. This automatically adds recipients as configured in the policy.

```http
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/apply-policies
```

```json
{}
```

**Response `204 No Content`**

After this call, the envelope's signing workflow is fully configured by the policy. Recipients and stages are now present on the envelope — verify this by calling the verify endpoint again (Step 7).

## Step 7 — Verify Policies Again

Re-run the verify call after applying the policy to confirm the envelope is complete and consistent.

```http
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/verify-policies
```

```json
{}
```

**Response `200 OK`**

```json
{
  "compliant": true
}
```

If `compliant` is `true`, the conditions configured for the policies are met.

## Step 8 — Send the Envelope

```http
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/send
```

No request body required.

**Response `200 OK`**

```json
{
  "id": "3fa85f64-1234-1234-1234-2c963f66afa6"
}
```

Recipients will now receive email notifications with links to their signing tasks.

For reference documentation explaining the UI side of this topic, see:

- [Document Class](/products/namirialsignenterprise/namirialsignenterprise-knowledge-center/02-products-and-modules/01-nse/02-nse-settings/organization-document-classes)
- [Policies](/products/namirialsignenterprise/namirialsignenterprise-knowledge-center/02-products-and-modules/01-nse/02-nse-settings/organization-policies)