> ## Documentation Index
> Fetch the complete documentation index at: https://integration.delogue.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage sample types
> Define the sampling stages used across your brand — proto samples, sales samples, and more — and configure the supplier notifications that fire when each stage changes.
**When to use this.** Sample types are the admin building blocks that power sample requests on styles.
You define them once (e.g. "Proto sample", "Sales sample"), order them to reflect your internal
sampling process, and then select them when creating sample requests on any style. A sample type
cannot be selected for new requests if it is inactive, and it cannot be deleted once it has been
used in a sample request. Configure these before you start working with styles.
## The workflow
A sample type is an organisation-level record. The usual path is to create the sample types,
set up notification preferences for each, reference them on styles, and optionally use season
milestones to anchor deadlines.
`POST /api/sample-types` with the name, state, optional comment deadline, and notification
settings. The server assigns a display position automatically.
Each sample type carries a `notifySettings` list — the sample-request statuses that trigger
an email to the supplier contact when changed from the Dashboard or Sample Report.
Pass the desired statuses in the body, or `null` to seed the organisation default.
`GET /api/sample-types` with optional filters (`State`, `Search`, `Names`) to retrieve
the current set. Use `State=active` to see only types available for new sample requests.
`PUT /api/sample-types/{id}` to deactivate a sample type by setting `state` to `inactive`.
To delete one that has never been used, call `DELETE /api/sample-types/{id}`.
Bulk operations (update and delete in one call) are available via `PUT /api/sample-types`.
```mermaid theme={"dark"}
sequenceDiagram
participant A as Admin
participant API as Delogue API
A->>API: POST /api/sample-types (name, notifySettings)
API-->>A: sample type id + position
A->>API: GET /api/sample-types?State=active
API-->>A: active sample types list
A->>API: PUT /api/sample-types/{id} (state=inactive)
API-->>A: updated sample type
```
## Walkthrough
Create a new sample type called "Salesman sample" with a 5-day comment deadline and four
notification statuses. The body is an array — one or many sample types are created in a single
all-or-nothing transaction.
```bash cURL theme={"dark"}
curl -X POST "https://service.my.delogue.com/api/sample-types" \
-H "Accept: application/json" \
-H "X-Auth-Token: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{
"name": "Salesman sample",
"state": "active",
"commentDeadline": 5,
"notifySettings": [
"Requested",
"Confirmed",
"Sent",
"Received"
]
}
]'
```
```js JavaScript theme={"dark"}
const res = await fetch("https://service.my.delogue.com/api/sample-types", {
method: "POST",
headers: {
"Accept": "application/json",
"X-Auth-Token": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify([
{
"name": "Salesman sample",
"state": "active",
"commentDeadline": 5,
"notifySettings": [
"Requested",
"Confirmed",
"Sent",
"Received"
]
}
]),
});
const { data } = await res.json();
```
```json theme={"dark"}
{
"status": "success",
"code": "sample_types_created",
"data": [
{
"id": 142,
"name": "Salesman sample",
"state": "active",
"commentDeadline": 5,
"position": 4,
"notifySettings": [
"Requested",
"Confirmed",
"Sent",
"Received"
],
"properties": []
}
]
}
```
The response wraps the created sample types in the standard envelope. Hold onto each `id` —
sample requests on styles reference sample types by it.
## Field reference
| Field | What it means at Delogue |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commentDeadline` | Number of days after receipt within which comments are due. Null means no deadline. |
| `name` | Display name of the new sample type. Required. Must be unique within the organization. |
| `notifySettings` | Sample-request statuses that should trigger an email notification to the supplier contact. Null seeds the organization default (all statuses except Planned). An empty array configures no notifications. A non-empty array sets exactly the listed statuses. |
| `state` | Initial lifecycle state. active makes the sample type immediately selectable for new sample requests; inactive creates it in a hidden state. Defaults to active. |
The `Cancelled` status is included in `notifySettings` for completeness but the system does
not send an email notification for it even when toggled on. Notify your supplier manually
when cancelling a sample request through the Dashboard or Report.
## Roles & permissions
Managing sample types requires the **`company`** permission on a **designer (brand)** account —
typically `CompanyAdmin`. Supplier accounts collaborate on sample requests on styles but do not
manage a brand's sample type configuration.
## When things go wrong
Errors use the standard envelope (`status: "error"`, a `code`, and `error.details[]`). See
[Errors & responses](/concepts/errors) for the full list of codes and how to resolve them.
Common cases:
* **400** — `validation_error.required_field` if `name` is missing; `validation_error.conflict` if the name already exists in the organisation.
* **400** — attempting to delete a sample type that is in use by a sample request.
* **404** — `resource_error.sample_type_not_found` if the `{id}` does not belong to the organisation.
## What to call next
Assign milestone dates per sample type on each season so deadlines appear automatically on new sample requests.
Size ranges are required before creating sample requests on styles — set them up alongside sample types.
Organise styles — the home of sample requests — by category.