List engagements (GET /api/v1/engagements)

Needs a token with the read:engagements scope (or write:engagements). Authentication

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.

GET

/api/v1/engagements

GET

/api/v1/engagements

Committed work per client with the current period's usage. Default: scheduled and active.

Authorization

bearerAuth

headerAuthorizationBearer <token>

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

Query Parameters

page?integer

Page number, from 1.

Range1 <= value

Default1

page_size?integer

Items per page.

Range1 <= value <= 200

Default50

q?string

Search text.

client_id?string

Only this client's.

status?string

Comma-separated: scheduled, active, ended, cancelled.

attention?string

Only engagements needing this attention.

Value in"under_pace""ending_soon""overage""to_invoice"

sort?string

Default ends.

Value in"ends""-created_at""title""client"

Response Body

application/json

response

data*array<>

meta*

Paging of a list: page/page_size in, totals out.

Example Request

curl -X GET 'https://app.helvetly.com/api/v1/engagements'

Example Request

curl -X GET 'https://app.helvetly.com/api/v1/engagements'

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"
      ]
    }
  ],
  "meta": {
    "page": 0,
    "page_size": 0,
    "total": 0,
    "total_pages": 0
  }
}

{  "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"      ]    }  ],  "meta": {    "page": 0,    "page_size": 0,    "total": 0,    "total_pages": 0  }}

List engagements

AuthorizationCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Query Parameters

Response Body