API referenceClients
Create a client
Needs a token with the write:clients scope. 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.
POST
Creates a client with the next client number. Only name is required.
bearerAuthheader
AuthorizationBearer <token>A personal API token, hvt_…, with scopes such as read:* or write:invoices
application/json- body
Fields of a client. Blank text or null clears a field; unknown fields are refused (400).
name?stringLength
length <= 200preferred_name?|Length
length <= 200is_company?booleanis_active?booleanemail?|Format
emailLength
length <= 254billing_email?|Format
emailLength
length <= 254phone?|Normalised to E.164.
Length
length <= 30website?|Length
length <= 255street?|Length
length <= 200street_number?|Length
length <= 20apt?|Length
length <= 50zip?|Length
length <= 20city?|Length
length <= 100country?|ISO 3166 alpha-2, e.g. CH.
vat_number?|Swiss UID (CHE-123.456.789) or an EU VAT number.
Length
length <= 30registration_number?|Length
length <= 100language?|Value in
"de""fr""it""en"nullcurrency?|ISO 4217, e.g. CHF.
payment_terms_days?|Range
0 <= value <= 365internal_id?|Length
length <= 100note?|Length
length <= 1000tags?array<>|Items
items <= 10dunning_enabled?booleaneinvoice_format?stringValue in
"none""xrechnung_ubl""xrechnung_cii""peppol"Created
application/json- response
data*curl -X POST 'https://app.helvetly.com/api/v1/clients' \ -H 'Content-Type: application/json' \ -d '{ "name": "Muster AG", "is_company": true, "email": "info@muster.example", "city": "Zurich", "country": "CH", "language": "de", "currency": "CHF", "payment_terms_days": 30, "tags": [ "vip" ]}'Example Response
{ "data": { "id": "string", "number": 0, "name": "string", "preferred_name": "string", "is_company": true, "is_active": true, "email": "string", "billing_email": "string", "phone": "string", "website": "string", "street": "string", "street_number": "string", "apt": "string", "zip": "string", "city": "string", "country": "string", "vat_number": "string", "electronic_address": { "scheme": "string", "id": "string" }, "registration_number": "string", "region": "string", "language": "de", "currency": "string", "payment_terms_days": 0, "internal_id": "string", "note": "string", "tags": [ "string" ], "dunning_enabled": true, "einvoice_format": "none", "leitweg_id": "string", "portal_enabled": true, "portal_invited_at": "2019-08-24T14:15:22Z", "portal_signed_in_at": "2019-08-24T14:15:22Z", "contacts": [ { "id": "string", "name": "string", "role": "string", "email": "string", "phone": "string", "is_primary": true } ], "is_draft": true, "missing_fields": [ "string" ], "files_count": 0, "pending_change_request": true, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }}