REST API Reference v2

Introduction

This document describes the resources that make up the official Yonyx API v2.
The API base URL is https://developer.yonyx.com/y/apiv2/
If you have any problems or requests please contact us.

API key and API secret

After you sign up with Yonyx, you can retrieve the API key and API secret from the Security page. The API keys provide full access to the Yonyx resources owned by your account.

The following is an example of API key and API secret:

API Key (a 36-character, alphanumeric string). E.g.: f4389790-33ba-11e3-9459-bc764e10f0e8.
API Secret (a 45-character string). E.g.: SGtuFbwOlsQTOlGuWZe2li4KvWh8y0XXvBbAZxbwL+Y= 

Your API Key identifies you as the party responsible for service requests. You include it in each request, so it’s not a secret.

Each API Key has an API Secret associated with it. This key is just a long string of characters that you use to calculate the digital signature that you include in the request.

Your API Secret is a secret, and only you and Yonyx should have it. Don’t e-mail it to anyone or include it in Yonyx requests. No authorized person from Yonyx will ever ask for your API Secret.

When you create a request, you create a digital signature with your API Secret and include it in the request along with your API Key. When we get the request, we use your API Key to look up the corresponding API Secret. We use the API Secret key to validate the signature and confirm that you’re the request sender.

Signing and Authenticating API Requests

Yonyx API uses a custom HTTP scheme based on a keyed-HMAC (Hash Message Authentication Code) for authentication. To authenticate a request, you first concatenate parameters of the request sorted by parameter name to form a string. You then use your Yonyx API secret to calculate the HMAC of that string. The output of the HMAC algorithm is called the signature. Finally, you add this signature as a parameter of the request by using the syntax described below.

Let’s say you want to retrieve a list of all guides containing keywords.
Step 1: Construct the request URL:

[Base URL]  https://developer.yonyx.com/y/apiv2/ 
[Parameter 1]  ?key={your-api-key} 
[Parameter 2]  &lobid=cxxx8fae-4xx7-4exx-xxa5-96xxadxx6xx1  
[Parameter 3]  &object=guides  
[Parameter 4]  &keyword=keyword1+keyword2+keyword3  
[Parameter 5]  &offset=5  
[Parameter 6]  &expires=1141889120 

Step 2: Create String-to-Sign by sorting the parameters in the request lexicographically by parameter name.
Notice question mark “?” is not included in String-to-Sign.

String-to-Sign before sorting:

[Parameter 1]  key={your-api-key}  Notice that the question mark "?" has been removed.
[Parameter 2]  &lobid=cxxx8fae-4xx7-4exx-xxa5-96xxadxx6xx1  
[Parameter 3]  &object=guides  
[Parameter 4]  &keyword=keyword1+keyword2+keyword3  
[Parameter 5]  &offset=5  
[Parameter 6]  &expires=1141889120 
String-to-Sign after sorting:

[Parameter 1]  expires=1141889120 
[Parameter 2]  &key={your-api-key} 
[Parameter 3]  &keyword=keyword1+keyword2+keyword3  
[Parameter 4]  &lobid=cxxx8fae-4xx7-4exx-xxa5-96xxadxx6xx1  
[Parameter 5]  &object=guides  
[Parameter 6]  &offset=5  

Step 3: Sign String-to-Sign:

Line breaks were added for readability.  Actual String-to-Sign should be a continuous string. 
E.g.: expires=1141889120&key={your-api-key}&keyword=keyword1+keyword2+keyword3&lobid=cxxx8fae-4xx7-4exx-xxa5-96xxadxx6xx1&object=guides&offset=5 signature = URL-Encode( Base64( HMAC-SHA256( String-to-Sign ) ) );

Step 4: Add Signature as a parameter to the request:

