Requests API - sample call structures
All of the examples below are written using a test company named Blanca Peak. For each example, additions are bold.
Visit our API docs under Requests for detailed libraries, custom header examples and sample code.
Custom headers for any API call
accept: application/json
content-type: application/json
x-api-key: YOUR API KEY
Simplest Auto-Trigger Request Structure
| Sample Interaction | Corresponding API Call |
Jane Customer {janecustomer@example.com} had a phone interaction with Paul Agent {paulagent@blancapeak.com} today. This interaction was attached to Case # 123456, and marked as Closed following this phone call. | { "customer": { "name": "Jane", "email": "janecustomer@example.com" }, "ext_interaction_id": "123456", "employee": { "email": "paulagent@blancapeak.com" }, "channel": "phone" } |
Agents without Email Addresses
| Sample Interaction | Corresponding API Call |
Jane Customer {janecustomer@example.com} had a phone interaction with Paul Agent Employee ID ABC789} today. This interaction was attached to Case # 123456, and marked as Closed following this phone call. | { "customer": { "name": "Jane", "email": "janecustomer@example.com" }, "ext_interaction_id": "123456", "employee": { "custom_id": "ABC789" }, "channel": "phone" } |
Transaction IDs make it easier for you to identify the interaction that triggered the feedback request in your source system. Therefore, you should pick the most granular transaction ID possible. This typically means an interaction ID or case ID, but an Order ID can also be used.
Enable Business Users to Link Back to a Corresponding Ticket number in your CRM
Often, when reading Connect feedback, business users want to know more about what happened on the interaction before coaching or praising the agent. To enable business users to link back to the original case/ticket record directly from the Connect stream, include the URL in the API call.
| Sample Interaction | Corresponding API Call |
Jane Customer {janecustomer@example.com} had a phone interaction with Paul Agent {paulagent@blancapeak.com} today. This interaction was attached to Case # 123456, and marked as Closed following the call. Details on Case #123456 can be accessed in Blanca Peak's CRM at www.samplecrm.com/caseid=123456 | { "customer": { "name": "Jane", "email": "janecustomer@example.com" }, "ext_interaction_id": "123456", "employee": { "email": "paulagent@blancapeak.com" }, "channel": "phone", "external_url": "www.samplecrm.com/caseid=123456 " } |
Once this information is included in the API call, each piece of feedback in the Stella Connect stream will include a link back to your system.
Including Interaction Tags
Sending interaction tags alongside the interaction details will enable more actionable reporting inside Stella Connect.
| Sample Interaction | Corresponding API Call |
Jane Customer {janecustomer@example.com} had a phone interaction with Paul Agent {paulagent@blancapeak.com} today. This interaction was attached to Case # 123456, and marked as Closed following the call. Details on Case #123456 can be accessed in Blanca Peak's CRM at www.samplecrm.com/caseid=123456 Blanca Peak's system marked this case with the tags Exchange and Backorder based on the phone queue the interaction came in on and notes taken by the agent before closing the case. | { "customer": { "name": "Jane", "email": "janecustomer@example.com" }, "tags": ["Exchange","Backorder"], "ext_interaction_id": "123456", "employee": { "email": "paulagent@blancapeak.com" }, "channel": "phone", "external_url": "www.samplecrm.com/caseid=123456" } |
Once you begin sending interaction tags, new features will be enabled inside Connect:
Each Connect request will be displayed with the corresponding tags, making it easier for you to understand what drove the customer's experience
Team Member Trends dashboards will highlight each agent's top-performing and bottom-performing tags, helping you to coach more effectively
A "Tags" dashboard will identify tags that consistently drive positive or negative feedback, helping you to identify themes for training or areas that require updated processes
Specifying a Brand
For companies using Stella Connect's multi-brand feature, each request must be associated with a brand label.
Brand labels are specified in the Company Info section of the Stella Connect Admin Console during the onboarding process.
| Sample Interaction | Corresponding API Call |
Jane Customer {janecustomer@example.com} had a phone interaction with Paul Agent {paulagent@blancapeak.com} today for the brand Blanca Kids {brand label blancakids} This interaction was attached to Case # 123456, and marked as Closed following this phone call. Details on Case #123456 can be accessed in Blanca Peak's CRM at www.samplecrm.com/caseid=123456 Blanca Peak's system marked this case with the tags Exchange and Backorder based on the phone queue the interaction came in on and notes taken by the agent before closing the case. | { "customer": { "name": "Jane", "email": "janecustomer@example.com" }, "tags": ["Exchange","Backorder"], "brand": "blancakids", "ext_interaction_id": "123456", "employee": { "email": "paulagent@blancapeak.com" }, "channel": "phone", "external_url": "www.samplecrm.com/caseid=123456" } |
Marking an Interaction with a Do Not Send Flag
Although we recommend that each interaction result in a Stella Connect request, there may be some instances in which you do not want to send a Stella Connect request. For example, you may not want to send a Stella Connect request if a customer called to unsubscribe from your email market list.
To enable these exceptions, you would establish a workflow rule or trigger condition to flag these interactions with a do_not_send flag in in the API call.
| Sample Interaction | Corresponding API Call |
Jane Customer {janecustomer@example.com} had a phone interaction with Paul Agent {paulagent@blancapeak.com} today for the brand Blanca Kids {brand label blancakids}. This interaction was attached to Case # 123456, and marked as Closed following this phone call. Details on Case #123456 can be accessed in Blanca Peak's CRM at www.samplecrm.com/caseid=123456 Blanca Peak's system marked this case with the tag "Unsubscribe". According to Blanca Peak's business rules, interactions with this tag should not trigger a Stella Connect request. | { "customer": { "name": "Jane", "email": "janecustomer@example.com" }, "do_not_send": true, "tags": ["Unsubscribe"], "brand": "blancakids", "ext_interaction_id": "123456", "employee": { "email": "paulagent@blancapeak.com" }, "channel": "phone", "external_url": "www.samplecrm.com/caseid=123456" } |
Specifying a Language and Country
For companies that support their customers in multiple languages, each request should include language and country values so the request can go out in the specified language. This also requires setup within Stella Connect before it will work.
| Sample Interaction | Corresponding API Call |
Jane Customer {janecustomer@example.com} who lives in Montreal, Canada, had a phone interaction with Paul Agent {paulagent@blancapeak.com} today in French This interaction was attached to Case # 123456, and marked as Closed following this phone call. Details on Case #123456 can be accessed in Blanca Peak's CRM at www.samplecrm.com/caseid=123456 Blanca Peak's system marked this case with the tags Exchange and Backorder based on the phone queue the interaction came in on and notes taken by the agent before closing the case. | { "customer": { "name": "Jane", "email": "janecustomer@example.com" }, "tags": ["Exchange","Backorder"], "language": "fr-ca", "country": "CA", "ext_interaction_id": "123456", "employee": { "email": "paulagent@blancapeak.com" }, "channel": "phone", "external_url": "www.samplecrm.com/caseid=123456" } |
Service Recovery
After a service recovery interaction, your team lead will close the case in your internal system which will trigger a follow-up Connect request to the customer. This request will enable you to measure whether you have reversed the customer's negative sentiment.
| Sample Interaction | Corresponding API Call |
Jane Customer {janecustomer@example.com} had a successful service recovery call with Paul Agent {paulagent@blancapeak.com} This is the request ID of the response that is being recovered. This would have been provided in the data return API. This interaction was attached to Case # 123456, and marked as Closed. Details on Case #123456 can be accessed in Blanca Peak's CRM at www.samplecrm.com/caseid=123456 Blanca Peak's system marked this case with the tags compensation provided based on actions taken by the agent before closing the service recovery case. | { "do_not_send": false, "tags": ["compensation provided"], "employee": { "email": "paulagent@blancapeak.com" }, "initial_feedback_request_id": "54bd2af9-28cb-48df-8c60-cd27de080cd4", "ext_interaction_id": "123456", "external_url": "www.samplecrm.com/caseid=123456"" } |
