--- title: Subaccounts | Sendblue Docs description: Create and manage child accounts for agency partners --- 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 to enable agency access. --- ## Create Child Account Create a new child account with automatic phone line assignment. ``` POST /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 | | `desired_area_code` | string | No | Preferred 3-digit area code for the assigned phone line | | `user` | string | No | User name or identifier | | `email` | string | No | Additional email | ### Example Request Terminal window ``` curl -X POST "https://api.sendblue.com/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": "client@example.com", "desired_area_code": "415", "user": "Jane Smith", "email": "jane@example.com" }' ``` ``` const axios = require("axios"); const response = await axios.post( "https://api.sendblue.com/request-child-account", { company_name: "my-client", primary_email: "client@example.com", desired_area_code: "415", user: "Jane Smith", email: "jane@example.com", }, { 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.com/request-child-account", json={ "company_name": "my-client", "primary_email": "client@example.com", "desired_area_code": "415", "user": "Jane Smith", "email": "jane@example.com" }, 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": "you@agency.com-my-client", "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": "you@agency.com-my-client", "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": "you@agency.com-my-client", "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." } } ``` ### 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 | Assigned phone number in E.164 format | | `line_request_ticket_id` | number | Ticket ID if area code request is pending (use [Check Request Status](/api-v2/line-provisioning#check-request-status/index.md) to track) | | `line_request_status` | string | `OPEN` if a line request ticket was created | | `message` | string | Additional context when area code is unavailable or line assignment fails | | `line_assignment_failed` | boolean | `true` if line assignment failed (partial success) | ### Error Responses | HTTP Status | Description | | ----------- | --------------------------------------------------- | | 400 | Missing required fields 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 /available-area-codes ``` ### Example Request Terminal window ``` curl -X GET "https://api.sendblue.com/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.com/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.com/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 to request access. - **Naming convention:** Child account names are automatically prefixed with your account email (e.g., `you@agency.com-my-client`). - **Area code availability:** Use the [List Available Area Codes](#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, you can track its status using the [Check Request Status](/api-v2/line-provisioning#check-request-status/index.md) endpoint.