--- title: Customer Service API usage slug: '3326' canonical_url: https://docs.coveo.com/en/3326/ collection: apis source_format: adoc --- # Customer Service API usage This topic explains how to request [case classifications](#case-classification) and [document suggestions](#document-suggestion), for the _field filling_ and _document suggestion_ stages of the Case Assist workflow, respectively. ![Case Assist event flow](https://docs.coveo.com/en/assets/images/coveo-for-salesforce/service-api-event-flow.svg) > **Note** > > All REST API string fields are case-sensitive unless otherwise specified. > For example, [search queries aren't case-sensitive](https://docs.coveo.com/en/3074/). > > To keep behavior consistent across the [Coveo Platform](https://docs.coveo.com/en/186/), the same value passed to different REST APIs must always be passed using the same case. > For example, if the [unique product identifier](https://docs.coveo.com/en/n73f0502#define-a-unique-product-identifier), such as `ec_product_id`, is passed to the Commerce API in lowercase, then it should also be passed to the Usage Analytics Write API in lowercase. ## Case Classification The Customer Service API Case Classification feature lets you request field value suggestions to help your end users and support agents as they create support cases. **Example** A client is creating a support case with the title `GC110 malfunction` and the description `My GC110 electrical panel is cutting off intermittently`. You have previously created a case classification configuration to request suggestions for the type of issues that your end users create. You make the following request to the Customer Service API: ```http POST https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists/myc45ea55-isti-d9d5-8f1d-81be8e739b70/classify HTTP/1.1 Authorization: Bearer ********-****-****-************ ``` **Payload:** ```json { "clientId": "04850f2-ee0d-47a9-aff5-39ee47f294f9", "fields": { "subject": { "value": "GC110 malfunction" }, "description": { "value": "My GC110 electrical panel is cutting off intermittently" } }, "analytics": { "capture": true } } ``` The API returns the following payload: ```json { "fields": { "sftype": { "predictions": [ { "value": "Electrical", "confidence": 0.9180843234062195, "id": "8c02099b-a227-46c4-aad1-46468e59e6c7" } ] } }, "responseId": "123e4567-e89b-12d3-a456-426614174000" } ``` You then suggest the field value `Electrical issue` to your client in your custom UI widget. This narrows down the options that they have to choose from and simplifies their case creation experience. > **Note** > > The `visitorId` parameter is deprecated and has been replaced by the `clientId` parameter in newer versions of the Coveo UI libraries. > The `visitorId` is still supported for backward compatibility, but you should use the `clientId` in new implementations. > See [What's the client ID?](https://docs.coveo.com/en/masb0234/) for details. ### Retrieving case classifications To retrieve meaningful suggestions from the Customer Service API, provide meaningful field values in your requests. Typically, you'll want to retrieve the subject and description of the case being created, and provide them as objects in the `fields` parameter of your request payload (for example, `{"subject": { "value": "GC3000 won't start" }, "description": { "value" : "My GC3000 series propane generator won't start"} }`). You must also pass the user's [client ID](https://docs.coveo.com/en/lbjf0131/) in the `clientId` parameter (for example, `c1i3n4v1-s1t0-rid9-8f1d-81be8e739b70`). To log requests to the case classification feature as [search events](https://docs.coveo.com/en/1502/) in your [Coveo Analytics reports](https://docs.coveo.com/en/266/), set `analytics.capture` to `true` in the request body. Furthermore, we recommend that you pass the interface's language tag in the `locale` parameter (for example, `en-US`). For debugging purposes, you can set the `debug` query parameter to `true` to retrieve a detailed execution report. Avoid setting this parameter to `true` in production, as it has a negative impact on performance. Use the https://platform.cloud.coveo.com/docs?urls.primaryName=Customer%20Service#/Suggestions/postClassify[`POST /rest/organizations/{organizationId}/caseassists/{caseAssistId}/classify`^] endpoint and authenticate your request using an access token that grants the **Customer Service - Use case assist - Allowed** privilege. You can [retrieve the target `caseAssistId`](https://docs.coveo.com/en/3328#retrieving-a-case-assist-id) from the [Coveo Administration Console](https://docs.coveo.com/en/183/). For each field targeted in your configuration, the API response includes a list of `predictions`, sorted by `confidence` value. **Example** A customer is creating a case with the title `GC3000 won't start` and the description `My GC3000 series propane generator won't start`. You retrieve the customer's client ID, which is usually stored in the [local storage](https://docs.coveo.com/en/mbeh0288/) under the key `visitorId`. You request case classifications by making the following request to the Customer Service API: ```http POST https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists/myc45ea55-isti-d9d5-8f1d-81be8e739b70/classify HTTP/1.1 Authorization: Bearer ********-****-****-************ ``` **Payload:** ```json [source,json] ``` { "clientId": "c1i3n4v1-s1t0-rid9-8f1d-81be8e739b70", "fields": { "subject": { "value": "GC3000 won't start" }, "description": { "value": "My GC3000 series propane generator won't start" } }, "analytics": { "capture": true }, "locale": "en-US" } ``` ---- The API returns the following response: <<>> { "fields": { "opportunitytype": { "predictions": [ { "value": "Propane", "confidence": 0.9178082346916199, "id": "aa24b08a-0ae5-5624-966b-d687cb37f045" } ] }, "issuetype": { "predictions": [ { "value": "Ignition", "confidence": 0.8325673948382833, "id": "7d25db2a-5a9f-5bb7-bfc9-5e9e59063077" }, { "value": "Controller", "confidence": 0.5364940382730438, "id": "72a7b604-804b-5b29-a0da-ca0672741e3b" } ] } }, "responseId": "123e4567-e89b-12d3-a456-426614174000" } ``` ---- Since the confidence scores for the `Propane` and `Ignition` predictions are fairly high, you suggest them to your customer in the **Product** and **Issue type** fields of your case creation interface. ## Document Suggestion The Customer Service API Document Suggestion feature lets you suggest documents to end users and support agents as they create support cases. **Example** A client is creating a support case with the title `GC110 malfunction` and the description `My GC110 electrical panel is cutting off intermittently`. You have previously created a document suggestions configuration to request suggestions for the type of issues that your end users create. You make the following request to the Customer Service API: ```http POST https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists/myc45ea55-isti-d9d5-8f1d-81be8e739b70/documents/suggest HTTP/1.1 Authorization: Bearer ********-****-****-************ ``` **Payload:** ```json { "clientId": "04850f2-ee0d-47a9-aff5-39ee47f294f9", "fields": { "subject": { "value": "GC110 malfunction" }, "description": { "value": "My GC110 electrical panel is cutting off intermittently" } }, "analytics": { "capture": true } } ``` The API returns the following payload: ```json { "documents": [ { "title": "GC110 Series Electrical Panel Troubleshooting", "uniqueId": "84.72597$https://na174.salesforce.com/5017g000000vLFgBCM:2", "hasHtmlVersion": true, "clickUri": "https://na174.salesforce.com/5017g000000vLFgBCM", "excerpt": "The GC110 series electrical panel needs to be reset using the following process if it begins to turn on and off without warnin...", "fields": { "syssfcreatedbyid": "0056g001172vCuBMAU", "sfsystemmodstamp": 1578952955001, ... } } ], "responseId": "2394cnd8-8dnc-3nc9-k432-9dn2nd8f93nd", "totalCount": 1 } ``` You then suggest that solution item to the client before they even finish creating their case, resulting in case deflection! > **Note** > > The `visitorId` parameter is deprecated and has been replaced by the `clientId` parameter in newer versions of the Coveo UI libraries. > The `visitorId` is still supported for backward compatibility, but you should use the `clientId` in new implementations. > See [What's the client ID?](https://docs.coveo.com/en/masb0234/) for details. ### Retrieving document suggestions To retrieve meaningful suggestions from the Customer Service API, provide meaningful field values in your requests. Typically, you'll want to retrieve the subject and description of the case being created, and provide them as objects in the `fields` parameter of your request payload (for example, `{"subject": { "value": "GC3000 won't start" }, "description": { "value" : "My GC3000 series propane generator won't start"} }`). You must also pass the user's [client ID](https://docs.coveo.com/en/lbjf0131/) in the `clientId` parameter (for example, `c1i3n4v1-s1t0-rid9-8f1d-81be8e739b70`). To log requests to the document suggestion feature as [search events](https://docs.coveo.com/en/1502/) in your [Coveo Analytics reports](https://docs.coveo.com/en/266/), set `analytics.capture` to `true` in the request body. Furthermore, we recommend that you pass the interface's language tag in the `locale` parameter (for example, `en-US`). Optionally, you can pass [context](https://docs.coveo.com/en/1345/) information in the `context` parameter of your request payload (for example, `{ "product": "Propane Generator", "subproduct": "GC3000 Series" }`). Doing so would allow you to leverage this context information in your query pipeline (see [Manage ranking expression rules](https://docs.coveo.com/en/3375/) and [Manage query pipeline conditions](https://docs.coveo.com/en/1959/)). For debugging purposes, you can set the `debug` query parameter to `true` to retrieve a detailed execution report. Avoid setting this parameter to `true` in production, as it has a negative impact on performance. Use the https://platform.cloud.coveo.com/docs?urls.primaryName=Customer%20Service#/Suggestions/getSuggestDocument[`POST /rest/organizations/{organizationId}/caseassists/{caseAssistId}/documents/suggest`^] endpoint and authenticate your request using an access token that grants the **Customer Service - Use case assist - Allowed** privilege. You can [retrieve the target `caseAssistId`](https://docs.coveo.com/en/3328#retrieving-a-case-assist-id) from the [Coveo Administration Console](https://docs.coveo.com/en/183/). The API response includes a list of `documents`, which each includes the document `title`, `clickuri`, `excerpt`, and raw `fields`. **Example** A customer is creating a case with the title `GC3000 won't start` and the description `My GC3000 series propane generator won't start`. You retrieve the customer's [client ID](https://docs.coveo.com/en/lbjf0131/), which is usually stored in the [local storage](https://docs.coveo.com/en/mbeh0288/) under the key `visitorId`. You request document suggestions by making the following request to the Customer Service API: ```http POST https://platform.cloud.coveo.com/rest/organizations/myorganizationid9sd8df7s/caseassists/myc45ea55-isti-d9d5-8f1d-81be8e739b70/documents/suggest HTTP/1.1 Authorization: Bearer ********-****-****-************ ``` **Payload:** ```json { "clientId": "c1i3n4v1-s1t0-rid9-8f1d-81be8e739b70", "fields": { "subject": { "value": "GC3000 won't start" }, "description": { "value": "My GC3000 series propane generator won't start" } }, "analytics": { "capture": true }, "context": { "product": "Propane Generator", "subproduct": "GC3000 Series" }, "locale": "en-US" } ``` The API returns the following payload: ```json { "documents": [ { "title": "GC3000 Series Propane Generator Ignition", "uniqueId": "84.72597$https://na174.salesforce.com/5016g000000vLFgAAM:2", "hasHtmlVersion": true, "clickUri": "https://na174.salesforce.com/5016g000000vLFgAAM", "excerpt": "The GC3000 series propane generators need to be started up using the following process if the ignition fails on the first try: 1) Disengage the fuel source. ... 2) Use the vacuum pump provided to s...", "fields": { "syssfcreatedbyid": "0056g000002vBuCAAU", "sfsystemmodstamp": 1578952955000, ... } }, { "title": "Selecting the Right Generator for Your Needs", "uniqueId": "84.392832$https://na174.salesforce.com/5016g000000vLFfAAM:1", "hasHtmlVersion": true, "clickUri": "https://na174.salesforce.com/5016g000000vLFfAAM", "excerpt": "GenWatt offers a wide range of electric generators for every need -- from high-powered industrial-strength generators, to medium-capacity standby generators, to emergency-use portable generators.", "fields": { "syssfcreatedbyid": "0056g000002vBuCAAU", "sfsystemmodstamp": 1578952955000, ... } } ], "responseId": "2394cnd8-8dnc-3nc9-k432-9dn2nd8f93nd", "totalCount": 2 } ``` You can then retrieve these document suggestions and display them in your user case creation interface to hopefully deflect the case creation. ## Error handling You must handle Coveo errors properly if you experience network issues or unexpected downtime. This table lists the most common errors. [%header,cols=4*] |=== |HTTP status |Description |Possible causes |Retry strategy |`400` |`BAD REQUEST` a|* Request body doesn't respect expected format * Missing parameter |Not applicable |`401` |`UNAUTHORIZED` a|* Authentication token is invalid * Missing authentication |Not applicable |`403` |`FORBIDDEN` a|* Missing privilege * Missing feature flag |Not applicable |`404` |`NOT FOUND` |The resource doesn't exist. |Not applicable |`429` |`TOO MANY REQUESTS` |Too many requests were sent within a specified amount of time. |Invoke the request again using an exponential backoff. **Note**: Check the value of the `Retry-after` header before invoking the request again. |`500` |`INTERNAL SERVER ERROR` | Internal error a|* Perform the operation again using an exponential backoff. * Monitor the status of Coveo from the [Coveo Service Status](https://status.cloud.coveo.com/) page. * Write down the `X-Request-ID`. * If the situation persists, contact [Coveo Support](https://connect.coveo.com/s/case/Case/Default). |`503` |`SERVER UNAVAILABLE` |Internal error a|* Perform the operation again using an exponential backoff. * Monitor the status of Coveo from the [Coveo Service Status](https://status.cloud.coveo.com/) page. * If the situation persists, contact [Coveo Support](https://connect.coveo.com/s/case/Case/Default). |=== ## What's next? As your users interact with your Case Assist interface, you'll want to [log Case Assist events](https://docs.coveo.com/en/3437/).