> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.bulkneo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a number slot
> POST /v1/instances — create an instance to connect a new WhatsApp number to.
Creates an empty slot for a WhatsApp number and returns its `instance_id`. Nothing is connected yet — someone still has to scan a QR with the phone.
Most people never call this. Adding a number in the portal is easier, and it shows the QR for you. This endpoint exists for software that provisions numbers on its own.
## Notes
* `label` is optional, up to **60 characters**. It is for your own reference only; nothing about sending depends on it.
* The response may include a `qrcode` straight away. If `qrcode` is `null`, fetch one from [`GET /v1/instances/{id}/qr`](/api-reference/instances/qr).
* Creating an instance counts against your account's number allowance. Over it, you get `403 instance_limit_reached` with `details.instance_limit`.
* This is the only instance endpoint that requires an active plan.
## Connecting the number afterwards
Use the `qrcode` from this response, or call [`GET /v1/instances/{id}/qr`](/api-reference/instances/qr).
`qrcode.base64` is a `data:image/png;base64,...` string you can put straight into an `
`.
**WhatsApp → Settings → Linked devices → Link a device.**
Call [`GET /v1/instances/{id}/qr-status`](/api-reference/instances/qr-status) about every 2.5 seconds until `connected` is `true`.
## Example
```bash cURL theme={null}
curl -X POST https://api.bulkneo.com/v1/instances \
-H "apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "label": "Sales" }'
```
Save the `instance_id` somewhere durable. It is how you name this number in every send from now on, and it never changes for the life of the instance.
## OpenAPI
````yaml api-reference/openapi.json POST /v1/instances
openapi: 3.1.0
info:
title: BulkNeo WhatsApp API
version: 1.0.0
description: >-
Send WhatsApp messages from your own connected numbers. Every request is
authenticated with an `apikey` header and names the `instance_id` of the
number it should be sent from.
servers:
- url: https://api.bulkneo.com
description: BulkNeo API
security:
- apikey: []
tags:
- name: Messages
description: Send a message from one of your connected numbers.
- name: Numbers
description: Check which numbers are reachable on WhatsApp.
- name: Instances
description: Create, connect, inspect and remove your WhatsApp numbers.
- name: Service
description: Unauthenticated service health checks.
paths:
/v1/instances:
post:
tags:
- Instances
summary: Create a number slot
description: >-
Creates a new instance — an empty slot for a WhatsApp number — and
returns its `instance_id`. The number is not connected until someone
scans the QR with WhatsApp on their phone. A QR may be returned
immediately; if `qrcode` is `null`, fetch one from `GET
/v1/instances/{id}/qr`.
operationId: createInstance
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
label:
type: string
maxLength: 60
description: >-
Your own name for this number, for example "Sales". Up to 60
characters.
example: Sales
example:
label: Sales
responses:
'201':
description: Instance created.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
const: true
data:
type: object
properties:
instance_id:
type: string
format: uuid
label:
type:
- string
- 'null'
status:
$ref: '#/components/schemas/ConnectionStatus'
connected:
type: boolean
qrcode:
$ref: '#/components/schemas/QrCode'
request_id:
type: string
format: uuid
example:
success: true
data:
instance_id: 3f9c1a2b-7d4e-4c81-9f0a-2b6d5e8c1a34
label: Sales
status: connecting
connected: false
qrcode:
base64: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...
code: 2@Xj4kR...
pairingCode: null
request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
'502':
$ref: '#/components/responses/ProvisioningFailed'
components:
schemas:
ConnectionStatus:
type: string
description: >-
`open` connected and able to send, `connecting` pairing in progress,
`close` not connected.
example: open
QrCode:
type:
- object
- 'null'
description: The pairing QR, or `null` when there is nothing to scan.
properties:
base64:
type:
- string
- 'null'
description: >-
A `data:image/png;base64,...` image you can render directly in an
`![]()
` tag.
code:
type:
- string
- 'null'
description: The raw QR payload, if you would rather render the code yourself.
pairingCode:
type:
- string
- 'null'
description: A short pairing code, when one is available.
Error:
type: object
properties:
success:
type: boolean
const: false
error:
type: object
properties:
code:
type: string
description: >-
Stable machine-readable code. Branch on this, not on the
message.
message:
type: string
description: Human-readable explanation. The wording may change.
details:
type: object
description: Extra safe context, present on some errors.
request_id:
type: string
format: uuid
description: Quote this when asking support about a request.
responses:
BadRequest:
description: >-
`invalid_request` a field is missing or malformed (the message names it,
including its position in a list) · `invalid_media_url` the `url` is not
a public http(s) link to a file.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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
Unauthorized:
description: >-
`missing_api_key` no `apikey` header was sent · `invalid_api_key` the
key is unknown or revoked.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
error:
code: invalid_api_key
message: Invalid or revoked API key.
request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
PaymentRequired:
description: >-
`no_active_subscription` no usable plan on this account ·
`subscription_expired` the plan has run out.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
error:
code: subscription_expired
message: >-
Your subscription has expired. Renew it to continue sending
messages.
request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
Forbidden:
description: >-
`account_suspended` · `access_expired` · `trial_quota_exceeded` ·
`instance_limit_reached` · `activation_unavailable`.
On `instance_limit_reached`, `details.limit_source` tells you which cap
you hit: `plan` (the plan you are on — upgrade it) or `account` (a cap
set on your account — ask your provider to raise it). Branch on that,
never on the wording of the message.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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
RateLimited:
description: >-
`rate_limit_exceeded` — too many requests this minute. Wait for the
number of seconds in the `Retry-After` header. `details.scope` and the
`X-RateLimit-Scope` header say WHICH allowance you exceeded.
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
X-RateLimit-Scope:
$ref: '#/components/headers/RateLimitScope'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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
InternalError:
description: >-
`internal_error` — something went wrong on our side. Quote the
`request_id` to support.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
error:
code: internal_error
message: An unexpected error occurred.
request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
ProvisioningFailed:
description: >-
`provisioning_failed` — the instance could not be created right now.
Retry shortly.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
error:
code: provisioning_failed
message: Could not create the instance right now. Please retry shortly.
request_id: b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
headers:
RateLimitScope:
description: >-
WHICH allowance the other X-RateLimit-* headers describe. `messages`
covers every /v1/messages/* endpoint and /v1/numbers/check together;
`instances` is the separate, much larger budget for /v1/instances/*. If
you cache a limit, cache it against its scope.
schema:
type: string
enum:
- messages
- instances
example: messages
RateLimitLimit:
description: Requests allowed per minute on this scope.
schema:
type: integer
example: 20
RateLimitRemaining:
description: Requests left in the current minute on this scope.
schema:
type: integer
example: 17
RateLimitReset:
description: >-
Seconds until the allowance next goes up by one. Present on successful
responses too, so you can pace yourself without first earning a 429. The
window is a rolling minute, so this is when the oldest request ages out
— not a fixed reset instant. If `X-RateLimit-Remaining` is above 0 you
can send now.
schema:
type: integer
example: 43
securitySchemes:
apikey:
type: apiKey
in: header
name: apikey
description: >-
Your API key, sent in an `apikey` request header. Never in the URL,
never as a Bearer token.
````