Create a Brand

POST Method

The Create a Brand API allows you to create a new RCS brand with the provided brand details and forwards the request to the provisioning service.

Prerequisites

After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in kaleyra.io.
Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
To send any RCS messages, you must configure the RCS channel in the Kaleyra platform. To configure the RCS channel in your account, please contact your local Kaleyra representative.

Base URL

https://rcs-api.<pod>.kaleyra.io/v1/<sid>

API Domain and Value

api_domain	Value
IN pod	`https://rcs-api.in.kaleyra.io`
NA pod	`https://rcs-api.na.kaleyra.io`

API Request to Create a Brand

To create a brand, use the https://rcs-api.<pod>.kaleyra.io/v1/<sid>/rcs/brand endpoint with the following request method:

Request Format

The following is the request format to create a brand for US region.

curl --location 'https://<api_domain>/v1/<sid>/rcs/brand' \
--header 'api-key: <api-key>' \
--header 'Content-Type: <content_type>' \
--data-raw '{
  "brand_name": "<brand_name>",
  "display_name": "<display_name>",
  "brand_description": "<brand_description>",
  "partner_name": "<partner_name>",
  "partner_email": "<partner_email>",
  "contact_name": "<contact_name>",
  "contact_email": "<contact_email>",
  "website_url": "<website_url>",
  "rcs_provider_id": <rcs_provider_id>,
  "image_id": "<image_id>",
  "thumbnail_imageid": "<thumbnail_imageid>"
}'

Sample Request Format

The following is the sample request format to create a brand US:

curl --location 'https://rcs-api.na.kaleyra.io/v1/XXXXX6913850XXXXUS/rcs/brand' \
--header 'api-key: XXXXX3b8497f58a94e84b671aca43XXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
  "brand_name": "Bigbasket Grocery",
  "display_name": "Bigbasket Grocery Display Name",
  "brand_description": "Bigbasket Grocery Description",
  "partner_name": "Bigbasket Partner",
  "partner_email": "[email protected]",
  "contact_name": "John Mathew",
  "contact_email": "[email protected]",
  "website_url": "https://www.tatacommunications.com",
  "rcs_provider_id": 1,
  "image_id": "https://i.pinimg.com/736x/1a/c3/da/5720ef03c.jpg",
  "thumbnail_imageid": "https://i.pinimg.com/736x/e0/30/81/e067e8a1.jpg"
}'

Request Format

The following is the request format to create a brand for IN region.

curl --location 'https://<api_domain>/v1/<sid>/rcs/brand' \
--header 'Content-Type: <content-type>' \
--header 'api-key: <api-key>' \
--data-raw '{
  "brand_name": "<brand_name>",
  "display_name": "<display_name>",
  "brand_description": "<brand_description>",
  "partner_name": "<partner_name>",
  "partner_email": "<partner_email>",
  "contact_name": "<contact_name>",
  "contact_email": "<contact_email>",
  "website_url": "<website_url>",
  "image_id": "<image_id>",
  "thumbnail_imageid": "<thumbnail_url>",
  "status": "<status>",
  "rcs_provider_id": <provider_id>,
  "contact_designation": "<contact_destination>",
  "contact_phone": {
    "label_text": "<label_text>",
    "number": "<number>",
    "country_code": "<country_code>",
    "is_toll_free": <is_toll_free>
  },
  "industry_type": "<industry_type>"
}'

Sample Request Format

The following is the sample request format to create a brand IN region:

