### Install CH340 Driver on Windows

Source: https://phoneblock.net/phoneblock/dongle

Download and install the CH340 driver on Windows if the dongle is not recognized. No restart is required after installation.

```bash
CH341SER.EXE
```

--------------------------------

### Get Registration Info

Source: https://phoneblock.net/phoneblock/api

Retrieves information required to start a user registration.

```APIDOC
## GET /register

### Description
Retrieve information required to start a user registration.

### Method
GET

### Endpoint
/register
```

--------------------------------

### Dongle Installer Unsupported Message

Source: https://phoneblock.net/phoneblock/link/translations/zh-Hans/dongle

This JavaScript code checks if the Web Serial API is available in the browser. If not, it displays an 'unsupported' message element. This is used for the dongle installer.

```javascript
oneblock.net/dongle/installer/esp-web-tools/install-button.js"
<script>
(function() {
  if (!('serial' in navigator)) {
    var box = document.getElementById('dongle-install-unsupported');
    if (box) {
      box.style.display = '';
    }
  }
})();
</script>
```

--------------------------------

### Get Whitelist

Source: https://phoneblock.net/phoneblock/api

Retrieves the current user's personalized whitelist.

```APIDOC
## GET /whitelist

### Description
Retrieves the current user's personalized whitelist.

### Method
GET

### Endpoint
/whitelist
```

--------------------------------

### Start Registration

Source: https://phoneblock.net/phoneblock/api/phoneblock.json

Initiates a user registration process by retrieving necessary session and captcha information. The returned session ID must be used in subsequent registration requests.

```APIDOC
## GET /register

### Description
Retrieve information required to start a user registration. This endpoint starts a new registration session. The session ID must be added to all following requests during the user registration. The captcha data is a Base64 encoded image that hides a text that must be added to the registration information.

### Method
GET

### Endpoint
/register

### Response
#### Success Response (200)
- **session** (string) - The session ID for the registration process.
- **captcha** (string) - Base64 encoded captcha image data.

#### Response Example
```json
{
  "session": "some_session_id",
  "captcha": "base64_encoded_image_data"
}
```
```

--------------------------------

### Get Blocklist

Source: https://phoneblock.net/phoneblock/api

Retrieves the blocklist with optional incremental synchronization.

```APIDOC
## GET /blocklist

### Description
Retrieves the blocklist with optional incremental synchronization.

### Method
GET

### Endpoint
/blocklist
```

--------------------------------

### GET /register

Source: https://phoneblock.net/phoneblock/api/phoneblock.json

Retrieves a captcha challenge for user registration. This captcha must be solved and submitted along with other registration details.

```APIDOC
## GET /register

### Description
Retrieves a captcha challenge for user registration. This captcha must be solved and submitted along with other registration details.

### Method
GET

### Endpoint
/register

### Response
#### Success Response (200)
- **session** (string) - A unique session identifier for the captcha challenge.
- **captcha** (string) - A Base64 encoded image of the captcha.

#### Response Example
{
  "session": "ehWfZJpRTJ9dQLemiVgY",
  "captcha": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPoAAAA8CAIAAADAPzDDAAAizElEQVR4Xu3deVyN+f/w8fdpX1Ra0EYpSjEhMogosrRIoVCKbNkZ2xCyFIqsmXJJvoTQlkSy..."
}
```

--------------------------------

### Get Account Settings

Source: https://phoneblock.net/phoneblock/api

Retrieves the current user's account settings.

```APIDOC
## GET /account

### Description
Retrieves the current user's account settings.

### Method
GET

### Endpoint
/account
```

--------------------------------

### Get Rating Codes

Source: https://phoneblock.net/phoneblock/api

Retrieves all available rating codes.

```APIDOC
## GET /ratings

### Description
Retrieve all available rating codes.

### Method
GET

### Endpoint
/ratings
```

--------------------------------

### Get Blacklist

Source: https://phoneblock.net/phoneblock/api

Retrieves the current user's personalized blacklist.

```APIDOC
## GET /blacklist

### Description
Retrieves the current user's personalized blacklist.

### Method
GET

### Endpoint
/blacklist
```

--------------------------------

### GET /whitelist

Source: https://phoneblock.net/phoneblock/api/phoneblock.json

