Create a Subaccount

POST Method

Kaleyra.io offers an API that enables you to create sub-account. You can configure the entities of the sub-account while creating them. Also, you have the option to change later the entities of the sub-account based on your business requirements.

Base URL

https://<api_domain>/v1/<SID>

API Domain and Value

api_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.na.kaleyra.ai

API request to create sub-account

To create a sub-account, use the /subaccounts endpoint with the following request method:

Request Format

curl --location --request POST 'https://<api_domain>/api/v1/<sid>/subaccounts' \
--header 'api-key: <api-key>' \
--header 'Content-Type: <content-type>' \
--data-raw '{
    "account_name" : "<account-name>",
    "email" : "<email-address>",
    "is_invited" : <is-invited>,
    "country_iso_code": "<country-iso-code>",
    "channels" :["<channels>"],
    "subaccount_credit_type" : "<subaccount-credit-type>"
}'

The following table describes the parameter used for creating sub-account:

Parameter

Data Type

Description

Applicable

Mandatory

Example

sid

String

Parent account SID (Security Identifier).

Always applicable.

Yes

HXXXXXXX071IN

content-type

String

The format in which the data is sent.

Always applicable.

Yes

application/json

api-key

String

Parent account API key.

Always applicable.

Yes

Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3

account_name

String - only alphanumeric, no special characters

Sub-account name.

Always applicable.

Yes

John Doe

email_address

String - with valid email

Sub-account user email address.

Always applicable.

Yes

[[email protected]]

is_invited

Boolean

Identifier to send an invitation email to a sub-account user.

  • *True** - Invitation email will be sent to a sub-account user.
  • *False** - Invitation email will not be sent to a sub-account user.

Always applicable.

Yes

True/False

country_iso_code

String - two-letter country ISO code.

Country code for which you want to create Sub-account.

Always applicable.

Yes

IN

channels

String

Channels for which you want to give access to sub-account users. The supported channel is SMS.

Always applicable.

Yes

sms

subaccount_credit_type

String

Any one of the following Credit Types can be assigned to Subaccount:

  • *Assigned** - If you want to assign a specific credit amount to a sub-account.
  • *Shared** - If you want to share the usage with a sub-account.

Always applicable.

Yes

assigned

low_balance_alert

Boolean

Identifier to send low balance alerts to specified email addresses.

Applicable only when subaccount_credit_type = assigned.

No

True/False

low_balance_limit

Number

The threshold amount to send alert email if sub-account’s balance goes below it.

Applicable only when subaccount_credit_type = assigned and low_balance_alert is true.

No

500

low_balance_emails

Array of strings

The email addresses to which low balance alert is sent. You can add more than one email address separated by a comma (,).

Applicable only when subaccount_credit_type = assigned and low_balance_alert is true.

No

[[email protected]]

initial_credit_amount

Number

Initial credit amount you want to assign to the sub-account user.

Applicable only when subaccount_credit_type = assigned.

No

1000

monthly_limit

Number

The monthly limit you want to set for a sub-account user.

Applicable only when a Monthly_limit is enabled for Parent account and when subaccount_credit_type = shared.

No

3000

ip_config_name

String

The IP configuration created by Parent account. If passed in the request, by default it will be shared with sub-account and will be applied to the sub-account api_key as a whitelisted IP addresses/ranges.

Applicable only if a parent is allowed to share ip_config.

No

test1

Sample Request

The following is the sample request:

curl --location --request POST 'https://api.in.kaleyra.io/api/v1/HXXXXXXX071IN/subaccounts' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account_name" : "John Doe",
    "email" : "[email protected]",
    "is_invited" : True,
    "country_iso_code": "IN",
    "channels" :["sms"],
    "subaccount_credit_type" : "Assigned"
}'

Sample Success Response

The following are the sample success response for different cases:

Case 1.: When subaccount_credit_type = assigned and low_balance_alert = false
{
    "code": "RBC103",
    "message": "Request executed successfully",
    "data": {
        "account_name": "John Doe",
        "email": "[email protected]",
        "status": "active",
        "sid": "HXXXXXXX071IN_1234",
        "api_key": "Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3",
        "channels": [
            "sms"
        ],
        "low_balance_alert": false,
        "subaccount_credit_type": "assigned",
        "balance": 1
    },
    "error": {},
    "status": 201
}
Case 2.: When subaccount__credit_type = assigned and low_balance_alert = true
{
    "code": "RBC103",
    "message": "Request executed successfully",
    "data": {
        "account_name": "John Doe",
        "email": "[email protected]",
        "status": "active",
        "sid": "HXXXXXXX071IN_1234",
        "api_key": "Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3",
        "channels": [
            "sms"
        ],
      	"low_balance_alert": "true",  
      	"low_balance_limit": "1",
        "low_balance_emails": "[email protected]",        
        "subaccount_credit_type": "assigned",
        "balance": 1
    },
    "error": {},
    "status": 201
}
Case 3.: When subaccount__credit_type = shared without monthly_limit
{
    "code": "RBC103",
    "message": "Request executed successfully",
    "data": {
        "account_name": "John Doe",
        "email": "[email protected]",
        "status": "active",
        "sid": "HXXXXXXX071IN_1234",
        "api_key": "Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3",
        "channels": [
            "sms"
        ],
        "subaccount_credit_type": "shared"       
    },
    "error": {},
    "status": 201
}
Case 4.: When subaccount__credit_type = shared with monthly_limit
{
    "code": "RBC103",
    "message": "Request executed successfully",
    "data": {        
        "account_name": "John Doe",
        "email": "[email protected]",
        "status": "active",
        "sid": "HXXXXXXX071IN_1234",
        "api_key": "Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3"
        "channels": [
            "sms"
        ],
        "subaccount_credit_type": "shared"
        "monthly_limit": 5
    },
    "error": {},
    "status": 201
}

Sample Failure Response

The following is a sample failure response:

{
    "code": "RBC2320",
    "message": "Error Occured in Rbac Register Wrapper API",
    "data": {},
    "error": {
        "Subaccount": "Subaccount with the same name already exists"
    },
    "status": 400
}

For more information about response codes and statuses for creating sub-account, see Response Codes and Statuses for Creating Subaccounts.





© 2025 Kaleyra Inc. All rights reserved.
Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.