Backend Integration Examples

The CheckName Partner API is designed for backend integrations.

Your frontend, mobile app, or other client application should call your own backend. Your backend should then call the CheckName Partner API using the partner API key.

Never expose the partner API key in browser code, mobile app bundles, desktop client code, or other client-side distributions.

Recommended architecture

Use this request flow:

1. Your user interacts with your frontend or app.
2. Your frontend sends the proposed company name to your backend.
3. Your backend adds the X-API-Key header and calls the CheckName Partner API.
4. Your backend returns only the result data your frontend needs.

This keeps the partner API key inside infrastructure you control and lets you apply your own authentication, rate limits, logging, and business rules.

Before you ship

The examples below are intentionally minimal. In production, add:

• explicit timeout configuration in the upstream HTTP client
• bounded retries for 429 and transient 5xx responses only
• traceId logging for support and diagnostics
• sanitized logging that never records full secrets
• your own stable frontend-facing error contract instead of blindly proxying every upstream detail

What not to do

Do not:

• call https://api.checkname.ch or https://api.test.checkname.ch directly from browser code
• expose the key in JavaScript bundles or mobile apps
• store the partner API key in NEXT_PUBLIC_* environment variables
• return the raw partner API key to any client

Next.js

In Next.js, the correct pattern is to call CheckName from a server-side route handler, not from a client component.

Recommended: route handler on the server

import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const body = await req.json();

  const upstream = await fetch(
    "https://api.test.checkname.ch/v1/name/assessment",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.CHECKNAME_API_KEY!,
      },
      body: JSON.stringify(body),
    }
  );

  const data = await upstream.json();

  return NextResponse.json(data, { status: upstream.status });
}

Use this from a route such as app/api/checkname/assessment/route.ts, then have your frontend call your own route:

const response = await fetch("/api/checkname/assessment", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    companyName: "Alpen Data AG",
    legalForm: "stock_corporation",
    activityScope: "Software development services",
    language: "de",
    legalSeat: "Zurich",
    languageVariants: [],
    checkLevel: "full",
    riskProfile: "balanced",
  }),
});

Do not do this in client code

await fetch("https://api.test.checkname.ch/v1/name/assessment", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.NEXT_PUBLIC_CHECKNAME_API_KEY!,
  },
  body: JSON.stringify(payload),
});

Do not put the partner API key into NEXT_PUBLIC_* variables or any other value exposed to the browser.

Express

import express from "express";

const app = express();
app.use(express.json());

app.post("/api/checkname/assessment", async (req, res) => {
  const upstream = await fetch(
    "https://api.test.checkname.ch/v1/name/assessment",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.CHECKNAME_API_KEY!,
      },
      body: JSON.stringify(req.body),
    }
  );

  const data = await upstream.json();
  res.status(upstream.status).json(data);
});

NestJS

import { Body, Controller, Post } from "@nestjs/common";
import { HttpService } from "@nestjs/axios";
import { firstValueFrom } from "rxjs";

@Controller("checkname")
export class ChecknameController {
  constructor(private readonly http: HttpService) {}

  @Post("assessment")
  async assessment(@Body() body: Record<string, unknown>) {
    const response = await firstValueFrom(
      this.http.post(
        "https://api.test.checkname.ch/v1/name/assessment",
        body,
        {
          headers: {
            "X-API-Key": process.env.CHECKNAME_API_KEY!,
          },
        }
      )
    );

    return response.data;
  }
}

FastAPI

import os

import httpx
from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()


@app.post("/api/checkname/assessment")
async def checkname_assessment(payload: dict):
    async with httpx.AsyncClient() as client:
        upstream = await client.post(
            "https://api.test.checkname.ch/v1/name/assessment",
            json=payload,
            headers={
                "X-API-Key": os.environ["CHECKNAME_API_KEY"],
            },
        )

    return JSONResponse(status_code=upstream.status_code, content=upstream.json())

Key management checklist

• Keep the partner API key in server-side environment variables or a secret manager.
• Use separate keys for sandbox and production.
• Rotate keys after suspected exposure or operational changes.
• Log request metadata and trace IDs, not full secrets.
• Apply your own authentication and authorization before your frontend can trigger calls through your backend.

Related pages

• Use Getting Started > Authentication for header format and key handling guidance.
• Use Getting Started > AI Agent Integration Prompt for a ready-to-copy prompt for Cursor, Copilot, and other coding agents.
• Use Getting Started > Quickstart for your first successful request.
• Use API Reference > Endpoints for current request and response contracts.