Skip to main content

Quickstart

This page walks you through your first Business Identity Validator requests: obtain an access token, find an organisation, and retrieve its registry data using its Swiss enterprise identification number (UID).

Prepare Authentication​

Complete:

Exit criteria:

  • You have a Bearer access token from the token endpoint.
  • You know your plan name and the matching base URL.

Look Up An Organisation​

Organisation-specific operations use this UID. If you do not know it, start with a search. Set the variables used below, replacing the plan segment with your own plan.

BASE_URL="https://api.swisscom.com/products/business-identity-validator/swiss-registry"
TOKEN="<access-token>"

1. Find the organisation​

Search the ZEFIX and UID registers with a name prefix of at least two characters, or with an exact UID:

curl --get \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "prefix=Ajila" \
  --data "limit=5" \
  "$BASE_URL/suggestions"
[
  { "name": "Ajila AG", "uid": "CHE110105931" },
  { "name": "Ajila Holding AG", "uid": "CHE248743394" }
]

Select the intended result and keep its uid. Do not infer an identity from a partial match.

Exit criteria:

  • You have the UID of the organisation you want.

2. Retrieve the organisation​

UID="CHE-110.105.931"

curl \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/organisations/by-uid/$UID"

The UID is accepted with or without separators, so both CHE-110.105.931 and CHE110105931 work.

{
  "organisationName": "Swisscom AG",
  "uid": "CHE-110105931",
  "legalForm": {
    "uid": "0106",
    "name": "Corporation (Ltd)"
  },
  "address": {
    "addressCategory": "LEGAL",
    "street": "Alte Tiefenaustrasse",
    "houseNumber": "6",
    "town": "Bern",
    "zipCode": {
      "swissZipCode": 3048,
      "cantonAbbreviation": "BE"
    },
    "countryIdISO2": "CH"
  }
}

Exit criteria:

  • A 200 response containing organisationName, uid, legalForm, and address.

From here, use the UID with the Organisations API to query authorised signatories and signing rules, validate a signer combination, or retrieve register excerpts. For failure handling, see Errors and Status Codes.

Sequence Diagram​