Retrieves the current user's personalized whitelist. This endpoint returns a list of phone numbers that the user has explicitly marked as legitimate. Numbers are added to the whitelist by rating them via the POST /api/rate endpoint.

```APIDOC
## GET /whitelist

### Description
Retrieves the current user's personalized whitelist. Returns a list of phone numbers that the user has explicitly marked as legitimate (whitelist). Numbers are added to the whitelist by rating them via the POST /api/rate endpoint with the A_LEGITIMATE rating. This endpoint only retrieves the list; use the rating API to add numbers.

### Method
GET

### Endpoint
/whitelist

### Parameters

### Query Parameters

### Request Body

### Request Example

### Response
#### Success Response (200)
- **numbers** (array) - List of whitelisted phone numbers with details like phone, label, comment, rating, and creation timestamp.

#### Response Example
{
  "numbers": [
    {
      "phone": "+491234567893",
      "label": "(DE) 01234 567893",
      "comment": "My doctor",
      "rating": "A_LEGITIMATE",
      "created": 1709913600000
    },
    {
      "phone": "+491234567894",
      "label": "(DE) 01234 567894",
      "comment": null,
      "rating": null,
      "created": 1709913600000
    }
  ]
}

#### Error Response (401)
- **description**: If no or invalid credentials have been provided.
- **example**: "Please provide login credentials."

#### Error Response (404)
- **description**: User not found.
- **example**: "User not found"
```

--------------------------------

### GET /search/{num}

Source: https://phoneblock.net/phoneblock/api/phoneblock.json

Retrieve extensive information for the given phone number from the PhoneBlock database. This includes details like votes, ratings, and AI summaries.

```APIDOC
## GET /search/{num}

### Description
Retrieve extensive information for the given phone number.

### Method
GET

### Endpoint
/search/{num}

### Parameters
#### Path Parameters
- **num** (string) - Required - Phone number to inspect

#### Query Parameters
- **format** (string) - Optional - The format to return. Defaults to 'json'. Allowed values: 'json', 'xml'.

### Response
#### Success Response (200)
- **phoneId** (string) - Unique identifier for the phone number.
- **info** (object) - General information about the phone number.
  - **phone** (string) - The phone number.
  - **votes** (integer) - Number of votes.
  - **votesWildcard** (integer) - Number of wildcard votes.
  - **rating** (string) - The rating of the phone number (e.g., 'C_POLL').
  - **whiteListed** (boolean) - Indicates if the number is whitelisted.
  - **blackListed** (boolean) - Indicates if the number is blacklisted.
  - **archived** (boolean) - Indicates if the number is archived.
  - **dateAdded** (integer) - Timestamp when the number was added.
  - **lastUpdate** (integer) - Timestamp of the last update.
  - **label** (string) - A label for the phone number.
  - **location** (string) - The location associated with the phone number.
- **topRating** (string) - The top rating for the number (e.g., 'G_FRAUD').
- **ratings** (object) - A breakdown of ratings.
  - **[RatingType]** (integer) - Count for each rating type.
- **searches** (array) - History of searches for this number.
- **aiSummary** (string) - An AI-generated summary of the number's activity.

### Request Example
```json
{
  "example": "{\n  \"phoneId\": \"⚡0123456789\",\n  \"info\": {\n    \"phone\": \"+49123456789\",\n    \"votes\": 42,\n    \"votesWildcard\": 120,\n    \"rating\": \"C_POLL\",\n    \"whiteListed\": false,\n    \"blackListed\": false,\n    \"archived\": false,\n    \"dateAdded\": 1700000000000,\n    \"lastUpdate\": 1710000000000,\n    \"label\": \"(DE) 0123 456789\",\n    \"location\": \"Berlin\"\n  },\n  \"topRating\": \"G_FRAUD\",\n  \"ratings\": {\n    \"G_FRAUD\": 30,\n    \"E_ADVERTISING\": 12\n  },\n  \"searches\": [0, 1, 3, 5, 2, 0, 0, 0, 0, 0, 0, 0],\n  \"aiSummary\": \"Aggressive spam caller attempting fraud.\"\n}" 
}
```

### Response Example
```json
{
  "example": "{\n  \"phoneId\": \"⚡0123456789\",\n  \"info\": {\n    \"phone\": \"+49123456789\",\n    \"votes\": 42,\n    \"votesWildcard\": 120,\n    \"rating\": \"C_POLL\",\n    \"whiteListed\": false,\n    \"blackListed\": false,\n    \"archived\": false,\n    \"dateAdded\": 1700000000000,\n    \"lastUpdate\": 1710000000000,\n    \"label\": \"(DE) 0123 456789\",\n    \"location\": \"Berlin\"\n  },\n  \"topRating\": \"G_FRAUD\",\n  \"ratings\": {\n    \"G_FRAUD\": 30,\n    \"E_ADVERTISING\": 12\n  },\n  \"searches\": [0, 1, 3, 5, 2, 0, 0, 0, 0, 0, 0, 0],\n  \"aiSummary\": \"Aggressive spam caller attempting fraud.\"\n}" 
}
```
```