curl --location 'https://rcs-api.in.kaleyra.io/v1/XXXXX6913850XXXXIN/rcs/brand' \
--header 'Content-Type: application/json' \
--header 'api-key: XXXXX3b8497f58a94e84b671aca43XXXX' \
--data-raw '{
  "brand_name": "Bigbasket Grocery",
  "display_name": "Bigbasket Grocery Display Name",
  "brand_description": "Bigbasket Grocery Description",
  "partner_name": "Bigbasket Partner",
  "partner_email": "[email protected]",
  "contact_name": "John Mathew",
  "contact_email": "[email protected]",
  "website_url": "https://www.tatacommunications.com",
  "image_id": "https://i.pinimg.com/736x/1a/c3/da/5720ef03c.jpg",
  "thumbnail_imageid": "https://i.pinimg.com/736x/e0/30/81/e067e8a1.jpg",
  "status": "REGISTRATIONINPROGRESS",
  "rcs_provider_id": 2,
  "contact_designation": "SM", 
  "contact_phone": {
    "label_text": "Work",
    "number": "91XXXXXXXXXXX",
    "country_code": "+91",
    "is_toll_free": false
  },
  "industry_type": "Advertising/marketing"
}'

📘
Note:

rcs_provider_id: Use 2 for India. The default value is 1 for other regions.

contact_designation: Used for India only.

contact_phone: Used for India only.

industry_type: Used for India only.

URL Parameters and Headers

The following is the list of parameters and headers to send the outgoing message request:

Parameter/Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	XXXXX6913850XXXX	Yes
`Content-Type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/JSON	Yes
`api-key`	String	API key generated from kaleyra.io account.	XXXXX3b8497f58a94e84b671aca43XXXX	Yes

The following is the list of attributes to be used in the payload to create a brand:

Parameter	Data Type	Description	Example	Mandatory?
`band_name`	String	Official name of the brand to be updated. Note: The maximum length is up to 100 characters.	Bigbasket Grocery	Yes
`display_name`	String	Name to be displayed publicly. Note: The maximum length is up to 100 characters.	Bigbasket Grocery Display Name	Yes
`brand_description`	String	Updated description of the brand. Note: The maximum length is up to 200 characters.	Bigbasket Grocery Description	Yes
`partner_name`	String	Name of the Partner organization. Note: The maximum length is up to 200 characters.	Bigbasket Partner	Yes
`partner_email`	String	Email of the Partner. Must be a valid email format.	`[email protected]`	Yes
`contact_name`	String	Name of the contact. Note: The maximum length is up to 200 characters.	John Mathew	Yes
`contact_email`	String	Email of the contact.	`[email protected]`	Yes
`website_url`	String	Brands website URL. Must be a valid URL.	`https://www.tatacommunications.com`	Yes
`rcs_provider_id`	Integer	RCS provider identifier. Use 2 for India and 1 for other regions.	2	Yes
`image_id`	String	Public image URL. Note: You should not pass `image id` while creating a brand since it is optional.	`https://i.pinimg.com/736x/1a/c3/da/5720ef03c.jpg`	No
`thumbnail_imageid`	String	Thumbnail image URL. Note: You should not pass `thumbnail_imageid` while creating a brand since it is optional.	`https://i.pinimg.com/736x/e0/30/81/e067e8a1.jpg`	No
`Status`	String	Brand registration status. Used for India region.	REGISTRATIONINPROGRESS	No
`contact_designation`	String	Designation of the brand contact. India only.	SM	No
`contact_phone`	Object	Contact phone details. India only.	See the specific table for details	No
`industry_type`	String	Industry/category of the brand. India only.	Advertising/marketing	No

The following table describes the different attributes used for the contact_phone JSON object:

Parameter	Data Type	Description	Example	Mandatory?
`label_text`	String	Label for the contact phone number.	Work	No
`number`	String	Contact phone number.	`91XXXXXXXXXXX`	No
`country_code`	String	Country calling code.	+91	No
`is_toll_free`	Boolean	Indicates whether the phone number is toll-free.	false	No

Sample Success Response

The following is a sample success response for US region:

