Scope Wiser API: Overview and Authentication

The base URL, where to get your API key, how every request is authenticated, and the response shape every endpoint returns. Start here before using any other API guide.

Last updated Sep 5, 2026

This guide is for developers. If you want Scope Wiser to call your system, that is the other direction and it is covered in HTTP API: The Complete Developer Guide. This article is about calling Scope Wiser from your own website, app or backend.

Where to find your API key

Click your avatar at the top right.
Choose API Developer.

The page is headed Scope Wiser - Developer — "Get Your API key and become a Scope Wiser developer" — and shows Your API key with a Copy button and a Generate API key button.

The whole reference lives on that page too, grouped as User API, WhatsApp API, Subscriber API, Label API and Catalog API, with a live example for each endpoint.

Treat the key as a password. It grants everything your account can do — reading conversations, messaging customers, deleting subscribers. Keep it in an environment variable on your server, never in front-end JavaScript, a mobile app, or a public repository. Generate API key issues a new one and invalidates the old, so rotate it if it is ever exposed.

The base URL

Every endpoint sits under:

https://connect.scopewiser.com/api/v1/

Authentication

There is no OAuth flow and no separate login call. Every request carries your key as a parameter called apiToken.

Most endpoints accept both GET and POST. Use POST from a server — a key in a query string ends up in browser history, proxy logs and server access logs.

GET

https://connect.scopewiser.com/api/v1/label/list?apiToken=API-KEY

POST

curl -X POST \
  'https://connect.scopewiser.com/api/v1/label/list' \
  -d 'apiToken=API-KEY'

The media upload endpoint also accepts the key as a bearer header, which is the tidier form where your HTTP client supports it:

-H "Authorization: Bearer API-KEY"

The response shape

Every endpoint returns JSON with a status field. It is a string, not a boolean or a number — check for "1", not 1 or true.

`status`	Meaning
`"1"`	The call succeeded. `message` holds the result — a string for actions, an array or object for reads.
`"0"`	The call failed. `message` holds the reason, in plain English.

A successful action:

{"status":"1","message":"Labels have been assigned successfully."}

A successful read:

{"status":"1","message":[{"id":1,"label_name":"Your label name","status":"1"}]}

A failure:

{"status":"0","message":"Subscriber limit has been exceeded. You cannot have more subscribers."}

A few endpoints return true instead of "1", and one sample response spells the key mesasge. Write your client so an unexpected shape is logged rather than treated as success.

The identifiers you will need

Almost every WhatsApp endpoint wants a phone_number_id — the ID of the WhatsApp number the call acts on, not the number itself. Note the two spellings: most endpoints use phone_number_id, but Subscriber Create uses phoneNumberID and phoneNumber. Copy the parameter names from each endpoint rather than assuming.

Identifier	What it is
`phone_number_id`	Your WhatsApp account's phone number ID
`phone_number`	The customer's number, country code first, digits only, no `+`
`label_ids` / `sequence_ids`	Comma-separated lists, for example `1,4,5`
`bot_flow_unique_id`	From Bot Flow List
`wa_message_id`	Returned when you send; used to check delivery

Paging

List endpoints take limit and offset, where offset is a page number starting at 1. Conversations cap at 50 per call, subscribers at 100. Responses that have more include nextOffset — keep calling until it stops coming back.

Rate limits and quotas

Your account's plan limits apply to the API exactly as they do in the interface. Sending is governed by the same WhatsApp rules as anywhere else: outside a 24-hour window since the customer last messaged you, only an approved template is delivered. If you exceed a plan limit the call returns status: "0" with a message saying which limit was hit — for example the subscriber cap.