--------------------------------

### Demonstrate Hash Computation

Source: https://phoneblock.net/phoneblock/api

Demonstrates hash computation for the /check API (for testing and debugging only).

```APIDOC
## GET /hash

### Description
Demonstrates hash computation for the /check API (for testing and debugging only, otherwise there is no privacy benefit).

### Method
GET

### Endpoint
/hash
```

--------------------------------

### POST /register

Source: https://phoneblock.net/phoneblock/api/phoneblock.json

Registers a new user by submitting their email address and the answer to a captcha challenge.

```APIDOC
## POST /register

### Description
Registers a new user by submitting their email address and the answer to a captcha challenge.

### Method
POST

### Endpoint
/register

### Parameters
#### Request Body
- **session** (string) - Required - The session identifier obtained from the GET /register request.
- **answer** (string) - Required - The user's answer to the captcha challenge.
- **email** (string) - Required - The user's email address.

### Request Example
{
  "session": "ehWfZJpRTJ9dQLemiVgY",
  "answer": "ABCDEFG123",
  "email": "whoami@company.de"
}

### Response
#### Success Response (200)
An email containing a registration code will be sent to the provided email address.

#### Response Example
"An e-mail was successfully sent to the provided e-mail address. The e-mail contains a registration code, that the user must provide to the final call to the verify request to receive the login credentials."
```

--------------------------------

### Register User

Source: https://phoneblock.net/phoneblock/api

Registers a new user.

```APIDOC
## POST /register

### Description
Register a new user.

### Method
POST

### Endpoint
/register
```

--------------------------------

### API HTML Structure

Source: https://phoneblock.net/phoneblock/link/translations/zh-Hans/api

This HTML snippet sets up the basic structure for the API documentation page. It includes placeholders for head content, links to Swagger UI assets, and the main section for the UI. It also includes JavaScript for API functionality and context path information.

```html
<!DOCTYPE html>
<html>
<head>
  <th:block th:replace="~{fragments/page :: headContent(titleKey='page.api.title', descriptionKey='page.api.description', titleText=null, descriptionText=null)}"></th:block>
  <link rel="stylesheet" th:href="|${contextPath}${deps.swagger}/swagger-ui.css|"/>
</head>
<body th:dir="${currentLang.direction}">
  <div th:replace="~{fragments/page :: header}"></div>
  <section class="section" id="swagger-ui">
  </section>
  <script th:src="|${contextPath}${deps.swagger}/swagger-ui-bundle.js|"></script>
  <script th:src="@{/assets/js/api.js}" type="text/javascript"></script>
  <input id="context-path" th:value="${contextPath}" type="hidden"/>
  <div th:replace="~{fragments/page :: footer}"></div>
</body>
</html>
```

--------------------------------

### GET /ratings

Source: https://phoneblock.net/phoneblock/api/phoneblock.json

Retrieves a list of all available rating codes that can be used when rating a phone number.

```APIDOC
## GET /ratings

### Description
Retrieves a list of all available rating codes that can be used when rating a phone number.

### Method
GET

### Endpoint
/ratings

### Parameters
#### Query Parameters
- **format** (string) - Optional - The format to return the data in. Allowed values: "json", "xml". Defaults to "json".

### Response
#### Success Response (200)
- **values** (array of strings) - A list of available rating codes.

#### Response Example
{
  "values": [
    "A_LEGITIMATE",
    "B_MISSED",
    "C_PING",
    "D_POLL",
    "E_ADVERTISING",
    "F_GAMBLE",
    "G_FRAUD"
  ]
}
```

