Create or update manual position category

Creates a new manual position category or updates an existing one. The operation is determined by whether an id is provided in the request body.

How it works:

Create: Omit the id field (or set it to null) to create a new category
Update: Include the id field with an existing category UUID to update that category

What is returned:

The created or updated category with:
- id: Category identifier (UUID)
- name: Category name

Validation rules:

name: Required, must be a non-empty string
id: Optional, must be a valid UUID if provided

Error handling:

If updating with an id that doesn’t exist, returns 404 Not Found
If validation fails, returns 400 Bad Request with detailed error messages

Note: This endpoint requires the manageManualPositions permission.

POST/workspace/manual-position-categories

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:write

AuthorizationBearer token (JWT) · headerrequired

Query parameters

fieldsToReturnstring

Comma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.

responseShapestring

Advanced override. Omit for the endpoint compact default. Use full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:compactfull

Header parameters

LT-Response-Shapestring

Advanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Allowed:full

Request body

requiredapplication/json

idstring

Category identifier (UUID). When provided, updates the existing category with this ID. When omitted or set to `null`, creates a new category. Must be a valid UUID format if provided.

namestringrequired

Category name. A descriptive label for organizing manual positions. Examples: "Development", "Consulting", "Travel Expenses", "External Services", "Licenses". Must be a non-empty string. Category names are case-sensitive and can be used across all projects in the workspace.

Responses

200

idstringrequired

Unique category identifier. A UUID that uniquely identifies this category within the workspace. Use this ID when assigning the category to manual positions or when updating/deleting the category.

namestringrequired

Category name. The display name of the category as it appears in the application. This is the name that will be shown when the category is assigned to manual positions in offers and invoices.

401Unauthorized - Invalid or missing authentication token

403Forbidden - Insufficient API scopes or permissions

Request

curl -X POST "https://leadtime.app/api/public/workspace/manual-position-categories" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Development"
}'

const response = await fetch("https://leadtime.app/api/public/workspace/manual-position-categories", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Development"
})
});

import requests

response = requests.post(
    "https://leadtime.app/api/public/workspace/manual-position-categories",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Development"
},
)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Development"
}