AI Agent Integration Prompt

Use this page when you want to give Cursor, Copilot, Claude Code, or another coding agent a ready-to-use prompt for implementing the CheckName Partner API correctly.

What this prompt is for

This prompt is meant for developers who want an AI coding assistant to scaffold or implement the integration in their own codebase.

It is intentionally written to enforce the correct integration pattern:

• backend-only API usage
• no partner API key in client-side code
• POST /v1/name/assessment as the primary endpoint
• POST /v1/name/screening as the convenience one-call screening endpoint
• POST /v1/conflicts/search as the supporting endpoint for already registered identical or similar company names

Copy-paste prompt

Implement a backend integration for the CheckName Partner API in my codebase.

Important constraints:
- This is a backend-only integration.
- Never expose the partner API key in browser code, mobile apps, or other client-side code.
- The frontend must call our own backend.
- Our backend must call the CheckName Partner API with the X-API-Key header.
- Store the API key in a server-side environment variable named CHECKNAME_API_KEY.

Integration goals:
1. Implement POST /v1/name/assessment as the primary integration endpoint.
2. Optionally implement POST /v1/name/screening when one-call bundled screening is preferred.
3. Optionally implement POST /v1/conflicts/search as a supporting endpoint to identify already registered Swiss company names that are identical or similar.
4. Optionally implement POST /v1/trademarks/search only when raw trademark-search output is needed separately from screening.
5. Add clear error handling for 401, 403, 429, and 5xx responses.
6. Preserve and log traceId and, if useful, the mirrored X-Trace-Id header.
7. Keep the implementation secure, minimal, and production-ready.

Business meaning:
- POST /v1/name/assessment evaluates a proposed company name against Swiss company-name rules and EHRA-oriented review logic, then returns the main decision signal for the workflow.
- POST /v1/name/screening is the convenience orchestration endpoint for bundled assessment, conflict search, trademark search, and optional domain checks.
- POST /v1/conflicts/search identifies already registered Swiss company names that are identical or similar and may require warning or review.
- Do not use deprecated eligibility endpoints for new integrations.

Implementation requirements:
- Create or update a server-side route or controller in this project.
- Add a small service/helper module for calling the upstream CheckName API.
- Use the sandbox base URL first: https://api.test.checkname.ch
- Make the upstream base URL configurable via environment variable if appropriate.
- Return only the data needed by the frontend.
- Do not hardcode secrets.
- Do not use NEXT_PUBLIC_* or other client-exposed environment variables for the API key.

If this project has a frontend:
- Make the frontend call our own backend endpoint only.
- Do not call api.checkname.ch directly from client code.

If helpful, implement these internal routes:
- POST /api/checkname/assessment
- POST /api/checkname/screening
- POST /api/checkname/conflicts

Use this request shape for assessment:
{
  "companyName": "Alpen Data AG",
  "legalForm": "stock_corporation",
  "activityScope": "Software development services",
  "language": "de",
  "ownerSurname": null,
  "legalSeat": "Zurich",
  "languageVariants": [],
  "checkLevel": "full",
  "riskProfile": "balanced"
}

Use this request shape for bundled screening:
{
  "companyName": "Alpen Data AG",
  "legalForm": "stock_corporation",
  "activityScope": "Software development services",
  "language": "de",
  "ownerSurname": null,
  "legalSeat": "Zurich",
  "languageVariants": [],
  "checkLevel": "full",
  "riskProfile": "balanced",
  "checks": {
    "ehraCompliance": { "enabled": true },
    "conflicts": { "enabled": true, "limit": 25, "minRisk": "Low" },
    "trademarks": { "enabled": true, "limit": 10, "minRisk": "Low", "niceClasses": [9, 42] },
    "domains": { "enabled": false }
  }
}

Use this request shape for conflict search:
{
  "name": "Alpen Data AG",
  "limit": 25,
  "minRisk": "Low"
}

Please:
- follow the framework conventions already used in this repository
- keep changes small and idiomatic
- explain which files you create or modify
- include short usage notes for local configuration

Framework-specific starter line

You can improve the result by adding one line before the main prompt, for example:

• This is a Next.js app-router project. Use route handlers and keep the API key server-side only.
• This is an Express backend. Add a secure internal endpoint that proxies requests to CheckName.
• This is a NestJS application. Use a controller and service pattern.
• This is a FastAPI backend. Add a router/service implementation using async HTTP calls.

Related pages

• Use Getting Started > Backend Integration Examples for concrete framework examples.
• Use Getting Started > Authentication for header and key-handling rules.
• Use Integration Guides > Overview for how the endpoints relate to each other.