[Base URL]  https://developer.yonyx.com/y/apiv2/ 
[Parameter 1]  ?key={your-api-key} 
[Parameter 2]  &lobid=cxxx8fae-4xx7-4exx-xxa5-96xxadxx6xx1  
[Parameter 3]  &object=guides  
[Parameter 4]  &keyword=keyword1+keyword2+keyword3  
[Parameter 5]  &offset=5  
[Parameter 6]  &expires=1141889120 
[Parameter 7]  &signature=E1PdLzqDVjtahJu4yqvfZPZP%2Bbocfs16QwdXqgOpVpU%3D

When the system receives an authenticated request, it fetches the Yonyx API secret that you claim to have and uses it in the same way to compute a signature for the message it received. It then compares the signature it computed against the signature provided by you. If the two signatures match, the system concludes that you must have access to the API secret. If the two signatures do not match, the request is dropped and the system responds with an error message.

All API requests must be made over HTTPS. You must authenticate for all requests. The API key is used for identity and usage tracking purposes. You will have to pass the API key in your API call. It is required that you pass a valid and active API key. The API will return a 401 Unauthorized Http status if the API key is invalid.

C# code example to generate signature


using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Security.Cryptography;

namespace Yonyx
{
    class GenerateSignature
    {

        static void Main()
        {

            var data = "String-to-Sign";
            var secretKey = "Secret-Key";

            // Initialize the keyed hash object using the secret key as the key
            HMACSHA256 hashObject = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey));

            // Computes the signature by hashing the data with the secret key as the key
            var signature = hashObject.ComputeHash(Encoding.UTF8.GetBytes(data));

            // Base 64 Encode
            var encodedSignature = Convert.ToBase64String(signature);

            // URL Encode
            encodedSignature = System.Web.HttpUtility.UrlEncode(encodedSignature);

            Console.WriteLine("Signature: " + encodedSignature);

            Console.ReadKey();

        }

    }
}

URL Encoding in .Net

.Net outputs percent-encoding triplet in lower case. Eg. URL-Encode ( “/”) will result in “%2f” instead of the normalized version “%2F”.

Although RFC 3986 outlines that both upper case and lower case hexadecimal digits within a percent-encoding triplet (%2f or %2F) are equivalent, for the sake of interoperability there needs to be common consenses among developers, providers and consumers.

This is why the same RFC 3986 also lays out rules for normalization.

“For all URIs, the hexadecimal digits within a percent-encoding
triplet (e.g., “%3a” versus “%3A”) are case-insensitive and therefore
should be normalized to use uppercase letters for the digits A-F.”

So, if you are using .Net libraries to URL encode, pass the output through a function similar to this:

static string NormalizeUrlEncoding(string value) {
    value = HttpUtility.UrlEncode(value);
    return Regex.Replace(value, "(%[0-9a-f][0-9a-f])", c => c.Value.ToUpper());
}

Java code example to generate signature


import java.net.URLEncoder;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

import org.apache.commons.codec.binary.Base64;

public class GenerateSignature {

   private static final String ALGORITHM = "HmacSHA256";
   
   public static void main(String[] args) throws Exception {
      //Signature = Base64( HMAC-SHA256( StringToSign ) );

        String data = "String-to-Sign";
        String secretKey = "Secret-Key";

        // Initialize the keyed hash object using the secret key as the key
      SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(), ALGORITHM);
      Mac mac = Mac.getInstance(ALGORITHM);
      mac.init(signingKey);

      // Computes the signature by hashing the data with the secret key as the key
      byte[] rawHmac = mac.doFinal(data.getBytes());     
      
      // Base 64 Encoding
      String encodedString = new String(Base64.encodeBase64(rawHmac));
      
      // URL Encoding
      encodedString = URLEncoder.encode(encodedString, "UTF-8");

      System.out.println("Signature: " + encodedString);
      
   }

}

PHP code example to generate signature


