Create an engagement (POST /api/v1/engagements)

Try in Playground sends a real request to app.helvetly.com with a token you paste. It stays in this browser tab only (session storage) and goes to no one else.

POST

/api/v1/engagements

POST

/api/v1/engagements

Creates committed work for a client (a quantity per one-off or recurring period) and opens its due periods. Required: client_id, title, quantity, unit_price; a one-off (recurrence none) also needs end_date. Answers 422 validation_failed with details.fields (including a client, item or document outside the workspace). Not idempotent: a retry creates a second engagement.

Authorization

bearerAuth

headerAuthorizationBearer <token>

A personal API token, hvt_…, with scopes such as read:* or write:invoices

Request Body

application/json

body

client_id?string

Required on create. Cannot change once the engagement has entries or an advance invoice.

title?string

Required on create.

Lengthlength <= 200

description?|

Lengthlength <= 2000

product_id?|

A catalogue item of the workspace.

unit?|

Value in"hour""day""piece""month""km""flat"null

quantity?|

The committed quantity per period, above 0 up to 1000000, up to 3 decimals. Required on create.

billing?string

Default advance.

Value in"advance""arrears"

price_basis?string

Whether unit_price includes VAT. Default net.

Value in"net""gross"

unit_price?|

Per unit, 0 to 100000000.00, 2 decimals. Required on create.

overage_unit_price?||

Price per unit above the commitment; null uses unit_price.

currency?string

ISO 4217. Default: the client's, else the workspace's.

vat_category?string

S (standard) needs vat_rate above 0; the others need 0.

Value in"S""Z""E""AE""K""G""O"

vat_rate?|

Percent, e.g. 8.1. Default: the workspace's rate when VAT-registered.

start_date?string

Default today. Cannot change once the engagement has entries or an advance invoice.

Formatdate

recurrence?string

none is a one-off engagement and needs end_date.

Value in"none""weekly""monthly""quarterly""yearly"

interval?integer

Repeat every n recurrences. Default 1.

Range1 <= value <= 12

end_date?|

Last day; required when recurrence is none.

Formatdate

reference?|

The client's reference or order number.

Lengthlength <= 100

document_id?|

A Document of the workspace, e.g. the signed agreement.

rollover?boolean

Carry unused quantity into the next period. Needs advance billing and a recurring schedule.

auto_invoice?boolean

Let the hourly job draft invoices automatically.

invoice_detail?string

Default summary.

Value in"summary""per_entry"

Response Body

Created

application/json

response

data*

Example Request

curl -X POST 'https://app.helvetly.com/api/v1/engagements' \
  -H 'Content-Type: application/json' \
  -d '{
  "client_id": "cli_01HZ",
  "title": "Support retainer",
  "unit": "hour",
  "quantity": "10",
  "billing": "advance",
  "unit_price": "150.00",
  "currency": "CHF",
  "vat_category": "S",
  "vat_rate": "8.1",
  "start_date": "2026-01-01",
  "recurrence": "monthly",
  "interval": 1
}'

Example Request

curl -X POST 'https://app.helvetly.com/api/v1/engagements' \  -H 'Content-Type: application/json' \  -d '{  "client_id": "cli_01HZ",  "title": "Support retainer",  "unit": "hour",  "quantity": "10",  "billing": "advance",  "unit_price": "150.00",  "currency": "CHF",  "vat_category": "S",  "vat_rate": "8.1",  "start_date": "2026-01-01",  "recurrence": "monthly",  "interval": 1}'

Example ResponseSchema

{
  "data": {
    "id": "string",
    "number": 0,
    "client": {
      "id": "string",
      "number": 0,
      "name": "string"
    },
    "title": "string",
    "description": "string",
    "product_id": "string",
    "unit": "string",
    "quantity": "string",
    "billing": "string",
    "price_basis": "string",
    "unit_price": "1234.50",
    "overage_unit_price": "1234.50",
    "currency": "string",
    "vat_category": "string",
    "vat_rate": "string",
    "start_date": "2019-08-24",
    "recurrence": "string",
    "interval": 0,
    "end_date": "2019-08-24",
    "reference": "string",
    "document_id": "string",
    "cancelled_on": "2019-08-24",
    "rollover": true,
    "auto_invoice": true,
    "invoice_detail": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "unit_price_net": "1234.50",
    "unit_price_gross": "1234.50",
    "status": "scheduled",
    "current_period": {
      "id": "string",
      "index": 0,
      "starts_on": "2019-08-24",
      "ends_on": "2019-08-24",
      "natural_ends_on": "2019-08-24",
      "full_quantity": "string",
      "quantity_manual": true,
      "quantity": "string",
      "unit_price": "1234.50",
      "overage_unit_price": "1234.50",
      "used": "string",
      "invoiced_quantity": "string",
      "advance_invoice": {
        "id": "string",
        "number": "string",
        "status": "string",
        "kind": "string"
      },
      "unearned": "string",
      "carried_in": "string",
      "available": "string",
      "remaining": "string",
      "overage": "string",
      "expected": "string",
      "state": "string",
      "uninvoiced_quantity": "string"
    },
    "attention": [
      "under_pace"
    ]
  }
}

{  "data": {    "id": "string",    "number": 0,    "client": {      "id": "string",      "number": 0,      "name": "string"    },    "title": "string",    "description": "string",    "product_id": "string",    "unit": "string",    "quantity": "string",    "billing": "string",    "price_basis": "string",    "unit_price": "1234.50",    "overage_unit_price": "1234.50",    "currency": "string",    "vat_category": "string",    "vat_rate": "string",    "start_date": "2019-08-24",    "recurrence": "string",    "interval": 0,    "end_date": "2019-08-24",    "reference": "string",    "document_id": "string",    "cancelled_on": "2019-08-24",    "rollover": true,    "auto_invoice": true,    "invoice_detail": "string",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "unit_price_net": "1234.50",    "unit_price_gross": "1234.50",    "status": "scheduled",    "current_period": {      "id": "string",      "index": 0,      "starts_on": "2019-08-24",      "ends_on": "2019-08-24",      "natural_ends_on": "2019-08-24",      "full_quantity": "string",      "quantity_manual": true,      "quantity": "string",      "unit_price": "1234.50",      "overage_unit_price": "1234.50",      "used": "string",      "invoiced_quantity": "string",      "advance_invoice": {        "id": "string",        "number": "string",        "status": "string",        "kind": "string"      },      "unearned": "string",      "carried_in": "string",      "available": "string",      "remaining": "string",      "overage": "string",      "expected": "string",      "state": "string",      "uninvoiced_quantity": "string"    },    "attention": [      "under_pace"    ]  }}

Create an engagement

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Request Body

Response Body