Creates or updates a ban record for the visitor and also marks the visitor metadata as blocked. `reason` is optional. If a ban already exists for the visitor, the route updates the existing record instead of creating a duplicate. Authenticate with an organization API key sent in `X-API-Key` or as a Bearer token and carrying the exact `visitors:write` scope. API-key access also requires the Automation & API module (`automation_api`). Authorized dashboard sessions remain supported where the route already permits them. The request is isolated to the authenticated organization. Resource and site/project identifiers must belong to that organization; out-of-scope identifiers are not disclosed. Banning prevents the visitor from starting or continuing normal support interactions for the authenticated organization. Repeating the same ban updates or preserves the active ban according to the documented response. Retry behavior: Repeating the same request converges on the same resource state, but a retry may return a conflict or not-found response after the first request succeeds.

POST/api/visitors/{id}/ban

Authorization

AuthorizationBearer <token>

Organization API key supplied as Authorization: Bearer convor_sk_....

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason?string

Response Body

`application/json`

Request examples

curl

curl --request POST \
  'https://api.convor.io/api/visitors/550e8400-e29b-41d4-a716-446655440000/ban' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer convor_sk_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "reason": "Repeated spam submissions"
}'

JavaScript

const response = await fetch("https://api.convor.io/api/visitors/550e8400-e29b-41d4-a716-446655440000/ban", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer convor_sk_...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "reason": "Repeated spam submissions"
  }),
});

const contentType = response.headers.get("content-type") ?? "";
const data = response.status === 204
  ? null
  : contentType.includes("json")
    ? await response.json()
    : contentType.startsWith("text/")
      ? await response.text()
      : await response.blob();

if (!response.ok) {
  const message = typeof data === "object" && data !== null
    && "error" in data && typeof data.error === "object"
    && data.error !== null && "message" in data.error
      ? String(data.error.message)
      : "Convor API request failed (" + response.status + ")";
  throw new Error(message);
}

console.log(data);

Was this page helpful?

POST/api/visitors/{id}/ban

Authorization

AuthorizationBearer <token>

Organization API key supplied as Authorization: Bearer convor_sk_....

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason?string

Response Body

`application/json`

Request examples

curl

curl --request POST \
  'https://api.convor.io/api/visitors/550e8400-e29b-41d4-a716-446655440000/ban' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer convor_sk_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "reason": "Repeated spam submissions"
}'

JavaScript

const response = await fetch("https://api.convor.io/api/visitors/550e8400-e29b-41d4-a716-446655440000/ban", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer convor_sk_...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "reason": "Repeated spam submissions"
  }),
});

const contentType = response.headers.get("content-type") ?? "";
const data = response.status === 204
  ? null
  : contentType.includes("json")
    ? await response.json()
    : contentType.startsWith("text/")
      ? await response.text()
      : await response.blob();

if (!response.ok) {
  const message = typeof data === "object" && data !== null
    && "error" in data && typeof data.error === "object"
    && data.error !== null && "message" in data.error
      ? String(data.error.message)
      : "Convor API request failed (" + response.status + ")";
  throw new Error(message);
}

console.log(data);

Was this page helpful?

Ban a visitor

Authorization

Path Parameters

Request Body

Response Body

`application/json`

Request examples

curl

JavaScript

On this page

Ban a visitor

Authorization

Path Parameters

Request Body

Response Body

`application/json`

Request examples

curl

JavaScript

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Ban a visitor

201application/json

On this page

Ban a visitor

201application/json

On this page

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`