{
    "code": "RCS802",
    "message": "RCS Brand created successfully",
    "data": {
        "id": "e15e63ca-8ae2-4ee4-ab6c-f92bd7772384",
        "brand_id": "e15e63ca-8ae2-4ee4-ab6c-f92bd7772384",
        "brand_name": "Bigbasket Grocery",
        "brand_number": "78600",
        "display_name": "Bigbasket Grocery Display Name",
        "brand_description": "Bigbasket Grocery Description",
        "partner_name": "Bigbasket Partner",
        "partner_email": "[email protected]",
        "contact_name": "John Mathew",
        "contact_email": "[email protected]",
        "website_url": "https://www.tatacommunications.com",
        "image_id": "https://i.pinimg.com/736x/1a/c3/da/5720ef03c.jpg",
        "thumbnail_imageid": "https://i.pinimg.com/736x/e0/30/81/e067e8a1.jpg",
        "status": "REGISTRATIONINPROGRESS",
        "org_number": "9700",
        "rcs_provider_id": 1,
        "billing_package_id": 0
    },
    "error": {}
}

The following is a sample success response for IN region:

{
    "code": "RCS802",
    "message": "RCS Brand created successfully",
    "data": {
        "id": "19fd90de-1e79-4fdd-9e81-7162dbf18e36",
        "brand_id": "19fd90de-1e79-4fdd-9e81-7162dbf18e36",
        "brand_name": "Bigbasket Grocery",
        "brand_number": "28800",
        "display_name": "Bigbasket Grocery Display Name",
        "brand_description": "Bigbasket Grocery Description",
        "partner_name": "Bigbasket Partner",
        "partner_email": "[email protected]",
        "contact_name": "John Mathew",
        "contact_email": "[email protected]",
        "website_url": "https://www.tatacommunications.com",
        "image_id": "https://i.pinimg.com/736x/1a/c3/da/5720ef03c.jpg",
        "thumbnail_imageid": "https://i.pinimg.com/736x/e0/30/81/e067e8a1.jpg",
        "status": "REGISTRATIONINPROGRESS",
        "org_number": "22000",
        "rcs_provider_id": 2,
        "contact_phone": {
            "is_toll_free": false,
            "country_code": "+91",
            "number": "902X8000955",
            "label_text": "Work"
        },
        "contact_designation": "SM",
        "industry_type": "Advertising/marketing",
        "billing_package_id": 0
    },
    "error": {}
}

Sample Failure Response

The following are sample failure responses:

404 Not Found - Invalid Method

{
  "code": "RCS404",
  "message": "404 Page Not found.",
  "data": [],
  "error": {
    "error_code": "PAGE_NOT_FOUND",
    "error_message": "404 Page Not found."
  }
}

500 Internal Server Error - Org Not Found

{
  "code": "RCS510",
  "message": "Unable to fetch Org details for the user.",
  "data": [],
  "error": {
    "error_code": "ORG_NOT_FOUND",
    "error_message": "Unable to fetch Org details for the user."
  }
}

400 Bad Request - Invalid JSON:

{
  "code": "RCS701",
  "message": "Invalid Json passed. Please check",
  "data": [],
  "error": {
    "error_code": "INVALID_JSON",
    "error_message": "actual JSON decode error message"
  }
}

400 Bad Request - Missing Fields

{
    "code": "RCS804",
    "message": "Required fields are missing",
    "data": [],
    "error": {
        "error_code": "MISSING_REQUIRED_FIELDS",
        "error_message": "missing required fields: contact_name"
    }
}

400 Bad Request - Invalid Field Formats

{
    "code": "RCS804",
    "message": "Fields with invalid format are passed",
    "data": [],
    "error": {
        "error_code": "INVALID_FIELD_FORMAT",
        "error_message": "invalid image URL for field 'image_id': https://d2luXXXXX0ih7r.cloudfront.net/17XXXXX527913-TC_Small_logo_(224_x_224)_1.pn"
    }
}

500 Internal Server Error - API Call Failed

{
  "code": "RCS805",
  "message": "Failed to call Prov API",
  "data": [],
  "error": {
    "error_code": "API_CALL_ERROR",
    "error_message": "actual API error message"
  }
}

4xx Downstream Error

{
    "code": "RCS804",
    "message": "Unable to fetch RCS Brand details",
    "data": [],
    "error": {
        "error_code": "PROV_ERROR",
        "error_message": "{\"status\":\"FAILED\",\"message\":\"Brand not found\",\"messageKey\":\"message\"}"
    }
}

Updated 14 days ago

Did this page help you?