Subaccounts

Create and manage child accounts under your agency account. Subaccounts receive their own API credentials and phone line for independent messaging.

Agency accounts only. These endpoints are restricted to accounts with agency permissions. Contact [email protected] to enable agency access.

---

Create Child Account

Create a new child account with automatic phone line assignment.

POST /accounts/lines/request-child-account

Request Body

Parameter	Type	Required	Description
company_name	string	Yes	Name for the child account
primary_email	string	Yes	Primary email for the child account
provision_line	boolean	Yes	Whether to provision a phone line. Pass false to create the account without assigning a line
desired_area_code	string	No	Preferred 3-digit area code for the assigned phone line (only used when provision_line: true)
user	string	No	User name or identifier
email	string	No	Additional email

Example Request

curl -X POST "https://api.sendblue.co/accounts/lines/request-child-account" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "my-client",
    "primary_email": "[email protected]",
    "provision_line": true,
    "desired_area_code": "415",
    "user": "Jane Smith",
    "email": "[email protected]"
  }'

const axios = require("axios");

const response = await axios.post(
  "https://api.sendblue.co/accounts/lines/request-child-account",
  {
    company_name: "my-client",
    primary_email: "[email protected]",
    provision_line: true,
    desired_area_code: "415",
    user: "Jane Smith",
    email: "[email protected]",
  },
  {
    headers: {
      "sb-api-key-id": "YOUR_API_KEY",
      "sb-api-secret-key": "YOUR_API_SECRET",
      "Content-Type": "application/json",
    },
  }
);

import requests

response = requests.post(
    "https://api.sendblue.co/accounts/lines/request-child-account",
    json={
        "company_name": "my-client",
        "primary_email": "[email protected]",
        "provision_line": True,
        "desired_area_code": "415",
        "user": "Jane Smith",
        "email": "[email protected]"
    },
    headers={
        "sb-api-key-id": "YOUR_API_KEY",
        "sb-api-secret-key": "YOUR_API_SECRET",
        "Content-Type": "application/json"
    }
)

Success Response (200)

{
  "status": "OK",
  "data": {
    "company_name": "[email protected]",
    "api_key": "child_api_key_here",
    "api_secret": "child_api_secret_here",
    "assigned_number": "+14155551234"
  }
}

If the requested area code is unavailable, a temporary line is assigned while your request is processed:

{
  "status": "OK",
  "data": {
    "company_name": "[email protected]",
    "api_key": "child_api_key_here",
    "api_secret": "child_api_secret_here",
    "assigned_number": "+12025551234",
    "line_request_ticket_id": 67890,
    "line_request_status": "OPEN",
    "message": "Requested area code 415 is not currently available. A temporary line has been assigned while we fulfill your request."
  }
}

Partial Success Response (200)

If the account is created but line assignment fails:

{
  "status": "PARTIAL",
  "data": {
    "company_name": "[email protected]",
    "api_key": "child_api_key_here",
    "api_secret": "child_api_secret_here",
    "line_assignment_failed": true,
    "message": "Account created but line assignment failed. Please contact support."
  }
}

No-line Example (provision_line: false)

To create an account without provisioning a phone line:

curl -X POST "https://api.sendblue.co/accounts/lines/request-child-account" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "my-client",
    "primary_email": "[email protected]",
    "provision_line": false
  }'

Response:

{
  "status": "OK",
  "data": {
    "company_name": "[email protected]",
    "api_key": "child_api_key_here",
    "api_secret": "child_api_secret_here",
    "assigned_number": null
  }
}

Response Schema

Field	Type	Description
company_name	string	Full child account name ({parent_email}-{company_name})
api_key	string	API key for the child account
api_secret	string	API secret for the child account
assigned_number	string | null	Assigned phone number in E.164 format, or null when provision_line is false
line_request_ticket_id	number	Legacy ticket ID if an area code request is pending
line_request_status	string	OPEN if a line request ticket was created
message	string	Additional context when area code is unavailable, line assignment fails, or account already exists
line_assignment_failed	boolean	true if line assignment failed (partial success)

Error Responses

HTTP Status	Description
400	Missing required fields, provision_line not provided or not a boolean, or invalid area code format
401	Invalid API credentials
403	Account does not have agency permissions
409	A child account with this name already exists
500	Server error during account or line creation

{
  "status": "ERROR",
  "message": "company_name and primary_email are required"
}

---

List Available Area Codes

Get the list of area codes currently available for phone line assignment.

GET /accounts/lines/available-area-codes

Example Request

curl -X GET "https://api.sendblue.co/accounts/lines/available-area-codes" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET"

const axios = require("axios");

const response = await axios.get(
  "https://api.sendblue.co/accounts/lines/available-area-codes",
  {
    headers: {
      "sb-api-key-id": "YOUR_API_KEY",
      "sb-api-secret-key": "YOUR_API_SECRET",
    },
  }
);

import requests

response = requests.get(
    "https://api.sendblue.co/accounts/lines/available-area-codes",
    headers={
        "sb-api-key-id": "YOUR_API_KEY",
        "sb-api-secret-key": "YOUR_API_SECRET"
    }
)

Success Response (200)

{
  "status": "OK",
  "data": {
    "area_codes": ["212", "310", "415", "512", "617", "720", "818"]
  }
}

Error Responses

HTTP Status	Description
401	Invalid API credentials
500	Failed to retrieve area codes

---

Notes

• Agency access required: Only accounts with agency permissions can create child accounts. Contact [email protected] to request access.
• Naming convention: Child account names are automatically prefixed with your account email (e.g., [email protected]).
• Area code availability: Use the List Available Area Codes endpoint to check availability before creating an account. If your preferred area code is unavailable, a temporary line will be assigned while your request is processed.
• Credentials: Store the returned api_key and api_secret securely — they are only returned once at creation time.
• Line request tracking: If a line_request_ticket_id is returned, the area-code request is pending review by the Sendblue team.