Organisations API

Use the canonical /organisations routes for organisation lookup and related registry data. These routes identify an organisation by its Swiss enterprise identification number (UID) or exact legal name.

Operation	Method and path	Purpose
Lookup by UID	`GET /organisations/by-uid/{uid}`	Return detailed organisation data.
Lookup by exact legal name	`GET /organisations/by-name/{name}`	Return detailed organisation data.
List signatories	`GET /organisations/{uid}/signatories`	Return authorised signatories.
Get signing rules	`GET /organisations/{uid}/signatories/rules`	Return signing authorities and competences.
Validate signatories	`POST /organisations/{uid}/signatories/validate`	Check whether a set of signatories can legally sign.
Get ZEFIX excerpt	`GET /organisations/{uid}/excerpt`	Return download details for the cantonal commercial-register excerpt.
Get UID excerpts	`GET /organisations/{uid}/excerpt-uid`	Return excerpts available from the Swiss UID register.

OAuth 2.0 client credentials are required; see Authentication and Authorization. Which of these operations you can call depends on your plan; see Plans and Base URLs. Calling an operation outside your plan returns 401.

The examples below use these variables. Replace the plan segment with your own plan.

BASE_URL="https://api.swisscom.com/products/business-identity-validator/swiss-registry-and-signatory-and-comm-register-excerpt"
TOKEN="<access-token>"
UID="CHE-110.105.931"

Lookup by UID

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

The UID may be supplied with or without separators — both CHE-110.105.931 and CHE110105931 are accepted.

{
  "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,
      "swissZipCodeAddOn": "00",
      "municipalityId": 351,
      "cantonAbbreviation": "BE"
    },
    "countryIdISO2": "CH"
  }
}

warning

The top-level uid (CHE…) is the organisation identifier you reuse in downstream calls. The nested legalForm.uid (for example 0106) is a separate legal-form code from the UID register — it identifies the legal form, not the company, and is never used as a path parameter.

Lookup by exact legal name

Use this operation when the exact registered name is already known:

LEGAL_NAME="Swisscom%20AG"

curl \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/organisations/by-name/$LEGAL_NAME"

URL-encode the name before placing it in the path. Both lookup operations return the same organisation shape.

List signatories

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

{
  "signatories": [
    {
      "personalDetails": "Strasser, Felix, von Aarau, in Küttigen",
      "role": "Member of the Board",
      "signingCompetence": "Individual signing authority"
    }
  ],
  "sourceURL": "https://be.chregister.ch/cr-portal/auszug/auszug.xhtml?uid=CHE-101.654.423",
  "sogcDate": "2025-01-23"
}

Use the personalDetails value as the signer name when validating a combination.

An empty signatories array means the commercial register publishes no signatory section for that entity, which is common for branches. The lookup succeeded. Retrieval failures are 4xx or 5xx. A 500 means the commercial-register excerpt could not be retrieved, so the service could not state whether the entity has signatories.

Get signing rules

Retrieve rules when the workflow needs to explain signing requirements. includeSuggestions=true adds possible valid signer combinations, and includeParsedParams=true adds parsed signatory attributes such as first name, last name, and residence.

curl \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/organisations/$UID/signatories/rules?includeSuggestions=true"

The response always contains rules; suggestions is included only when requested.

{
  "rules": [
    {
      "name": "Zsigray, Zsolt, von Rümlang, in Zürich",
      "role": "secretary (non-member of the board)",
      "groups": [],
      "signingCompetence": {
        "minSigners": 2,
        "requiredRoles": [],
        "requiredGroups": [],
        "mode": "JOINT"
      }
    },
    {
      "name": "Hänni, Frank, von Wengi, in Zürich",
      "role": "chairperson of the board",
      "groups": [],
      "signingCompetence": {
        "minSigners": 2,
        "requiredRoles": [],
        "requiredGroups": [],
        "mode": "JOINT"
      }
    }
  ],
  "suggestions": [
    {
      "explanation": "Valid: Joint signing with 2 signer(s), minimum required: 2",
      "minSigners": 2,
      "satisfiedRules": [
        "Zsigray, Zsolt, von Rümlang, in Zürich",
        "Hänni, Frank, von Wengi, in Zürich"
      ]
    }
  ]
}