--------------------------------

### POST /verify

Source: https://phoneblock.net/phoneblock/api/phoneblock.json

Verifies a user's registration using the code sent to their email address and provides login credentials.

```APIDOC
## POST /verify

### Description
Verifies a user's registration using the code sent to their email address and provides login credentials.

### Method
POST

### Endpoint
/verify

### Parameters
#### Request Body
- **session** (string) - Required - The session identifier.
- **code** (string) - Required - The registration code received via email.

### Request Example
{
  "session": "xxxx",
  "code": "123456"
}

### Response
#### Success Response (200)
- **session** (string) - A new session identifier.
- **login** (string) - The user's login identifier.
- **password** (string) - The user's password.

#### Response Example
{
  "session": "ehWfZJpRTJ9dQLemiVgY",
  "login": "6d8f7262-faa6-41bc-adb4-50a6013c2b07",
  "password": "5s4df6s5df"
}
```

--------------------------------

### AccountSettings Schema

Source: https://phoneblock.net/phoneblock/api/phoneblock.json

Represents the current settings for a user's account, including language, dial prefix, and display name.

```APIDOC
## AccountSettings Schema

### Description
User account settings

### Properties
- **lang** (string) - Optional - Preferred language tag. Example: 'de-DE'.
- **dialPrefix** (string) - Optional - User's country dial prefix. Example: '+49'.
- **displayName** (string) - Optional - User's display name. Example: 'John Doe'.
```

--------------------------------

### GET /blacklist

Source: https://phoneblock.net/phoneblock/api/phoneblock.json

Retrieves the current user's personalized blacklist. This endpoint returns a list of phone numbers that the user has explicitly marked as blocked. Numbers are typically added to the blacklist via the rating API.

```APIDOC
## GET /blacklist

### Description
Retrieves the current user's personalized blacklist. Returns a list of phone numbers that the user has explicitly marked as blocked (blacklist). Numbers are added to the blacklist by rating them via the POST /api/rate endpoint with spam ratings such as E_ADVERTISING, F_GAMBLE, or G_FRAUD. This endpoint only retrieves the list; use the rating API to add numbers.

### Method
GET

### Endpoint
/blacklist

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **numbers** (array) - A list of blacklisted numbers, each with phone, label, comment, rating, and creation timestamp.

#### Response Example
{
  "numbers": [
    {
      "phone": "+491234567890",
      "label": "(DE) 01234 567890",
      "comment": "Spam caller",
      "rating": "G_FRAUD",
      "created": 1709913600000
    },
    {
      "phone": "+491234567891",
      "label": "(DE) 01234 567891",
      "comment": null,
      "rating": null,
      "created": 1709913600000
    }
  ]
}

#### Error Response (401)
- **description**: If no or invalid credentials have been provided.
- **content**: text/plain
- **example**: "Please provide login credentials."

#### Error Response (404)
- **description**: User not found.
- **content**: text/plain
- **example**: "User not found"
```

--------------------------------

### Get Blocklist

Source: https://phoneblock.net/phoneblock/api/phoneblock.json

Retrieves all active phone numbers from the PhoneBlock database along with their vote counts. Supports full synchronization or incremental updates based on a 'since' version. Numbers with 0 votes indicate removal from the client's local blocklist.

