Create express quotation

Requires express quotations to be enabled in the task’s current project. Returns 403 when disabled.

Creates a new express quotation for the specified task. Express quotations are pricing estimates that can be sent to contacts and, when accepted, replace time-based billing with the quotation amount.

What are Express Quotations? Express quotations provide a way to offer fixed-price estimates for tasks instead of billing by time. They:

Link pricing estimates directly to tasks
Can be sent to contacts via email
When accepted, override time-based billing for the task
Include line items with quantities, unit prices, and options
Support tax calculations and multi-language content

How items are generated:

Items are automatically created from task products (if any)
If includeEstimate is true, estimated work time is added as the first item
Each item can have options (variants) with their own pricing
Prices, quantities, and totals are calculated automatically

What is returned:

Complete quotation with all items and options
Calculated subtotal, tax amount, and total
HTML-formatted comment and item descriptions
Quotation status (initially Pending)
Contact user and language information

Note: The task identifier can be either a UUID or numeric shortNumber. The quotation is automatically assigned a sequential shortNumber per task.

POST/tasks/{identifier}/express-quotations

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:write

AuthorizationBearer token (JWT) · headerrequired

Path parameters

identifierstringrequired

Task UUID or numeric shortNumber

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

commentstring

Optional comment or notes for the quotation. Can be provided in HTML or Markdown format. The system will automatically detect the format and convert it to the internal IDoc format. This comment appears on the quotation document when sent to the contact.

contactUserIdstringrequired

UUID of the contact user who will receive the quotation. This user must exist in the workspace and will be the recipient when the quotation is sent via email.

includeEstimatebooleanrequired

If true, includes the task's estimated work time as the first quotation item. The estimated time is converted to an item with the task's hour rate. If false, only products from the task are included as items.

languagestring

Language code for the quotation (e.g., "en" for English, "de" for German). Used for formatting dates, numbers, and generating localized item descriptions. If not provided, the workspace default language is used.

Responses

201

Express quotation created successfully

commentstringrequired

Comment or notes for the quotation, formatted as HTML. This content is converted from the internal IDoc format and appears on the quotation document when sent to the contact.

contactUserIdstringrequired

UUID of the contact user who is the recipient of this quotation. This user receives the quotation when it is sent via email.

createdAtstring<date-time>required

ISO 8601 timestamp when the quotation was created

createdBystringrequired

UUID of the user who created this quotation

idstringrequired

Unique identifier for the quotation (UUID)

itemsExpressQuotationItemResponseDto[]required

Array of all items included in the quotation. Items are ordered by their order field. Each item can have multiple options (variants). Items are typically generated from task products and optionally include estimated work time.

Show properties

Array of ExpressQuotationItemResponseDto

descriptionstringrequired

Detailed description of the item in HTML format. For time-based items, this may include the task summary. For product items, this is the product description. The content is converted from the internal IDoc format to HTML.

idstringrequired

Unique identifier for the quotation item (UUID)

optionsExpressQuotationItemOptionResponseDto[]required

Array of option variants available for this item. Options represent different configurations or variants (e.g., color, size, material) that can be selected, each with its own pricing. An empty array means no options are available.

Show properties

Array of ExpressQuotationItemOptionResponseDto

idstringrequired

Unique identifier for the option (UUID)

titlestringrequired

Display name or title of the option variant (e.g., "Color: Red", "Size: Large", "Material: Premium"). Options represent different variants or configurations of a quotation item.

totalPricenumberrequired

Total price for this option variant, calculated as unitPrice * itemQuantity. This represents the total additional cost when this option is selected for the item.

unitPricenumberrequired

Price per unit for this option variant. This is the additional cost per unit when this option is selected.

quantitynumberrequired

Quantity of units for this item. For time-based items, this is the number of hours. For product items, this is the product quantity.

titlestringrequired

Display title of the item. For time-based items, this typically includes the hours and rate (e.g., "Work time: 1440 hours at 100 EUR each"). For product items, this is the product name.

totalPricenumberrequired

Total price for this item, calculated as quantity * unitPrice. This does not include option prices, which are added separately.

unitstringrequired

Unit of measurement for this item. Can be "Hour" for time-based billing or "Piece" for product-based items.

Allowed:PieceHour

unitPricenumberrequired

Price per unit for this item. For time-based items, this is the hourly rate. For product items, this is the product unit price.

languageobject | nullrequired

Language code used for this quotation (e.g., "en", "de"). Used for formatting and localization. Can be null if not specified, in which case the workspace default is used.

sentAtobject | nullrequired

ISO 8601 timestamp when the quotation was sent via email to the contact user. Null if the quotation has not been sent yet.

