Customer

Search and page the customers of the caller's company.

Returns a page of customers (<code>Persons</code> + <code>Companies</code>) of the caller's company, with optional free-text search (<code>search-key</code>) and status filter (<code>status</code>). Results are paged with <code>offset</code> and <code>limit</code>: to retrieve every customer, iterate <code>offset=0, limit, 2×limit, …</code> until a response returns fewer than <code>limit</code> rows. All query parameters are optional; without any, the endpoint returns the first <code>50</code> active customers (downstream default ordering). This is a read-only, idempotent operation. <br/><br/>The tenant and company are derived from the JWT (<code>@CurrentSession Token</code>) and are never accepted as parameters. The caller must be authenticated (<code>apiKeyAuth</code> + <code>bearerAuth</code>) and must hold the <code>FINANCE_GET_CUSTOMER</code> permission on that company; otherwise the endpoint returns <code>403</code>.

get/core/v1/customers

Request

  • Base URL: https://api.klara.ch
  • URL: https://api.klara.ch/core/v1/customers
  • Auth: one of:
    • API key in header X-API-KEY
    • HTTP bearer

Query parameters

limitinteger
Example:50

Page size. Defaults to <code>50</code>; hard cap <code>100</code>. Requests above the cap are rejected with <code>400</code>.

offsetinteger

0-based pagination offset — the number of customers to skip before the returned page. Defaults to <code>0</code>. Combine with <code>limit</code> to walk the full list.

search-keystring
Example:müller

Free-text search across customer <code>name</code>, <code>email</code>, <code>phone</code> and <code>customer number</code>. Tokenised on whitespace; matches are case-insensitive substring matches. Maximum length 256 characters.

status'ACTIVE' | 'ALL' | 'ARCHIVED'
Example:ACTIVE

Filter by customer state. Allowed values: <code>ACTIVE</code>, <code>ALL</code>, <code>ARCHIVED</code>. When omitted, the downstream service applies its default (active customers only).

Response

Customers

idstring

Id of this Customer. Does not need to be included when creating customer

priceCategorystring

You can select / enter a price category. On the articles you can define a special price for this price category. When such an article is sold / invoiced, the price of this category will apply if it is identical for the article and the customer.

customerType'COMPANY' | 'PERSON' required

The type of this partner. Could be either Person or Company.

Example response

[
  {
    "id": "1",
    "person": {
      "website": "www.my-company.com",
      "onlinePlatforms": [
        {
          "id": "1",
          "platformName": "FACEBOOK",
          "platformValue": "www.linkedin.com/abc"
        }
      ],
      "language": "en",
      "responsibleCounterpart": "Mr. Marc",
      "correspondence": "MAIL",
      "id": "1",
      "salutation": "MALE",
      "firstName": "John",
      "lastName": "Henry",
      "birthday": "2020-01-20",
      "addresses": [
        {
          "id": "1",
          "addressLines": "Chemin de la Caquerette 12",
          "addressType": "WORK",
          "cityName": "Bern",
          "cityZipCode": "3003",
          "countryIso2Code": "CH",
          "countryIso3Code": "CHE",
          "countryNumericCode": "756",
          "city_href": "https://api.klara.ch/core/latest/cities/1",
          "definitionName": "2nd address",
          "additionalAddress": "No. 13, street 123"
        }
      ],
      "phones": [
        {
          "id": "1",
          "phoneNumber": "+41783334444",
          "type": "PRIVATE"
        }
      ],
      "emails": [
        {
          "id": "1",
          "emailAddress": "example@gmail.com",
          "type": "PRIVATE"
        }
      ]
    },
    "company": {
      "website": "www.my-company.com",
      "onlinePlatforms": [
        {
          "id": "1",
          "platformName": "FACEBOOK",
          "platformValue": "www.linkedin.com/abc"
        }
      ],
      "language": "en",
      "responsibleCounterpart": "Mr. Marc",
      "correspondence": "MAIL",
      "id": "1",
      "name": "ABC-Corp",
      "phones": [
        {
          "id": "1",
          "phoneNumber": "+41783334444",
          "type": "PRIVATE"
        }
      ],
      "emails": [
        {
          "id": "1",
          "emailAddress": "example@gmail.com",
          "type": "PRIVATE"
        }
      ],
      "addresses": [
        {
          "id": "1",
          "addressLines": "Chemin de la Caquerette 12",
          "addressType": "WORK",
          "cityName": "Bern",
          "cityZipCode": "3003",
          "countryIso2Code": "CH",
          "countryIso3Code": "CHE",
          "countryNumericCode": "756",
          "city_href": "https://api.klara.ch/core/latest/cities/1",
          "definitionName": "2nd address",
          "additionalAddress": "No. 13, street 123"
        }
      ],
      "corporateIdentificationNumber": "CHE-123.456.789",
      "vatNumber": "CHE-123.456.789",
      "hrNumber": "CHE-123.456.789",
      "nogaCode": "1234",
      "foundingDate": "2019-12-20"
    },
    "priceCategory": "Sale price",
    "customerType": "PERSON"
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.