Validate signatories

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$BASE_URL/organisations/$UID/signatories/validate" \
  --data '{
    "signers": [
      "Strasser, Felix, von Aarau, in Küttigen"
    ]
  }'

warning

A 200 response means the validation ran, not that the combination is valid. Always check isValid. Status codes in the 4xx and 5xx ranges indicate request, authentication, or server errors rather than a negative validation outcome.

{
  "isValid": true
}

When isValid is true, the response may also include hints. Each hint has a code, a message, and the affected signers. The current hint code is LIMITED_JOINT_SIGNERS.

When validation fails, the response can carry reason, failureCode, and invalidSigners. A role-requirement failure uses failureCode MISSING_REQUIRED_ROLE. requiredRoles on a signing competence names roles that at least one other co-signer in the set must hold. A signer cannot satisfy their own requirement.

{
  "isValid": false,
  "reason": "One or more signers were not found",
  "failureCode": "UNKNOWN_SIGNER",
  "invalidSigners": [
    {
      "name": "Unknown, Person",
      "code": "UNKNOWN_SIGNER",
      "reason": "Signer was not found in the organisation's signing rules"
    }
  ]
}

For normal rule discovery, use the signing rules operation. Add ?includeRules=true only when troubleshooting; the response then also includes rules.

Get ZEFIX excerpt

For an organisation listed in ZEFIX, retrieve its cantonal commercial-register excerpt:

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

The response contains instructions as to where to actually download the document, it does not contain PDF binary data:

{
  "method": "GET",
  "url": "https://.example.com/extract_CHE123456789.pdf?...",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/pdf"
  },
  "body": null,
  "fileName": "extract_CHE123456789.pdf",
  "sourceURL": "https://be.chregister.ch/cr-portal/auszug/auszug.xhtml?uid=CHE-101.654.423"
}

This response contains all the components to create an HTTP request to fetch the actual document. These components include:

URL
HTTP method
Request headers and body that have to be included

If these components are null or empty, they don't have to be supplied with your onwards HTTP request.

When the service has the PDF cached, url is a presigned S3 URL valid for 15 minutes instead of the canton website. Replay method and url as before, and do not store that URL beyond the window.

Get UID excerpts

Use this operation for organisations not listed in ZEFIX, or when all excerpts held by the Swiss UID register are required:

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

The response contains one entry per available excerpt. ehraId is optional; each pdfs entry always contains downloadRequest.

{
  "uid": "CHE-123.456.789",
  "pdfs": [
    {
      "ehraId": "214124",
      "downloadRequest": {
        "method": "POST",
        "url": "https://example.com/download-pdf",
        "headers": {
          "Content-Type": "application/json",
          "Accept": "application/pdf"
        },
        "body": "",
        "fileName": "extract_CHE123456789.pdf",
        "sourceURL": "https://be.chregister.ch/cr-portal/auszug/auszug.xhtml?uid=CHE-101.654.423"
      }
    }
  ]
}

Downloading excerpts safely

Both excerpt operations hand you a request to execute against an external host, so treat the returned values as untrusted input.

Require HTTPS and an approved destination host before issuing the request, and apply response size and time limits.
Treat fileName as untrusted: remove path components, write into a controlled storage directory, and verify the content is a PDF before retaining it.
Do not log the returned headers or request body, which can carry sensitive values.

Lookup by UID​

Lookup by exact legal name​

List signatories​

Get signing rules​

Validate signatories​

Get ZEFIX excerpt​

Get UID excerpts​

Downloading excerpts safely​

Related​