API reference

WhatsApp connections

Register a client business (the future owner of a WhatsApp Business account)#

POST/connected-businesses

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: connections:manage

Request body (JSON)

Field	Type		Description
`name`	string	required	Name of your customer's business (2 to 120 characters).
`externalRef`	string	optional	Your own identifier for this customer

Example

bash

curl -X POST "$INBOX_API/connected-businesses" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cabinet Dentaire Zokem",
    "externalRef": "client-42"
  }'

javascript

const res = await fetch(`${process.env.INBOX_API}/connected-businesses`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Cabinet Dentaire Zokem",
    "externalRef": "client-42"
  }),
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/connected-businesses",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
    json={
        "name": "Cabinet Dentaire Zokem",
        "externalRef": "client-42",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/connected-businesses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'Cabinet Dentaire Zokem',
        'externalRef' => 'client-42',
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 201 Created

{
  "id": "39e2803f-79e7-4e99-8da0-1c15991f5985",
  "name": "Cabinet Dentaire Zokem",
  "externalRef": "client-42",
  "createdAt": "2026-11-12T08:33:45.469Z"
}

List the businesses in the key's environment#

GET/connected-businesses

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: connections:read

Example

bash

curl "$INBOX_API/connected-businesses" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/connected-businesses`, {
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.get(
    f"{os.environ['INBOX_API']}/connected-businesses",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/connected-businesses');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

[
  {
    "id": "39e2803f-79e7-4e99-8da0-1c15991f5985",
    "name": "Cabinet Dentaire Zokem",
    "externalRef": "client-42",
    "createdAt": "2026-11-12T08:33:45.469Z"
  }
]

Complete Embedded Signup: connect the WhatsApp Business account and number#

POST/connected-businesses/{businessId}/waba-connections

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: connections:manage

Parameters

Name	Location	Type	Description
`businessId`required	path	string	Connected business ID.

Request body (JSON)

Field	Type		Description
`code`	string	required	Code returned by Embedded Signup (single-use, short-lived)
`wabaId`	string	required	ID of the WhatsApp Business account (WABA) returned by Embedded Signup. Digits only.
`phoneNumberId`	string	required	ID of the WhatsApp number returned by Embedded Signup. Digits only.
`mode`	string	optional	`cloud_api` (default), or `coexistence` if the customer keeps the WhatsApp Business app on their phone.Values: cloud_api, coexistence

Example

bash

curl -X POST "$INBOX_API/connected-businesses/BUSINESS_ID/waba-connections" \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AQBx7…",
    "wabaId": "102290129340398",
    "phoneNumberId": "106540352242922",
    "mode": "cloud_api"
  }'

javascript

const res = await fetch(`${process.env.INBOX_API}/connected-businesses/BUSINESS_ID/waba-connections`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "code": "AQBx7…",
    "wabaId": "102290129340398",
    "phoneNumberId": "106540352242922",
    "mode": "cloud_api"
  }),
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/connected-businesses/BUSINESS_ID/waba-connections",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
    json={
        "code": "AQBx7…",
        "wabaId": "102290129340398",
        "phoneNumberId": "106540352242922",
        "mode": "cloud_api",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/connected-businesses/BUSINESS_ID/waba-connections');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'code' => 'AQBx7…',
        'wabaId' => '102290129340398',
        'phoneNumberId' => '106540352242922',
        'mode' => 'cloud_api',
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 201 Created

{
  "id": "b76a1f98-53d6-4078-8d28-6406482daabb",
  "wabaId": "102290129340398",
  "status": "active",
  "mode": "cloud_api",
  "phoneNumber": {
    "id": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
    "phoneNumberId": "106540352242922",
    "displayNumber": "+237 6 52242922",
    "verifiedName": "Cabinet Test",
    "qualityRating": "GREEN"
  }
}

A business's connected accounts and numbers#

GET/connected-businesses/{businessId}/phone-numbers

Authentication: API key (Bearer pk_…), or console session (Bearer ses_… with the X-Environment-Id header)
Required scope: connections:read

Parameters

Name	Location	Type	Description
`businessId`required	path	string	Connected business ID.

Example

bash

curl "$INBOX_API/connected-businesses/BUSINESS_ID/phone-numbers" \
  -H "Authorization: Bearer $INBOX_KEY"

javascript

const res = await fetch(`${process.env.INBOX_API}/connected-businesses/BUSINESS_ID/phone-numbers`, {
  headers: {
    Authorization: `Bearer ${process.env.INBOX_KEY}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.get(
    f"{os.environ['INBOX_API']}/connected-businesses/BUSINESS_ID/phone-numbers",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_KEY']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/connected-businesses/BUSINESS_ID/phone-numbers');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

[
  {
    "id": "b76a1f98-53d6-4078-8d28-6406482daabb",
    "wabaId": "102290129340398",
    "status": "active",
    "mode": "cloud_api",
    "phoneNumbers": [
      {
        "id": "4d8e654e-d744-4bf3-8211-9ceffcccfe87",
        "phoneNumberId": "106540352242922",
        "displayNumber": "+237 6 52242922",
        "verifiedName": "Cabinet Test",
        "qualityRating": "GREEN"
      }
    ]
  }
]