Manage sample types

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”); the server gives each one a display position that reflects the sequence of your sampling process. You 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.

Create sample types

POST /api/sample-types with the name, state, optional comment deadline, and notification settings. The server assigns a display position automatically.

Configure notifications

Each sample type carries a notifySettings list: the sample-request statuses that trigger an email to the supplier contact when a request is set to that status. Pass the desired statuses in the body, or omit the field (or send null) to use the default of every status except planned.

List and filter

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. Fetch a single sample type with GET /api/sample-types/{id}.

Retire or delete

PUT /api/sample-types/{id} to deactivate a sample type by setting state to inactive. PUT is a full replace: send name, state, commentDeadline and notifySettings as they should end up, because an omitted commentDeadline or notifySettings is cleared. To change one field and keep the rest, use PATCH /api/sample-types/{id} instead. 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.

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.

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"
    ]
  }
]'

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();

{
  "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, unique within the organisation, and must not contain a dot.
`notifySettings`	Sample-request statuses that should trigger an email notification to the supplier contact. Null or omitted uses the default of every status 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 unavailable for new sample requests. Defaults to active; deleted is not accepted.

For a partial update, PATCH /api/sample-types/{id} accepts an RFC 6902 JSON Patch document (Content-Type: application/json-patch+json) and touches only the paths you send: /name, /state, /commentDeadline and /notifySettings; every field you omit keeps its current value. A replace of /commentDeadline to null clears the deadline. A touched /notifySettings is the full set of notifying statuses ([] means none notify). name cannot be cleared and state cannot be removed (400), state cannot be set to deleted (use DELETE /api/sample-types/{id}), and position is server-controlled, so touching it is rejected.

Roles & permissions

Managing sample types requires admin-level sample_types permission on a designer (brand) account: by default, 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 for the full list of codes and how to resolve them. Common cases:

400: validation_error.required_field if name is missing.
400: attempting to delete a sample type that is in use by a sample request.
403: the {id} belongs to a different organisation.
404: resource_error.sample_type_not_found if the {id} exists in no organisation.
409: resource_conflict_error.sample_type_already_exists if the name already exists in the organisation.
409: a JSON Patch test operation fails on PATCH /api/sample-types/{id}.
422: any other JSON Patch operation that cannot be applied.

What to call next

Seasons

Assign milestone dates per sample type on each season so deadlines appear automatically on new sample requests.

Size ranges

Size ranges are required before creating sample requests on styles: set them up alongside sample types.

Style categories

Organise styles, the home of sample requests, by category.

Getting Started

Concepts

Guides

The workflow

Walkthrough

Field reference

Roles & permissions

When things go wrong

What to call next

Seasons

Size ranges

Style categories

​The workflow

​Walkthrough

​Field reference

​Roles & permissions

​When things go wrong

​What to call next

Seasons

Size ranges

Style categories

The workflow

Walkthrough

Field reference

Roles & permissions

When things go wrong

What to call next