```APIDOC
## GET /api/phoneblock

### Description
Returns all active phone numbers from the blocklist with their actual vote counts. Numbers below the server's minimum vote threshold are excluded from the full blocklist and returned with votes=0 in incremental updates (indicating removal). When 'since' is omitted, returns the complete blocklist. When 'since' is provided, returns only changes since that version (incremental sync). Entries with votes=0 indicate the number should be removed from the client's local blocklist.

**Important:** This endpoint returns only the community-maintained blocklist data. It does NOT include user-specific personalizations (personal blacklist/whitelist). For call filtering, clients must check BOTH the community blocklist AND the user's personal black/whitelist entries (retrieved via /api/blacklist and /api/whitelist). Personal whitelist entries should override community blocklist entries, and personal blacklist entries should block calls regardless of community ratings.

**Rate Limits:** To avoid excessive server load, clients should limit full synchronization (without 'since' parameter) to a maximum of once per month. Incremental synchronization (with 'since' parameter) should be performed at most once per day. Clients exceeding these limits may be subject to rate limiting.

**Implementation:** Perform an initial full sync to retrieve the complete blocklist and its version number. Store this data locally and save the version number. For subsequent updates, use the saved version number in the 'since' parameter to retrieve only changes. Apply the incremental updates to your local copy: add/update entries with votes > 0, remove entries with votes = 0. After each sync, update your saved version number to the one returned in the response.

### Method
GET

### Endpoint
/api/phoneblock

### Parameters
#### Query Parameters
- **since** (integer) - Optional - Optional version number for incremental synchronization. When provided, returns only changes since the specified version. Entries with votes=0 indicate the number dropped below the minimum threshold and should be removed from the client's local blocklist.
- **format** (string) - Optional - The format to return. Defaults to "json". Enum: ["json", "xml"]

### Response
#### Success Response (200)
- **numbers** (array) - An array of phone number objects.
  - **phone** (string) - The phone number.
  - **rating** (string) - The rating of the phone number. Enum: ["A_LEGITIMATE", "B_MISSED", "C_PING", "D_POLL", "E_ADVERTISING", "F_GAMBLE", "G_FRAUD"]
  - **votes** (integer) - Actual vote count. A value of 0 indicates the number should be removed from the client's local blocklist.
  - **lastActivity** (integer) - Timestamp (milliseconds since epoch) of the last activity for this number.
- **version** (integer) - Current version of the blocklist for incremental synchronization.

#### Response Example
```json
{
  "numbers": [
    {
      "phone": "+49123456789",
      "rating": "G_FRAUD",
      "votes": 4
    },
    {
      "phone": "+390456789123",
      "rating": "F_GAMBLE",
      "votes": 10
    }
  ],
  "version": 42
}
```
```

--------------------------------

### Test Connection

Source: https://phoneblock.net/phoneblock/api

Checks connection and authentication. Can be used to verify user credentials when setting up a PhoneBlock connection.

```APIDOC
## GET /test

### Description
Checks connection and authentication. Call to this API can be used when setting up a PhoneBlock connection in a third-party app to verify the user has provided valid credentials.

### Method
GET

### Endpoint
/test
```

--------------------------------

### Verify Registration

Source: https://phoneblock.net/phoneblock/api

Verifies a user registration.

```APIDOC
## POST /verify

### Description
Verifies a user registration.

### Method
POST

### Endpoint
/verify
```

--------------------------------

### Remove BRLTTY Service on Linux

Source: https://phoneblock.net/phoneblock/dongle

On Ubuntu, uninstall the BRLTTY service if it interferes with CH340 device detection. Ensure your user is in the 'dialout' group.

```bash
sudo apt remove --purge brltty
```

```bash
sudo usermod -aG dialout $USER
```

--------------------------------

### Remove BRLTTY Service on Ubuntu Linux

Source: https://phoneblock.net/phoneblock/dongle?lang=en-US

If the CH340 device is not visible on Ubuntu, the BRLTTY service might be interfering. Uninstalling BRLTTY can resolve this.

```bash
sudo apt remove --purge brltty
```

--------------------------------

### Add User to Dialout Group on Linux

Source: https://phoneblock.net/phoneblock/dongle?lang=en-US

Ensure your user is part of the 'dialout' group to access serial devices like the CH340 dongle on Linux. This is a common requirement for serial communication.

```bash
sudo usermod -aG dialout $USER
```

--------------------------------

### Check Prefix

Source: https://phoneblock.net/phoneblock/api

Performs a privacy-preserving k-anonymity lookup against the SPAM database using a prefix.

```APIDOC
## GET /check-prefix

### Description
Privacy-preserving k-anonymity lookup against the SPAM database.

### Method
GET

### Endpoint
/check-prefix
```

--------------------------------

### CardDAV Server Configuration for iPhone

Source: https://phoneblock.net/phoneblock/setup-iphone?lang=en-US

Use this server address when setting up the CardDAV account in your iPhone's settings to synchronize PhoneBlock contacts.

```text
https://phoneblock.net/phoneblock/contacts/
```