< ?php
 
   $data = "String-to-Sign";
   $secretKey = "Secret-Key";
 
   // Computes the signature by hashing the data with the secret key as the key
   $signature = hash_hmac('sha256', $data, $secretKey, true);
 
   // Base 64 Encoding
   $encodedSignature = base64_encode($signature);
   
   // URL Encoding
   $encodedSignature = urlencode($encodedSignature);
 
   echo "Signature: " . $encodedSignature;
 
?>

Python code example to generate signature


import hmac
import hashlib
import base64
import urllib

data = "String-to-Sign"
secretKey = "Secret-Key"
     
# Computes the signature by hashing the data with the secret key as the key
hash = hmac.new(secretKey, msg=data, digestmod=hashlib.sha256).digest()

# and Base 64 Encodes
encodedString = base64.b64encode(hash).decode()

#URL Encoding
encodedString = urllib.quote(encodedString)

print encodedString;

Node.js code example to generate signature


    var crypto = require('crypto')
     , algorithm = "sha256"
     , data = "String-to-Sign"
     , secretKey = "Secret-Key"
     , hash
     , encodedString 
     
    // Computes the signature by hashing the data with the secret key as the key
    hash = crypto.createHmac(algorithm, secretKey).update(data)

    // and Base 64 Encodes
    encodedString = hash.digest(encoding='base64')

    //URL Encoding
    encodedString = encodeURIComponent(encodedString)

    console.log(encodedString);

Rate Limiting

Rate limits are divided into 15-minute intervals for generic calls and 24-hour intervals for user-specific calls. You will be allowed to make 100 generic calls every 15 minutes and 250 user-specific calls every 24 hours. We limit API requests to a reasonable number in order to ensure that one customer’s use of Yonyx API does not adversely affect other customers. Without rate limiting, one customer could flood our system with requests in a way that would prevent another customer from being able to use the system. This happens sometimes when customers are first working with an API – a simple programming error could flood the API with requests that the customer doesn’t mean to send.

If you hit the rate limit, this is the body of the HTTP 429 (Too Many Requests) message that you will see. When you see this response, just retry your request after couple minutes.

{
  "error": [
    {
      "code": 10006,
      "message": "Error Code: 10006 - Sorry, you've exceeded your limit of {x} requests in the last 15 minutes."
    }
  ] 
}

Supported object types

Yonyx API supports these object types:

OBJECT TYPES
lobs
catalogs
guides_by_keyword
guides_by_tag
guides
guidance_family
create_feedback
create_compliment
transcript
transcripts_by_refid
associate_refid_with_transcript
transcript_ids
enable_user
disable_user

Retrieve an existing line of business

