Create Subaccount

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.kaleyra.io>

To create a sub-account, perform the following steps:

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 '<url>/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.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.