kycnotme/web/src/pages/docs/api.mdx

---
layout: ../../layouts/MarkdownLayout.astro
title: API
updatedAt: 2025-05-31
description: 'Access basic service data via our public API.'
icon: 'ri:plug-line'
---

import { SOURCE_CODE_URL } from 'astro:env/client'
import { kycLevels } from '../../constants/kycLevels'
import { verificationStatuses } from '../../constants/verificationStatus'
import { serviceVisibilities } from '../../constants/serviceVisibility'
import { kycLevelClarifications } from '../../constants/kycLevelClarifications'

Access basic service data via our public API.

All endpoints should be prefixed with `/api/v1/`.

The endpoints <a href={SOURCE_CODE_URL}>source code</a> is available on the `/web/src/actions/api/index.ts` file.

**Attribution:** Please credit **KYCnot.me** if you use data from this API.

## `QUERY` `/service/get`

Fetches details for a single service by various lookup criteria.

### Request Parameters

| Parameter    | Type   | Required | Description                                                                 |
| ------------ | ------ | -------- | --------------------------------------------------------------------------- |
| `id`         | number | No\*     | Service ID                                                                  |
| `slug`       | string | No\*     | Service URL slug (lowercase letters, numbers, and hyphens only)             |
| `serviceUrl` | string | No\*     | Service URL. May be web, onion, or i2p. May just be a domain or a full URL. |

\* At least one of the marked parameters is required.

### Response Format

```typescript
type ServiceResponse = {
  id: number
  slug: string
  name: string
  description: string
  serviceVisibility: 'PUBLIC' | 'ARCHIVED' | 'UNLISTED'
  verificationStatus: 'VERIFICATION_SUCCESS' | 'APPROVED' | 'COMMUNITY_CONTRIBUTED' | 'VERIFICATION_FAILED'
  verificationStatusInfo: {
    value: 'VERIFICATION_SUCCESS' | 'APPROVED' | 'COMMUNITY_CONTRIBUTED' | 'VERIFICATION_FAILED'
    slug: string
    label: string
    labelShort: string
    description: string
  }
  verifiedAt: Date | null
  approvedAt: Date | null
  kycLevel: 0 | 1 | 2 | 3 | 4
  kycLevelInfo: {
    value: 0 | 1 | 2 | 3 | 4
    name: string
    description: string
  }
  kycLevelClarification: 'NONE' | 'DEPENDS_ON_PARTNERS' | ...
  kycLevelClarificationInfo: {
    value: 'NONE' | 'DEPENDS_ON_PARTNERS' | ...
    name: string
    description: string
  }
  categories: {
    name: string
    slug: string
  }[]
  listedAt: Date
  serviceUrls: string[]
  tosUrls: string[]
  kycnotmeUrl: `https://kycnot.me/service/${service.slug}`
}
```

#### KYC Levels

<ul>
  {kycLevels.map((level) => (
    <li key={level.id}>
      <strong>{level.id}</strong>: {level.name} - {level.description}
    </li>
  ))}
</ul>

#### Verification Status

<ul>
  {verificationStatuses.map((status) => (
    <li key={status.value}>
      <strong>{status.value}</strong>: {status.description}
    </li>
  ))}
</ul>

#### Service Visibility

<ul>
  {serviceVisibilities
    .filter(
      (visibility) =>
        visibility.value === 'PUBLIC' || visibility.value === 'ARCHIVED' || visibility.value === 'UNLISTED'
    )
    .map((visibility) => (
      <li key={visibility.value}>
        <strong>{visibility.value}</strong>: {visibility.longDescription}
      </li>
    ))}
</ul>

#### KYC Level Clarifications

<ul>
  {kycLevelClarifications.map((clarification) => (
    <li key={clarification.value}>
      <strong>{clarification.value}</strong>: {clarification.description}
    </li>
  ))}
</ul>

### Examples

#### Request

```zsh
curl -X QUERY https://kycnot.me/api/v1/service/get \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-example-service"}'
```

#### Response

```json
{
  "name": "My Example Service",
  "description": "This is a description of my example service",
  "serviceVisibility": "PUBLIC",
  "verificationStatus": "VERIFICATION_SUCCESS",
  "verificationStatusInfo": {
    "value": "VERIFICATION_SUCCESS",
    "slug": "verified",
    "label": "Verified",
    "labelShort": "Verified",
    "description": "Thoroughly tested and verified by the team. But things might change, this is not a guarantee."
  },
  "verifiedAt": "2025-06-14T11:02:39.294Z",
  "approvedAt": "2025-05-31T19:09:18.043Z",
  "kycLevel": 0,
  "kycLevelInfo": {
    "value": 0,
    "name": "Guaranteed no KYC",
    "description": "Terms explicitly state KYC will never be requested."
  },
  "kycLevelClarification": "NONE",
  "kycLevelClarificationInfo": {
    "value": "NONE",
    "description": "No clarification needed."
  },
  "categories": [
    {
      "name": "Exchange",
      "slug": "exchange"
    }
  ],
  "listedAt": "2025-04-20T07:12:29.393Z",
  "serviceUrls": [
    "https://example.com",
    "http://c9ikae0fdidzh1ufrzp022e5uqfvz6ofxlkycz59cvo6fdxjgx7ekl9e.onion"
  ],
  "tosUrls": ["https://example.com/terms-of-service"],
  "kycnotmeUrl": "https://kycnot.me/service/bisq"
}
```

#### Error Responses

**404 Not Found**: Service not found

```json
{
  "error": "Service not found"
}
```

**400 Bad Request**: Invalid input parameters

```json
{
  "error": "Validation error message"
}
```

**500 Internal Server Error**: Server error

```json
{
  "error": "Internal server error"
}
```