# Creates a document type

`POST /api/configuration/document-types`

- **Success:** `201 Created`
- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Creates a document type](https://support.gladstonesoftware.cloud/reference/configuration/creates-a-document-type)

## Overview

Defines a new category that member documents can be filed under. A document type is a definition only — creating one does not attach any file to a member; you upload files against an existing type through the member document endpoints.

Two things about this request will surprise you. First, `name` — not `description` — is the type's unique label and the value the rest of the platform matches on, while `description` holds separate free-text notes that are not used for matching. Second, the `name` must be unique across all document types in the tenant — a clash is rejected with `409` before anything is saved.

A successful call returns `201 Created` carrying the new document type's integer id as the response payload, not the object shown under Sample response — that JSON is the shape of the document type as it is read back, not a body you will receive. Read the stored definition back with `GET /api/configuration/document-types/{id}`.

The new type appears on subsequent reads immediately.

## Endpoint

`POST {base_url}/api/configuration/document-types`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | The document type's name, and the value everything else matches on. It is unique and has a maximum of 255 characters, and a document type cannot be saved without one — so in practice you must supply it. It must not duplicate the `name` of an existing document type; a clash is rejected with `409` and `The document type name {name} already exists`. Matching is on the whole string. |
| `description` | string | No | Free-text notes about the type. Maximum 500 characters — a longer value is not caught by request validation and fails with `500`. This value is never used to identify the type; that is `name`'s job. Sending null stores no notes. |
| `isSensitive` | boolean | No | Marks documents of this type as sensitive. Omit it, or send null, and it is stored as `false`. |
| `isAttachment` | boolean | No | Marks the type as an email attachment type. Omit it, or send null, and it defaults to `false`. |

## Sample request

```bash title="cURL"
curl -X POST '{base_url}/api/configuration/document-types' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "isSensitive": true,
  "isAttachment": true
}'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer (int32) | The platform-generated identifier of the new document type, and the only value the create call actually returns — the `201` payload is this integer, not the object below. Use it as `{documentTypeId}` on `GET`, `PUT` and `DELETE /api/configuration/document-types/{documentTypeId}`. |
| `key` | string | A stable, system-generated key for the type, unique across document types. You cannot set or influence it on create. Maximum 55 characters. Only returned by `GET /api/configuration/document-types`. |
| `name` | string | The type's name — that is, the `name` you sent. Only returned by `GET /api/configuration/document-types`. |
| `description` | string | The free-text notes — that is, the `description` you sent. Maximum 500 characters. Only returned by `GET /api/configuration/document-types`. |
| `isSensitive` | boolean | Whether the type is flagged sensitive. Only returned by `GET /api/configuration/document-types`. |
| `isAttachment` | boolean | Whether the type is flagged as an email attachment type. Only returned by `GET /api/configuration/document-types`. |
| `isSystem` | boolean | Whether the type is one Gladstone ships and maintains. Always `false` for a type you create — this endpoint cannot set it. System types cannot be renamed or deleted: `PUT` rejects them with `Document Type ID {id} cannot be changed because it is system` and `DELETE` with `The documentType ID {id} is system.` Only returned by `GET /api/configuration/document-types`. |

## Sample response

```json title="201 Created"
{
  "id": 12345,
  "key": "string",
  "name": "string",
  "description": "string",
  "isSensitive": true,
  "isAttachment": true,
  "isSystem": true
}
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | The request body is not valid — for example `isSensitive` or `isAttachment` sent as a string rather than a boolean. The body is a validation error object keyed by field name. |
| `409` | Conflict | Another document type already uses this `name` — `The document type name {name} already exists`. The check compares against every existing type's `name`, and fires before anything is saved. |
| `409` | Conflict | The clash was detected when saving rather than by the check above — `This entry already exists in the database`. In practice this is the `name` clash again, racing against a concurrent create. |
| `500` | Internal server error | The type could not be saved for any other reason, most commonly `description` exceeding 500 characters or `name` exceeding 255 characters — neither length is enforced by request validation. Nothing is created, and the request is safe to retry once the value is shortened. |