Deprecated Version 2
This version of Yonyx REST API is no longer actively maintained and support for this version will stop on December 31, 2024.
For up-to-date information, see the latest version.
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 questions 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_by_keyword
[Parameter 4] &keyword=keyword1+keyword2+keyword3
[Parameter 5] &offset=5
[Parameter 6] &expires=1524066580844
Step 2: Create String-to-Sign by sorting the parameters in the request alphabetically 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_by_keyword
[Parameter 4] &keyword=keyword1+keyword2+keyword3
[Parameter 5] &offset=5
[Parameter 6] &expires=1524066580844
String-to-Sign after sorting:
[Parameter 1] expires=1524066580844
[Parameter 2] &key={your-api-key}
[Parameter 3] &keyword=keyword1+keyword2+keyword3
[Parameter 4] &lobid=cxxx8fae-4xx7-4exx-xxa5-96xxadxx6xx1
[Parameter 5] &object=guides_by_keyword
[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=1524066580844&key={your-api-key}&keyword=keyword1+keyword2+keyword3&lobid=cxxx8fae-4xx7-4exx-xxa5-96xxadxx6xx1&object=guides_by_keyword&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_by_keyword
[Parameter 4] &keyword=keyword1+keyword2+keyword3
[Parameter 5] &offset=5
[Parameter 6] &expires=1524066580844
[Parameter 7] &signature=E1PdLzqDVjtahJu4yqvfZPZP%2Bbocfs16QwdXqgOpVpU%3DWhen 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
C# code example to generate signature. Download code.
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();
}
static String getExpires()
{
long millis = (long)((DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0)).TotalSeconds * 1000) + 900000;
return millis.ToString();
}
}
}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
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 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
Python code example to generate signature
import time
import datetime,calendar
import hmac
import hashlib
import base64
import urllib.request, urllib.parse, urllib.error
from collections import OrderedDict
from tenacity import retry, wait_random_exponential, stop_after_attempt
import requests
import json
from datetime import datetime, timedelta
YONYX_API_BASE_URL = 'https://developer.yonyx.com/y/apiv2/'
YONYX_API_KEY = '<api-key-here>'
YONYX_API_SECRET = '<api-secret-here>'
def get_epoch_ms(year, month, day, hour, minute, second):
date = datetime(year, month, day, hour, minute, second)
output = calendar.timegm(date.timetuple())
return output * 1000
def get_current_epoch_ms():
# Return the time that is 60 minutes before the current time.
return int(time.time() - 3600) * 1000
# Beginning of day yesterday
def get_bod_yesterday_ms():
yesterday = datetime.now() - timedelta(days=1)
yesterday_bod = yesterday.replace(hour=0, minute=0, second=0, microsecond=0)
return int(yesterday_bod.timestamp()) * 1000
def get_expiry_ms():
one_min_msec = 60000
expires_unix_ts = int(time.time() * 1000) + (one_min_msec * 15)
return expires_unix_ts
def generate_url(params):
# Add API key parameters
params['key'] = YONYX_API_KEY
# Sort parameters alphabetically
sorted_params = OrderedDict(sorted(params.items()))
# Convert to string
string_to_sign = '&'.join(['{}={}'.format(k, v) for k, v in sorted_params.items()])
# Sign the string
signature = sign(string_to_sign)
# Add Signature parameter
params['signature'] = signature
# Sort parameters alphabetically
sorted_params = OrderedDict(sorted(params.items()))
# Generate complete API URL
complete_url = YONYX_API_BASE_URL + '?' + '&'.join(['{}={}'.format(k, v) for k, v in sorted_params.items()])
return complete_url
def sign(string_to_sign):
signing_key = YONYX_API_SECRET.encode('utf-8')
data_bytes = string_to_sign.encode('utf-8')
# HMAC-SHA256
mac = hmac.new(signing_key, msg=data_bytes, digestmod=hashlib.sha256)
raw_hmac = mac.digest()
# Base64 encode
encoded = base64.b64encode(raw_hmac)
encoded = encoded.decode('utf-8')
# URL encode
encoded = urllib.parse.quote(encoded, safe='')
return encoded
@retry(wait=wait_random_exponential(min=1, max=40), stop=stop_after_attempt(3))
def make_request(url):
try:
response = requests.get(url)
response.raise_for_status() # Raise an exception if the response status code indicates an error
# print("Response Status Code:", response.status_code)
data = response.json() # parse the response content as JSON
# print(json.dumps(data, indent=4)) # Pretty print the JSON
return data
except Exception as e:
print("Unable to make APi request")
print(f"Exception: {e}")
return e
def save_data(data):
# TODO: Save data somewhere
print("Save data somewhere")
# ##############################################
# # RETRIEVE SINGLE TRANSCRIPT BY ID
# ##############################################
# params = {
# 'object':'transcript',
# 'id':'<transcript-id-here>',
# "expires": expiry
# }
# print(generate_url(params))
###############################################################
# RETRIEVE MULTIPLE TRANSCRIPTS BY LOBID, STARTDATE, AND ENDDATE
###############################################################
# Batch bounds
start_date_ms = get_current_epoch_ms() # Current date at least 60 mins before current time
end_date_ms = get_epoch_ms(2023, 8, 1, 0, 0, 0) # Past date
# Pagination offset within a batch
offset = start_date_ms
while True:
params = {
"object": "transcripts",
"lobid": "<lob-id-here>",
"offset": offset,
"endDate": end_date_ms,
"expires": get_expiry_ms()
}
url = generate_url(params)
print(url)
response = make_request(url)
print(response)
print(response["object"])
# Iterate and save somewhere
save_data(response["data"])
# Handle pagination within the batch
if "next_offset" in response:
# More transcripts exist in this batch
print('Gettint next page from the same Batch')
offset = response["next_offset"]
else:
# No more transcripts exist in this batch
print('Starting the next Batch')
end_date_ms = start_date_ms
start_date_ms = get_current_epoch_ms()
offset = start_date_ms
print(f'Offset: {offset}')
print(f'Start Date in Millis: {start_date_ms}')
print(f'End Date in Millis: {end_date_ms}')
time.sleep(10)Node.js code example to generate signature
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 5-minute intervals. You will be allowed to make 100 calls every 5 minutes. 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 5 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
set_incident_placeholder_values
set_form_valuesRetrieve 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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
$ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=lobs&id={lob_id}&expires=1524066580844&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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
$ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=lobs&expires=1524066580844&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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
$ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=catalogs&id={CATALOG_ID}&expires=1524066580844&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',
updatedDate : 1444856689506
},
{
object : 'guide',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Print Head Errors on Inkjet Printers',
updatedDate : 1451056689506
},
{ '': '' },
{ '': '' }
]
}
}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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
$ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&lobid={lob_id}&object=catalogs&expires=1524066580844&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 : 5,
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',
updatedDate : 1452856689506
},
{
object : 'guide',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Print Head Errors on Inkjet Printers',
updatedDate : 1452856689300
},
{ '': '' },
{ '': '' }
]
}
},
{
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',
updatedDate : 1444856689506
},
{
object : 'guide',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Wireless Scanning issues',
updatedDate : 1451056689506
},
{ '': '' },
{ '': '' }
]
}
},
{ '': '' },
{ '': '' }
]
}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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
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?',
updatedDate : 1444856689506
},
{
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 ?',
updatedDate : 1451056689506
},
{ '': '' },
{ '': '' }
]
}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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
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=1524066580844&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 : ' ... ',
updatedDate : 1451056689506
},
{
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 : ' ... ',
updatedDate : 1451056689234
},
{ '': '' },
{ '': '' }
]
}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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP GET REQUEST
$ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&lobid={lob_id}&object=guides&offset=5&expires=1524066580844&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 : '',
updatedDate : 1444856689506
},
{
object : 'guide',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'I need help for resolving Internet accessibility issue',
match_fragment : '',
updatedDate : 1444856689729
},
{ '': '' },
{ '': '' }
]
}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 the 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 the 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 the 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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
did: (optional) When redirecting from one guide to another, this is the transcriptID of the guide that is redirecting to another guide. Passing this "Parent Incident Id" ensures that all placeholder values are handed over from the parent incident to the child incident.
rid: (optional) The Reference Id, typically your CRM or Service Desk incident Id. Pass rid when session = "initial".
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=1524066580844&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.
=================================================
Example guidance family with command auto-traversal
Refer Get Command Auto Traversal to learn how to auto-traverse with a command's return value
=================================================
{
object : 'guidance_family',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Place T-Shirt Order',
body : '
Place an order for {{ph:t-shirt-clor}} t-shirt or {ph:t-shirt-size}} size .
',
inquiry : 'Was the order placed?',
notes : '',
commandInternalName : 'place-order',
commandParameters : {
object : 'list',
count : 2,
data : [
{
name : 't-shirt-color',
value : 'Blue'
},
{
name : 't-shirt-size',
value : 'Small'
}
]
},
placeholders : {
object : 'list',
count : 2,
data : [ '{{ph:t-shirt-color}}', '{{ph:t-shirt-size}}' ]
},
placeholderValues : {
object : 'list',
count : 2,
data : [
{
name : 't-shirt-color',
value : 'Blue'
},
{
name : 't-shirt-size',
value : 'Small'
}
]
},
user_responses : {
object : 'list',
count : 2,
data : [
{
object : 'user_response',
id : 'a8d6f340-9d72-11e5-850c-bc764e10d166',
body : 'Order succeeded',
conditionGrouping : 'any',
conditions : {
object : 'list',
count : 2,
data : [
{
operator : 'equal-to',
operand : 'ordered'
},
{
operator : 'equal-to',
operand : 'ordered-with-discount'
}
]
},
placeholderValues : {
object : 'list',
count : 1,
data : [
{
name : 'order-status',
value : 'ordered'
}
]
},
updatedDate : 1452856689506
},
{
object : 'user_response',
id : 'a8d6f340-9d72-11e5-850c-bc764e10d166',
body : 'Order failed',
conditionGrouping : 'any',
conditions : {
object : 'list',
count : 2,
data : [
{
operator : 'equal-to',
operand : 'ordered-failed'
},
{
operator : 'equal-to',
operand : 'discount-not-applicable'
}
]
},
placeholderValues : {
object : 'list',
count : 1,
data : [
{
name : 'order-status',
value : 'failed'
}
]
},
updatedDate : 1452856689506
}
]
},
transcriptId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
transcriptUrl : 'https://subdomain.yonyx.com/y/incident/?did=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
session : 'NBwSd2ytk2X%2FbjqA5h2BXsKuHJThzDsVe%2F%2BiLg26kfAe8Wwa6MrOffPGedBSad2l',
rootId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
form : {
object : 'list',
count : 3,
data : [
{
name : 'buyer-name',
type : 'String',
value : ''
},
{
name : 'claim-status',
type : 'String',
value : ''
},
{
name : 'claim-no',
type : 'String',
value : ''
}
]
},
formMarkup :
'<form class="yonyx-form" name="data-capture-3" action="#"><fieldset ><div class="form-group"><label>Name</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="input" name="buyer-name" maxlength="30" required="required" value="John Doe" ></div><div class="form-group"><label>Date</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="date" name="claim-status" min="2020-01-05" max="2020-01-10" required="required" value="2020-01-07" ></div><div class="form-group"><label>Number</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="number" name="claim-no" maxlength="30" min="5" max="15" required="required" value="7" ></div></fieldset></form>',
score : 0,
commandType : 'yonyx-command',
placeholderAutoTraverse : false,
placeholderAutoTraversalId : '',
redirectId : '',
redirectType : '',
returnToParent : false,
updatedDate : 1452856689506
}
=================================================
Example guidance family with placeholder auto-traversal
=================================================
{
object : 'guidance_family',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'T-Shirt Preference',
body : '
You have chosen {{ph:t-shirt-clor}} t-shirt of {ph:t-shirt-size}} size .
',
inquiry : 'Do you want to proceed?',
notes : '',
commandInternalName : '',
commandParameters : {
object : 'list',
count : 0,
data : []
},
placeholders : {
object : 'list',
count : 2,
data : [ '{{ph:t-shirt-color}}', '{{ph:t-shirt-size}}' ]
},
placeholderValues : {
object : 'list',
count : 2,
data : [
{
name : 't-shirt-color',
value : 'Blue'
},
{
name : 't-shirt-size',
value : 'Small'
}
]
},
user_responses : {
object : 'list',
count : 2,
data : [
{
object : 'user_response',
id : 'a8d6f340-9d72-11e5-850c-bc764e10d166',
body : 'Modern',
conditionGrouping : 'all',
conditions : {
object : 'list',
count : 0,
data : []
},
placeholderConditionGrouping : 'all',
placeholderConditions : {
object : 'list',
count : 2,
data : [
{
leftOperand : 't-shirt-size',
operator : 'equal-to',
rightOperand : 'Small'
},
{
leftOperand : 't-shirt-color',
operator : 'equal-to',
rightOperand : 'Blue'
}
]
},
placeholderValues : {
object : 'list',
count : 1,
data : [
{
name : 'style-code',
value : 'modern'
}
]
},
updatedDate : 1452856689300
},
{
object : 'user_response',
id : 'a8d6f340-9d72-11e5-850c-bc764e10d166',
body : 'Traditional',
conditionGrouping : 'all',
conditions : {
object : 'list',
count : 0,
data : []
},
placeholderConditionGrouping : 'all',
placeholderConditions : {
object : 'list',
count : 2,
data : [
{
leftOperand : 't-shirt-size',
operator : 'equal-to',
rightOperand : 'Large'
},
{
leftOperand : 't-shirt-color',
operator : 'equal-to',
rightOperand : 'Red'
}
]
},
placeholderValues : {
object : 'list',
count : 1,
data : [
{
name : 'style-code',
value : 'traditional'
}
]
},
updatedDate : 1452856689300
}
]
},
transcriptId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
transcriptUrl : 'https://subdomain.yonyx.com/y/incident/?did=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
session : 'NBwSd2ytk2X%2FbjqA5h2BXsKuHJThzDsVe%2F%2BiLg26kfAe8Wwa6MrOffPGedBSad2l',
rootId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
form : {
object : 'list',
count : 3,
data : [
{
name : 'buyer-name',
type : 'String',
value : ''
},
{
name : 'claim-status',
type : 'String',
value : ''
},
{
name : 'claim-no',
type : 'String',
value : ''
}
]
},
formMarkup :
'<form class="yonyx-form" name="data-capture-3" action="#"><fieldset ><div class="form-group"><label>Name</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="input" name="buyer-name" maxlength="30" required="required" value="John Doe" ></div><div class="form-group"><label>Date</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="date" name="claim-status" min="2020-01-05" max="2020-01-10" required="required" value="2020-01-07" ></div><div class="form-group"><label>Number</label> <span class="glyphicon glyphicon-star-empty emphasize"></span><input class="form-control fld " type="number" name="claim-no" maxlength="30" min="5" max="15" required="required" value="7" ></div></fieldset></form>',
score : 0,
commandType : 'yonyx-command',
placeholderAutoTraverse : true,
placeholderAutoTraversalId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
redirectId : '',
redirectType : '',
returnToParent : false,
updatedDate : 1452856689300
}
=================================================
INSTRUCTIONS ON HANDLING HANDOFF/RETURN AND PLACEHOLDER AUTO-TRAVERSAL
=================================================
=================================================
INITIAL REQUEST
session=initial
id=Guide Id (later becomes parent Guide)
Don't set did
=================================================
Complete URL:
https://developer.yonyx.com/y/apiv2/
?expires=1653030103208
&id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&lang=en
&object=guidance_family
&session=initial
&type=int
&user=some-user@your-domain.com
&signature=mu0iA1lH8V....=
=================================================
SUBSEQUENT REQUEST - REGULAR
session=session value from previous reponse
id=User Response ID
Don't set did
=================================================
Complete URL:
https://developer.yonyx.com/y/apiv2/
?expires=1653030160777
&id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&lang=en
&object=guidance_family
&session=EDPn4HQp9C...
&type=int
&user=some-user@your-domain.com
&signature=GCN0oPKpBg...=
=================================================
HANDLING HANDOFF (REDIRECT) / RETURN
=================================================
----------------------------------------------
SUBSEQUENT REQUEST - REDIRECT TO CHILD GUIDE
----------------------------------------------
If previous Response contains non-empty redirectId and redirectType:
redirectId: "590d12f0-6855-11eb-a673-76421da31ef2"
redirectType: "guidance_family"
returnToParent: false
Set these parameters in the next request:
session=initial
id=Value of redirectId from previous response
did=Value of transcriptId from previous reponse
----------------------------------------------
Complete URL:
https://developer.yonyx.com/y/apiv2/
?did=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&expires=1653030257702
&id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&lang=en
&object=guidance_family
&session=initial
&type=int
&user=some-user@your-domain.com
&signature=LNePbMpVk8...=
----------------------------------------------
After a few subsequent requests in child guide
----------------------------------------------
https://developer.yonyx.com/y/apiv2/...
https://developer.yonyx.com/y/apiv2/...
https://developer.yonyx.com/y/apiv2/...
...
...
...
----------------------------------------------
SUBSEQUENT REQUEST - RETURN TO THE PARENT GUIDE
----------------------------------------------
If previous Response contains returnToParent=true, then redirectId and session carrry Parent Guide information :
redirectId: "4a9276a0-ccf1-11ec-a090-5254004d38b5" - Guidance Step Id from the Parent Incident (step that initiated handoff)
redirectType: "guidance_family"
returnToParent: true
session: "uEITnDqNg2..." - Parent Guide's session
Set these parameters in the next request:
session=Value of session from previous reponse
id=Value of redirectId from previous response
Don't set did
----------------------------------------------
Complete URL:
https://developer.yonyx.com/y/apiv2/
?expires=1653030440328
&id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&lang=en
&object=guidance_family
&session=uEITnDqNg2...
&type=int
&user=some-user@your-domain.com
&signature=qwmx9oJd/6...=
----------------------------------------------
VALID REDIRECT TYPES
----------------------------------------------
lob, catalog, guidance_family, and url
=================================================
HANDLING PLACEHOLDER AUTO-TRAVERSAL
=================================================
If previous Response contains placeholderAutoTraverse=true:
placeholderAutoTraverse true
placeholderAutoTraversalId "2b948a70-ccfd-11ec-a090-5254004d38b5"
Set these parameters in the next request:
session=Value of session from previous response
id=Value of placeholderAutoTraversalId from previous response
----------------------------------------------
Complete URL:
https://developer.yonyx.com/y/apiv2/
?did=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&expires=1653030257702
&id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
&lang=en
&object=guidance_family
&session=uOPTnDqNg2...
&type=int
&user=some-user@your-domain.com
&signature=LNePbMpVk8...=Create a 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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP POST REQUEST
$ curl http://developer.yonyx.com:8888/apiv2/ --data "expires=1524066580844&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 a 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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP POST REQUEST
$ curl http://developer.yonyx.com:8888/apiv2/ --data "expires=1524066580844&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 a 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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP POST REQUEST
$ curl https://developer.yonyx.com/y/apiv2/ --data "expires=1524066580844&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 a 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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP POST REQUEST
$ curl https://developer.yonyx.com/y/apiv2/ --data "expires=1524066580844&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.'
}Get Command Auto Traversal
In any given step, determine which User Response qualifies for Command auto-traversal by providing the Command’s return value.
HTTP METHOD: GET
PARAMETERS
key: (Required) Your API key.
object: get_command_auto_traversal (Required) The object type to be retrieved.
session: (Required) Get this value from the response of the previous "guidance_family" method call.
commandReturnValue: (Required) Return value of the Command. A command is typically code that you run and the result of that code is commandReturnValue.
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/?expires=1524066580844&commandReturnValue={return-value-of-your-command}&key={your-api-key}&object=get_command_auto_traversal&session={session-from-guidance-family-response}&signature={signature}"
EXAMPLE RESPONSE WITH A POSITIVE MATCH
{
commandAutoTraverse : true,
commandAutoTraversalId : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
message : ''
}
EXAMPLE RESPONSE WITH NO MATCH
{
commandAutoTraverse : false,
commandAutoTraversalId : ''
message : 'The Command return value you provided did not match any User Response conditions for auto-traversal.'
}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=1524066580844&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 : 'T-Shirt color',
question : 'What is your favorite color?',
duration : '00:00:06'
},
{
object : 'transcript_step',
type : 'user_response',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Blue.',
placeholderValues : {
object : 'list',
count : 2,
data : [
{
name : 't-shirt-color',
value : 'Blue'
}
]
}
},
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'T-Shirt size',
question : 'What is your T-Shirt size?',
duration : '00:00:55'
},
{
object : 'transcript_step',
type : 'user_response',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Small.',
placeholderValues : {
object : 'list',
count : 2,
data : [
{
name : 't-shirt-size',
value : 'Small'
}
]
}
},
{
object : 'transcript_step',
type : 'guidance_step',
id : 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
title : 'Place Order',
question : 'Do you wish to proceed with placing the order?',
duration : '00:01:02'
}
]
},
summary :
'\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:06] T-Shirt color\nQ: What is your favorite color?\n--------------------------------------------\nU: Blue.\n--------------------------------------------\nT: [00:00:55] T-Shirt size\nQ: What is your T-Shirt size?\n--------------------------------------------\nU: Small.\n--------------------------------------------\nT: [00:01:02] Place Order\nQ: Do you wish to proceed with placing the order?\n--------------------------------------------',
ownerName : 'user1',
ownerEmail : 'user1@company.com',
startTime : 1452855652483,
endTime : 1452856659750,
done : true,
doneDate : 1452856650050,
score : 0,
parentId : '',
groupId : '',
formattedStartTime : '2021-03-02 02:14:26',
formattedEndTime : '2021-03-02 02:14:56'
}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.
offset: (optional) An offset into the list of returned items. The API will return the number of items starting at the offset.
Offset accepts 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
EXAMPLE HTTP GET REQUEST
$ curl https://developer.yonyx.com/y/apiv2/?key={your-api-key}&object=transcripts_by_refid&rid={reference-id}&expires=1524066580844&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,
next_offset : 'c6bee1b0-bb59-11e5-87df-46894e2acb2b',
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,
done : true,
doneDate : 1452856650050,
score : 0,
parentId : '',
groupId : '',
formattedStartTime : '2021-03-02 02:14:26',
formattedEndTime : '2021-03-02 02:14:56'
},
{
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,
done : true,
doneDate : 1452856650050,
score : 0,
parentId : '',
groupId : '',
formattedStartTime : '2021-03-02 01:11:06',
formattedEndTime : '2021-03-02 01:15:00'
}
]
}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 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=1524066580844&signature={signature}
EXAMPLE RESPONSE
Returns a success message.
{
message : 'Reference ID associated with Transcript successfully.'
}Associate Reference Id with multiple Transcripts (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_transcripts (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=1524066580844&signature={signature}
EXAMPLE RESPONSE
Returns a dictionary with a data property that contains an array of Transcript objects. If no Transcript object is available, the resulting array will be empty. This request should never return an error.
{
object : 'list',
count : 4,
data : [
{ object : 'transcript', ...},
{ object : 'transcript', ...},
{...},
{...}
]
}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. The transcript Ids are returned sorted by creation date, with the most recently created Transcript appearing first.
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.
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.
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
endDate: (Required) End of the date range.
Let's say you want to retrieve Transcript Ids for the date range Jan-01-2020 to Jan-05-2020.
offset will be Jan-05-2020 in UTC milliseconds format for the initial request. Think of offset as Start Date.
endDate will be Jan-01-2020 in UTC milliseconds format.
Remember, this method returns data in reverse chronological order. This is the reason Jan-05-2020 has become start date and Jan-01-2020 end date.
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=1578182400000&endDate=1577836800000&expires=1524066580844&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&endDate=1577836800000&expires=1524066580844&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',
'6c38a2f0-xx50-xxxx-xxxx-0800xxxxxxxx',
'3f8b9580-xx3e-xxxx-xxxx-0800xxxxxxxx',
'0d6dd770-xx3e-xxxx-xxxx-0800xxxxxxxx',
'0f750e90-xx3d-xxxx-xxxx-0800xxxxxxxx',
{...},
{...},
{...}
]
}List all Transcripts of a line of business
Returns a list of Transcripts since the offset. A max of 10 transcripts will be returned starting at the offset 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.
lobid: (Required) Line of business ID.
object: transcripts (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.
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 Transcripts, 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
endDate: (Required) End of the date range.
Let's say you want to retrieve Transcripts for the date range Jan-01-2020 to Jan-05-2020.
offset will be Jan-05-2020 in UTC milliseconds format for the initial request. Think of offset as Start Date.
endDate will be Jan-01-2020 in UTC milliseconds format.
Remember, this method returns data in reverse chronological order. This is the reason Jan-05-2020 has become start date and Jan-01-2020 end date.
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=transcripts&offset=1578182400000&endDate=1577836800000&expires=1524066580844&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=transcripts&offset=99988830-047c-11e4-9638-bc764e10f0e8&endDate=1577836800000&expires=1524066580844&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 subsequent 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 Transcripts, starting at provided offset. If no Transcripts are available, the resulting array will be empty. This request should never return an error.
{
object : 'list',
count : 10,
next_offset : 'c6bee1b0-bb59-11e5-87df-46894e2acb2b',
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,
done : true,
doneDate : 1452856650050,
score : 0,
parentId : '',
groupId : '',
formattedStartTime : '2021-03-02 02:14:26',
formattedEndTime : '2021-03-02 02:14:56'
},
{
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,
done : true,
doneDate : 1452856650050,
score : 0,
parentId : '',
groupId : '',
formattedStartTime : '2021-03-01 01:00:00',
formattedEndTime : '2021-03-01 01:14:56'
},
{...},
{...},
{...}
]
}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=1524066580844&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=1524066580844&signature={signature}
EXAMPLE RESPONSE
Returns a success message.
{
message : 'User disabled successfully.'
}Set Incident Placeholder Values
Sets/Updates the current Incident with provided Placeholder Values.
HTTP METHOD: POST
PARAMETERS
key: (Required) Your API key.
object: set_incident_placeholder_values (Required) The method name.
placeholderValues: (Required) JSON Array of name-value objects. Eg.: [{"name":"name","value":"John Doe"},{"name":"order-status","value":"Returned"}].
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.
lang: (optional) The language code Eg.: en or en-US or es or es-ES or es-US
EXAMPLE HTTP POST REQUEST
$ curl https://developer.yonyx.com/y/apiv2/ --data 'expires=1524066580844&key={your-api-key}&object=set_incident_placeholder_values&placeholderValues=[{"name":"name","value":"John Doe"},{"name":"order-status","value":"Returned"}]&session=8NRG3vhMfyiwTRr7%2B2XwDoHTB2qM%2BNsMEbIteFbLJV1v11x1XINDxqxEO8GadGfYZwQNU7sYcVWL39LC1c6V2OQ74%2FPsZV%2BlZ8zQOV6cUHwUZxxIQBoqWtqJow88W3hbAQeLQrHnClS1vIoM12BP4a9ik3%2BkfOusIHRCZQCbzJM&signature=CJ%2B5VLw26B5o%2BLqS6AKpWGUcWmHts1N51VNdfAR2VbA%3D'
EXAMPLE RESPONSE
Returns a success message.
{
message : 'Set incident placeholder values succeeded.'
}Set Form Values
This method does the following: 1. Validates the form values. Returns error message if field validation fails. 2. Updates the current incident with provided Form values as Placeholder values.
HTTP METHOD: POST
PARAMETERS
key: (Required) Your API key.
object: set_form_values (Required) The method name.
formValues: (Required) JSON Array of name-value objects. Eg.: [{"name":"buyer-name","value":"John Doe"},{"name":"user-email","value":"user@email.com"},{"name":"purchase-date","value":"2020-01-17"},{"name":"purchase-time","value":"10:00"},{"name":"order-status","value":"Returned"}].
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=1524066580844&formValues=[{"name":"buyer-name","value":"John Doe"},{"name":"user-email","value":"user@email.com"},{"name":"purchase-date","value":"2020-01-17"},{"name":"purchase-time","value":"10:00"},{"name":"order-status","value":"Returned"}]&key={your-api-key}&object=set_form_values&session=fKYcd2ZV0pBg%2FQacAqTAWSjybRPDvrE2%2F75CAzdTvQvN0SMBQu6rgu9SyXgS%2FqIb747LfU49Q%2Bm00TpmTJtuYoHvyLzkSsZk1ee8d1kcsUnoWxVg%2FC%2FSU9wkwXTzoDqOAQeLQrHnClS1vIoM12BP4a9ik3%2BkfOusIHRCZQCbzJM&signature=5t3sO%2FIE8ibY40ogyY9P2dp7TGsMBD9Qxrv3keUjEkM%3D'
EXAMPLE RESPONSE
Returns a success message.
{
message : 'Set form values succeeded.'
}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.