shortNumbernumberrequired

Sequential quotation number within the task. The first quotation for a task is 1, the second is 2, etc. This provides a human-readable reference number for the quotation.

statusstringrequired

Current status of the quotation. "Pending" means it has been created but not yet accepted or rejected. "Accepted" means it will be used for billing. "Rejected" means it will not be used for billing. Only one quotation per task can be Accepted at a time.

Allowed:PendingAcceptedRejected

statusChangedBystringrequired

UUID of the user who last changed the quotation status (accepted or rejected). This tracks who made the decision on the quotation.

subTotalnumberrequired

Total amount for all items before tax is applied. This is the sum of all item total prices plus any option prices.

taskIdstringrequired

UUID of the task this quotation is linked to. The quotation affects billing for this task when accepted.

taxnumberrequired

Tax rate percentage applied to the quotation (e.g., 17 for 17% VAT). This is typically taken from the workspace or organization tax settings.

taxAmountnumberrequired

Tax amount calculated from the subtotal and tax rate. Calculated as (subTotal * tax) / 100.

totalnumberrequired

Final total amount including tax. Calculated as subTotal + taxAmount. This is the amount that will be billed if the quotation is accepted.

updatedAtstring<date-time>required

ISO 8601 timestamp when the quotation was last modified

400

Invalid input data or task identifier

401

Unauthorized - Invalid or missing authentication token

403

No access to task project or express quotations are disabled

404

Task not found

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

OAuth2 access tokenRemember on this deviceInclude my values in samples

Parameters

identifierpath*Task UUID or numeric shortNumberfieldsToReturnqueryComma-separated list of top-level response fields to return. Overrides the endpoint compact default unless responseShape=full is used.responseShapequeryAdvanced 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.LT-Response-ShapeheaderAdvanced override. Set to full only when you need the complete endpoint response, including nested fields that are not selectable with fieldsToReturn.

Bodyapplication/json

commentstringOptional comment or notes for the quotation. Can be provided in HTML or Markdown format. The system will automatically detect the format and convert it to the internal IDoc format. This comment appears on the quotation document when sent to the contact.contactUserIdstring*UUID of the contact user who will receive the quotation. This user must exist in the workspace and will be the recipient when the quotation is sent via email.includeEstimateboolean*If true, includes the task's estimated work time as the first quotation item. The estimated time is converted to an item with the task's hour rate. If false, only products from the task are included as items.languagestringLanguage code for the quotation (e.g., "en" for English, "de" for German). Used for formatting dates, numbers, and generating localized item descriptions. If not provided, the workspace default language is used.

Request

curl -X POST "https://leadtime.app/api/public/tasks/550e8400-e29b-41d4-a716-446655440000%20or%20123/express-quotations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "comment": "<p>Please review this quotation and let us know if you have any questions.</p>",
  "contactUserId": "550e8400-e29b-41d4-a716-446655440000",
  "includeEstimate": true,
  "language": "en"
}'

const response = await fetch("https://leadtime.app/api/public/tasks/550e8400-e29b-41d4-a716-446655440000%20or%20123/express-quotations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"comment\": \"<p>Please review this quotation and let us know if you have any questions.</p>\",\n  \"contactUserId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"includeEstimate\": true,\n  \"language\": \"en\"\n}"
});

import requests

response = requests.post(
    "https://leadtime.app/api/public/tasks/550e8400-e29b-41d4-a716-446655440000%20or%20123/express-quotations",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"comment\": \"<p>Please review this quotation and let us know if you have any questions.</p>\",\n  \"contactUserId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"includeEstimate\": true,\n  \"language\": \"en\"\n}",
)

Response

{
  "comment": "<p>Please review this quotation and let us know if you have any questions.</p>",
  "contactUserId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2024-01-01T00:00:00Z",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "items": [
    {
      "description": "<p>Development and implementation of the new feature as described in the task requirements.</p>",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "options": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "title": "Color: Red",
          "totalPrice": 59.9,
          "unitPrice": 5.99
        }
      ],
      "quantity": 1440,
      "title": "Work time: 1440 hours at 100 EUR each",
      "totalPrice": 144000,
      "unit": "Hour",
      "unitPrice": 100
    }
  ],
  "language": "en",
  "sentAt": "2024-01-01T00:00:00Z",
  "shortNumber": 1,
  "status": "Pending",
  "statusChangedBy": "550e8400-e29b-41d4-a716-446655440000",
  "subTotal": 144000,
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "tax": 17,
  "taxAmount": 24480,
  "total": 168480,
  "updatedAt": "2024-01-01T00:00:00Z"
}