Retrieves the details of an existing line of business (lob). You need to only supply the unique lob identifier.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
object: lobs (Required) The object type to be retrieved.
id: (Required) The identifier of the lob to be retrieved.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=lobs&id={lob_id}&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns an lob object if a valid identifier was provided. { "object":"lob", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Self Service" }

List all lines of business

Returns a list of your lines of business. The lobs are returned sorted by creation date, with the most recently created lob appearing first.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
object: lobs (Required) The object type to be retrieved.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=lobs&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a dictionary with a data property that contains an array of lobs. Each entry in the array is a separate lob object. If no lobs are available, the resulting array will be empty. This request should never return an error. { "object":"list", "count":3, "data":[ { "object":"lob", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Self Service" }, { "object":"lob", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Customer Service" }, {...} ] }

Retrieve an existing catalog

Retrieves the details of an existing catalog. You need to only supply the unique catalog identifier.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
object: catalogs (Required) The object type to be retrieved.
id: (Required) The identifier of the catalog to be retrieved.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=catalogs&id={CATALOG_ID}&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a catalog object if a valid identifier was provided. { "object":"catalog", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Fix an Issue with Inkjet Printer", "guides":{ "object":"list", "count":5, "data":[ { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Computer Cannot Find Printer or Will not Print" }, { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Print Head Errors on Inkjet Printers" }, {...}, {...}, {...}, ] } }

List all catalogs

Returns a list of catalogs belonging to a particular line of business. The catalogs are returned sorted by creation date, with the most recently created catalog appearing first.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
lobid: (Required) Line of business ID.
object: catalogs (Required) The object type to be retrieved.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&lobid={lob_id}&object=catalogs&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a dictionary with a data property that contains an array of catalogs. Each entry in the array is a separate catalog object. If no catalogs are available, the resulting array will be empty. This request should never return an error. { "object":"list", "count":3, "data":[ { "object":"catalog", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Fix an Issue with Inkjet Printer", "guides":{ "object":"list", "count":8, "data":[ { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Computer Cannot Find Printer or Will not Print" }, { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Print Head Errors on Inkjet Printers" }, {...}, {...}, {...} ] } }, { "object":"catalog", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Customer Interactive HelpDesk", "guides":{ "object":"list", "count":8, "data":[ { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Having Print Quality issues" }, { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Wireless Scanning issues" }, {...}, {...}, {...} ] } }, {...} ] }

List all guides containing keyword

Returns a list of yonyx guidance steps matching the provided keyword(s). A max of 20 objects will be returned starting at index offset if provided.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
lobid: (Required) Line of business ID.  If this LOB is configured with Root-Only search, this request will search across all published roots.
object: guides_by_keyword (Required) The object type to be retrieved.
keyword: (Required) Keywords that will be used to match.  URL encode keywords.  Eg. URL-Encode( "keyword1 keyword2's keyword3" ) should result in "keyword1+keyword2%27s+keyword3"
offset: (Optional) Default is 0. An offset into the list of returned items. The API will return the number of items starting at that offset.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&lobid={lob_id}&object=guides_by_keyword&keyword={keywords}&offset=5&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a dictionary with a data property that contains an array of guides, starting at index offset. Each entry in the array is a separate guide object. If no guides are available, the resulting array will be empty. This request should never return an error. { "object":"list", "count":20, "next_offset":26, "data":[ { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Print Head Errors on Inkjet \u003cem\u003ePrinters\u003c/em\u003e", "match_fragment":"You see an error message on your \u003cem\u003ePrinter\u003c/em\u003e\u0027s LCD panel. This message is typically related to either the Print head or the Cartridge. Let us guide you interactively to help resolve the \u003cem\u003eissue\u003c/em\u003e you are facing. ... What model \u003cem\u003eprinter\u003c/em\u003e do you need help with?" }, { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"\u003cem\u003ePrinter\u003c/em\u003e is Printing Banner Page on every given Print Job", "match_fragment":"This \u003cem\u003eissue\u003c/em\u003e is noticed if the banner Page option is selected in EWS (Embedded Web Server). To resolve this Problem: Go to EWS page using the \u003cem\u003eprinter\u003c/em\u003e IP address and then Go to Settings -\u003e General Settings -\u003e General Active Card Settings -\u003e Uncheck Banner Page and Submit Selection. ... Was the \u003cem\u003eissue\u003c/em\u003e resolved ?" }, {...}, {...}, {...} ] }

List all guides by tag

Returns a list of yonyx guidance steps associated with the tag(s). A max of 20 objects will be returned starting at index offset if provided.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
lobid: (Required) Line of business ID.  If this LOB is configured with Root-Only search, this request will search across all published roots.
object: guides_by_tag (Required) The object type to be retrieved.
tag: (Required) Tags that will be used to match.  URL encode tags.  Eg. URL-Encode( "tag1 tag2's tag" ) should result in "tag1+tag2%27s+tag3"
offset: (Optional) Default is 0. An offset into the list of returned items. The API will return the number of items starting at that offset.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&lobid={lob_id}&object=guides_by_tag&tag={tags}&offset=5&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a dictionary with a data property that contains an array of guides, starting at index offset. Each entry in the array is a separate guide object. If no guides are available, the resulting array will be empty. This request should never return an error. { "object":"list", "count":20, "next_offset":26, "data":[ { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Print Head Errors on Inkjet \u003cem\u003ePrinters\u003c/em\u003e", "match_fragment":" ... " }, { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"\u003cem\u003ePrinter\u003c/em\u003e is Printing Banner Page on every given Print Job", "match_fragment":" ... " }, {...}, {...}, {...} ] }

List all guides

Returns a list of root guidance steps (start point of an interactive guidance flow) belonging to a particular line of business. A max of 20 objects will be returned starting at index offset if provided.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
lobid: (Required) Line of business ID.
object: guides (Required) The object type to be retrieved.
offset: (Optional) Default is 0. An offset into the list of returned items. The API will return the number of items starting at that offset.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&lobid={lob_id}&object=guides&offset=5&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a dictionary with a data property that contains an array of guides, starting at index offset. Each entry in the array is a separate guide object. If no guides are available, the resulting array will be empty. This request should never return an error. { "object":"list", "count":20, "next_offset":26, "data":[ { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Handling \"Windows Update Failed\" Error Msg.", "match_fragment":"" }, { "object":"guide", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"I need help for resolving Internet accessibility issue", "match_fragment":"" }, {...}, {...}, {...} ] }

Retrieve an existing guidance family

Retrieves the details of an existing guidance step.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
object: guidance_family (Required) The object type to be retrieved.
id: (Required) The identifier of the node. Can pass either a Guidance Step Id or a User Response Id.
      Guidance Step Id is passed during initial request of the traversal. 
      User Response Id is passed during subsequent requests of the traversal.  This will fetch the next Guidance Step connected to this User Response. 
user: (Required) The end user's email address (the user viewing this content).
type: (Required) The end user's type. 
      Pass "ext" for external user or "int" for internal user.  
      Internal users are typically your agents/consultants/employees using this guide to help your customers either on the phone or on the field.  
      External users are typically your customers using this guide to self help.
session: (Required) Session ensures that all the steps of this guide traversed by the user show up as a single incident under Analytics. 
      Pass "initial" for initial request / first step of the guide.  
      For subsequent requests until the user exits out of the guide, pass the value of session property from the previous response. 
      Failing to pass this will result in a new incident per step.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST Initial request for a guide $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=guidance_family&id={YONYX_ID}&user=user@domain.com&type=int&session=initial&expires={expires}&signature={signature} Subsequent request for the steps of the same guide $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=guidance_family&id={YONYX_ID}&user=user@domain.com&type=int&session=NBwSd2ytk2X%2FbjqA5h2BXsKuHJThzDsVe%2F%2BiLg26kfAe8Wwa6MrOffPGedBSad2l&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a guidance family object if a valid identifier was provided. { "object":"guidance_family", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Computer Cannot Find Printer or Will not Print", "body":"\u003cp\u003eThese steps will help you resolve communication issues between your computer and your All-in-One inkjet printer.\u003c/p\u003e", "inquiry":"How is your computer connected to your printer?", "notes": "", "commandInternalName": "command-name", "placeholders": { "object": "list", "count": 3, "data": [ "{{ph:placeholder-name1}}", "{{ph:placeholder-name2}}", "{{ph:placeholder-name3}}" ] }, "redirectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "redirectType": "guidance_family or catalog or lob", "user_responses":{ "object":"list", "count":3, "data":[ { "object":"user_response", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "body":"Wired via USB", "conditionGrouping": "all", "conditions": { "object": "list", "count": 1, "data": [ { "operator": "equal-to", "operand": "some value" } ] } }, { "object":"user_response", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "body":"Wireless" "conditionGrouping": "all", "conditions": { "object": "list", "count": 1, "data": [ { "operator": "equal-to", "operand": "some value" } ] } }, { "object":"user_response", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "body":"I need help connecting to a wireless network" "conditionGrouping": "all", "conditions": { "object": "list", "count": 1, "data": [ { "operator": "equal-to", "operand": "some value" } ] } } ] }, "transcriptId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "transcriptUrl":"https://interfacesecuritysystemsllc.yonyx.com/y/incident/?did=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "session":"NBwSd2ytk2X%2FbjqA5h2BXsKuHJThzDsVe%2F%2BiLg26kfAe8Wwa6MrOffPGedBSad2l" }

Create Feedback

Creates a feedback within an active traversal of a guide. This method can only be called during a live traversal.

HTTP METHOD: POST

PARAMETERS
key: (Required) Your API key.
object: create_feedback (Required) The object type to be retrieved.
feedback: (Required) Feedback text not more than 5000 chars long.
session: (Required) Get this value from the response of the previous "guidance_family" method call. 
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP POST REQUEST $ curl https://developer.yonyx.com/y/apiv2/ --data "expires={expires}&feedback={feedback-text}&key={your-api-key}&object=create_feedback&session={session-from-guidance-family-response}&signature={signature}" EXAMPLE RESPONSE Returns a success message. { "message":"Feedback created successfully." }

Create Compliment

Creates a compliment within an active traversal of a guide. This method can only be called during a live traversal.

HTTP METHOD: POST

PARAMETERS
key: (Required) Your API key.
object: create_compliment (Required) The object type to be retrieved.
compliment: (Required) Compliment text not more than 5000 chars long.
session: (Required) Get this value from the response of the previous "guidance_family" method call. 
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP POST REQUEST $ curl https://developer.yonyx.com/y/apiv2/ --data "expires={expires}&compliment={compliment-text}&key={your-api-key}&object=create_compliment&session={session-from-guidance-family-response}&signature={signature}" EXAMPLE RESPONSE Returns a success message. { "message":"Compliment created successfully." }

Create Feedback without session

Creates a feedback within a traversal of a guide.

HTTP METHOD: POST

PARAMETERS
key: (Required) Your API key.
object: create_feedback_sessionless (Required) The object type to be retrieved.
feedback: (Required) Feedback text not more than 5000 chars long.
email: (Required) Email address of the user or system user.
transcriptId: (Required) Id of the transcript you want this feedback to be created in.
guidanceId: (Required) Id of the guidance step where you want to create this feedback. 
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP POST REQUEST $ curl https://developer.yonyx.com/y/apiv2/ --data "expires={expires}&feedback={feedback-text}&key={your-api-key}&object=create_feedback_sessionless&email={email-of-user}&transcriptId={id-of-transcript}&guidanceId={id-of-guidance-step}&signature={signature}" EXAMPLE RESPONSE Returns a success message. { "message":"Feedback Sessionless created successfully." }

Create Compliment without session

Creates a compliment within a traversal of a guide.

HTTP METHOD: POST

PARAMETERS
key: (Required) Your API key.
object: create_compliment_sessionless (Required) The object type to be retrieved.
compliment: (Required) Compliment text not more than 5000 chars long.
email: (Required) Email address of the user or system user.
transcriptId: (Required) Id of the transcript you want this compliment to be created in.
guidanceId: (Required) Id of the guidance step where you want to create this compliment. 
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP POST REQUEST $ curl https://developer.yonyx.com/y/apiv2/ --data "expires={expires}&compliment={compliment-text}&key={your-api-key}&object=create_compliment_sessionless&email={email-of-user}&transcriptId={id-of-transcript}&guidanceId={id-of-guidance-step}&signature={signature}" EXAMPLE RESPONSE Returns a success message. { "message":"Compliment Sessionless created successfully." }

Retrieve an existing Transcript

Retrieves the details of an existing transcript. You need to only supply the unique Transcript Id. The startTime and endTime are in UTC time. You will need to convert them to desired timezone.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
object: transcript (Required) The object type to be retrieved.
id: (Required) The identifier of the Transcript to be retrieved.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=transcript&id={TRANSCRIPT_ID}&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a Transcript object if a valid identifier was provided. { "object":"transcript", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "url":"https://subdomain.yonyx.com/y/incident/?did\u003dxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "steps":{ "object":"list", "count":5, "data":[ { "object":"transcript_step", "type":"guidance_step", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"My TV Doesn\u0027t work", "question":"Is your TV plugged into the wall socket?", "duration":"00:00:06" }, { "object":"transcript_step", "type":"user_response", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"No it is not." }, { "object":"transcript_step", "type":"guidance_step", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Plug it in", "question":"Do you now see the red light come on?", "duration":"00:18:55" }, { "object":"transcript_step", "type":"user_response", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"No it is not." }, { "object":"transcript_step", "type":"guidance_step", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Plug it in", "question":"Do you now see the red light come on?", "duration":"00:00:02" } ] }, "summary":"\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:06] My TV Doesn\u0027t work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:18:55] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:00:02] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------", "ownerName":"user1", "ownerEmail":"user1@company.com", "startTime":1452855652483, "endTime":1452856659750 }

List all Transcripts associated with a Reference Id

Returns a list of all Transcripts associated with the Reference Id provided. The Transcripts are returned sorted by creation date, with the most recently created Transcript appearing first.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
object: transcripts_by_refid (Required) The object type to be retrieved.
rid: (Required) The Reference Id, typically your CRM or Service Desk incident Id.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=transcripts_by_refid&rid={reference-id}&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a dictionary with a data property that contains an array of Transcripts. Each entry in the array is a separate Transcript object. If no Transcripts are available, the resulting array will be empty. The startTime and endTime are in UTC time. You will need to convert them to desired timezone { "object":"list", "count":2, "data":[ { "object":"transcript", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "referenceId":"xxxxxxxx", "url":"https://subdomain.yonyx.com/y/incident/?did\u003dxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "steps":{ "object":"list", "count":3, "data":[ { "object":"transcript_step", "type":"guidance_step", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"My TV Doesn\u0027t work", "question":"Is your TV plugged into the wall socket?", "duration":"00:00:06" }, { "object":"transcript_step", "type":"user_response", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"No it is not." }, { "object":"transcript_step", "type":"guidance_step", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Plug it in", "question":"Do you now see the red light come on?", "duration":"00:18:55" } ] }, "summary":"\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:06] My TV Doesn\u0027t work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:18:55] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------", "ownerName":"user1", "ownerEmail":"user1@company.com", "startTime":1452855652483, "endTime":1452856659750 }, { "object":"transcript", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "referenceId":"xxxxxxxx", "url":"https://subdomain.yonyx.com/y/incident/?did\u003dxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "steps":{ "object":"list", "count":5, "data":[ { "object":"transcript_step", "type":"guidance_step", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"My TV Doesn\u0027t work", "question":"Is your TV plugged into the wall socket?", "duration":"00:00:06" }, { "object":"transcript_step", "type":"user_response", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"No it is not." }, { "object":"transcript_step", "type":"guidance_step", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Plug it in", "question":"Do you now see the red light come on?", "duration":"00:18:55" }, { "object":"transcript_step", "type":"user_response", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"No it is not." }, { "object":"transcript_step", "type":"guidance_step", "id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "title":"Plug it in", "question":"Do you now see the red light come on?", "duration":"00:00:02" } ] }, "summary":"\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:06] My TV Doesn\u0027t work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:18:55] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:00:02] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------", "ownerName":"user1", "ownerEmail":"user1@company.com", "startTime":1452855652483, "endTime":1452856659750 } ] }

Associate Reference Id with Transcript

Associates Reference ID (typically your CRM or Service Desk incident Id) with an existing Transcript.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
object: associate_refid_with_transcript (Required) The object type to be retrieved.
rid: (Required) The Reference Id, typically your CRM or Service Desk incident Id.
id: (Required) The Transcript Id. This is Yonyx incident Id.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=associate_refid_with_transcript&rid={reference-id}&id{transcript-id}&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a success message. { "message":"Reference ID associated with Transcript successfully." }

Associate Reference Id with multiple Transcript (up to 10)

Associates Reference ID (typically your CRM or Service Desk incident Id) with multiple existing Transcripts.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
object: associate_refid_with_transcript (Required) The object type to be retrieved.
rid: (Required) The Reference Id, typically your CRM or Service Desk incident Id.
ids: (Required) Transcript Ids up to 10. These are Yonyx incident Ids.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=associate_refid_with_transcript&rid={reference-id}&id{transcript-id}&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a success message. { "message":"Reference ID associated with Transcript successfully." }

List all Transcript IDs of a line of business

Returns a list of Transcript Ids since the offset. A max of 100 Ids will be returned starting at the offset provided.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
lobid: (Required) Line of business ID.
object: transcript_ids (Required) The object type to be retrieved.
offset: (Required) An offset into the list of returned items. The API will return the number of items starting at that offset.  
      Offset accepts 2 types of values:
      - The date since when to retrieve the list of Transcript Ids, specified as the number of milliseconds since the epoch (00:00:00 UTC on January 1, 1970).  Eg. 1477938600000
      - The next_offset from the response of the previous API request. The value of next_offset is nothing but a Transcript ID. Eg. 99988830-047c-11e4-9638-bc764e10f0e8           
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch (00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected.

EXAMPLE HTTP GET REQUEST
Initial Request - pass date value as offset
$ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&lobid={lob_id}&object=transcript_ids&offset=1477938600000&expires={expires}&signature={signature}

Subsequent Request - pass next_offset (Transcript Id) as offset
$ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&lobid={lob_id}&object=transcript_ids&offset=99988830-047c-11e4-9638-bc764e10f0e8&expires={expires}&signature={signature}

Notice how the value of parameter offset is different between Initial and Subsequent requests.  
In the initial request the value of offset is a date specified as a number of milliseconds.
In the seubsequent request the value of offset is a value of property "next_offset" from the response of previous request.

EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of Transcript Ids, starting at provided offset. If no Transcript Ids are available, the resulting array will be empty. This request should never return an error.
{
   "object": "list",
   "count": 100,
   "next_offset": "c6bee1b0-bb59-11e5-87df-46894e2acb2b",
   "data": [
      "6c38a2f0-xx50-xxxx-xxxx-0800xxxxxxxx",
      "3f8b9580-xx3e-xxxx-xxxx-0800xxxxxxxx",
      "0d6dd770-xx3e-xxxx-xxxx-0800xxxxxxxx",
      "0f750e90-xx3d-xxxx-xxxx-0800xxxxxxxx",
      {...},
      {...},
      {...}
   ]
}

Enable User

Enable a disabled user.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
object: enable_user (Required) The object type to be retrieved.
user: (Required) The email address of the user you want to enable.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=enable_user&user={user-email-address}&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a success message. { "message":"User enabled successfully." }

Disable User

Disable an enabled user.

HTTP METHOD: GET

PARAMETERS
key: (Required) Your API key.
object: disable_user (Required) The object type to be retrieved.
user: (Required) The email address of the user you want to disable.
signature: (Required) The URL encoding of the Base64 encoding of the HMAC-SHA256 of String-to-Sign.
expires: (Required) The time when the signature expires, specified as the number of milliseconds since the epoch 
(00:00:00 UTC on January 1, 1970). A request received after this time (according to the server) will be rejected. EXAMPLE HTTP GET REQUEST $ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=disable_user&user={user-email-address}&expires={expires}&signature={signature} EXAMPLE RESPONSE Returns a success message. { "message":"User disabled successfully." }

Errors

Yonyx API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with Yonyx API servers..

HTTP STATUS CODE SUMMARY
200 OK - Everything worked as expected.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - No valid API key was provided.
402 Request Failed - Parameters were valid but request failed.
404 Not Found - The requested item doesn't exist.
500, 502, 503, 504 Server errors - something went wrong on Yonyx API end.

Sign Up for a 30-day Free-Trial

Share this article

Back to top