Disconnect or delete a number

curl --request DELETE \
  --url https://api.bulkneo.com/v1/instances/{id} \
  --header 'apikey: <api-key>'

const options = {method: 'DELETE', headers: {apikey: '<api-key>'}};

fetch('https://api.bulkneo.com/v1/instances/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "data": {
    "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
    "deleted": true
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Field \"text\" is required and must be a non-empty string."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "trial_quota_exceeded",
    "message": "Trial message quota reached (500 messages). Upgrade to a paid plan to keep sending.",
    "details": {
      "trial_message_limit": 500
    }
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "instance_not_found",
    "message": "Instance not found. Check the instance_id and that it belongs to your account."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded, retry in 12s.",
    "details": {
      "retry_after_seconds": 12,
      "limit_per_minute": 20,
      "scope": "messages"
    }
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "upstream_unavailable",
    "message": "The messaging service is temporarily unavailable. Please retry shortly."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

DELETE

instances

{id}

Disconnect or delete a number

curl --request DELETE \
  --url https://api.bulkneo.com/v1/instances/{id} \
  --header 'apikey: <api-key>'

const options = {method: 'DELETE', headers: {apikey: '<api-key>'}};

fetch('https://api.bulkneo.com/v1/instances/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "data": {
    "instance_id": "3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34",
    "deleted": true
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Field \"text\" is required and must be a non-empty string."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "trial_quota_exceeded",
    "message": "Trial message quota reached (500 messages). Upgrade to a paid plan to keep sending.",
    "details": {
      "trial_message_limit": 500
    }
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "instance_not_found",
    "message": "Instance not found. Check the instance_id and that it belongs to your account."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded, retry in 12s.",
    "details": {
      "retry_after_seconds": 12,
      "limit_per_minute": 20,
      "scope": "messages"
    }
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

{
  "success": false,
  "error": {
    "code": "upstream_unavailable",
    "message": "The messaging service is temporarily unavailable. Please retry shortly."
  },
  "request_id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}

One endpoint, two very different outcomes. The logout_only query parameter decides which.

Read this before you call it. Deleting is permanent: the instance_id stops working forever, and anything in your code holding it will start returning 404 instance_not_found.

The two modes

Disconnect — logout_only=true

Signs WhatsApp out but keeps the instance.

instance_id stays valid
Reconnect by scanning again
Nothing to change in your code

Returns { "status": "close", "disconnected": true }.

Delete — no parameter

Removes the instance permanently.

instance_id stops working
You would have to create a new one and redeploy
Frees the slot on your account

Returns { "deleted": true }.

Exactly what each value does

The flag is never guessed at. A value we cannot read is refused, and nothing on your account changes.

You send	What happens
`logout_only=true`, `=1`, `=yes`, `=on` (any capitalisation)	Disconnect. The instance and its `instance_id` survive.
`logout_only=false`, `=0`, `=no`, `=off`	Delete permanently — you asked explicitly.
No `logout_only` parameter at all	Delete permanently — the long-standing default for a bare `DELETE`.
Any other value — `=2`, `=y`, `=maybe`, the literal `undefined`	`400 invalid_request`. Nothing is deleted, nothing is disconnected.
A bare `?logout_only` with no value	`400 invalid_request`. Nothing changes.
The parameter sent twice (`?logout_only=true&logout_only=false`)	`400 invalid_request`. Nothing changes.
A misspelled name — `?logoutOnly=true`, `?logout-only=true`, `?logout=true`	`400 invalid_request` telling you the correct name. Nothing changes.

If you are building the query string from a variable, this is the case that matters: ?logout_only=${flag} with an undefined flag sends the literal text undefined, and that now returns a 400 instead of destroying the instance.

Which one do you want?

Situation	Use
The number keeps dropping and you want a clean re-pair	`logout_only=true`, then re-scan
You are handing the phone to someone else temporarily	`logout_only=true`
You are done with this number for good	Delete
You need the slot for a different number	Delete

If a number has simply gone offline, you usually need neither. Just re-scan the QR on the existing instance — see If your number disconnects.

Examples

Disconnect, keep the instance

curl -X DELETE "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID?logout_only=true" \
  -H "apikey: YOUR_API_KEY"

Delete permanently

curl -X DELETE "https://api.bulkneo.com/v1/instances/YOUR_INSTANCE_ID" \
  -H "apikey: YOUR_API_KEY"

Node.js — never let a falsy variable decide

// Send the parameter only when you actually mean "disconnect". Do not
// interpolate a variable into the query string and hope it renders as "true".
const url = new URL(`https://api.bulkneo.com/v1/instances/${instanceId}`);
if (disconnectOnly) url.searchParams.set("logout_only", "true");

const res = await fetch(url, {
  method: "DELETE",
  headers: { apikey: process.env.BULKNEO_API_KEY },
});

Deleting or disconnecting a number does not credit anything back for the day it was already active. Reconnecting the same number later the same day costs nothing extra.

Authorizations

apikey

string

header

required

Your API key, sent in an apikey request header. Never in the URL, never as a Bearer token.

Path Parameters

string<uuid>

required

The instance_id of one of your numbers.

Query Parameters

logout_only

enum<string>

true, 1, yes or on (any capitalisation) disconnect WhatsApp and KEEP the instance. false, 0, no or off delete it, as does omitting the parameter entirely. Any other value — including an empty one, and the parameter sent twice — returns 400 invalid_request and changes nothing.

Available options:

true,

1,

yes,

on,

false,

0,

no,

off

Response

Disconnected or deleted.

success

boolean

data

object

Show child attributes

request_id

string<uuid>

⌘I

Overview

Messages

Numbers

Instances

Service

Disconnect or delete a number

The two modes

Disconnect — logout_only=true

Delete — no parameter

Exactly what each value does

Which one do you want?

Examples

Authorizations

Path Parameters

Query Parameters

Response

​The two modes

Disconnect — logout_only=true

Delete — no parameter

​Exactly what each value does

​Which one do you want?

​Examples

Authorizations

Path Parameters

Query Parameters

Response

The two modes

Exactly what each value does

Which one do you want?

Examples