B2B Service Create Contact & Incident using REST API
B2B Service REST API Base Endpoint URI
https://example.custhelp.com/services/rest/connect/v1.4/
B2B Service REST API Headers
These headers values are required for all requests. ‘OSvC-CREST-Application-Context’ is required and can be any value.
| Authorization | Basic |
| Content-Type | application/json |
| OSvC-CREST-Application-Context | Query Contact |
Query
The email address is the unique identifier in B2B Service. First, query to see if the contact already exists.
SELECT ID FROM Contacts WHERE Emails.Address='contact@craigdaniels.me'
Query Full URI
https://example.custhelp.com/services/rest/connect/v1.4/queryResults/?query=SELECT%20ID%20FROM%20Contacts%20WHERE%20Emails.Address='contact@craigdaniels.me
JavaScript Sample Query Request
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
let primaryContactId = this.responseText.items[0].rows[0][0];
console.log(primaryContactId);
}
});
xhr.open("GET", "https://example.custhelp.com/services/rest/connect/v1.4/queryResults/?query=SELECT%20ID%20FROM%20Contacts%20WHERE%20Emails.Address='contact@craigdaniels.me'");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("OSvC-CREST-Application-Context", "Query Contact");
xhr.setRequestHeader("Authorization", "Basic yourusername:yourpasssword");
xhr.send();
Sample Response
If the contact exists, the response will return the ID in the rows attribute on Line 11. Save this id and skip to section below ‘Create the Incident.’
{
"items": [
{
"tableName": "contacts",
"count": 1,
"columnNames": [
"id"
],
"rows": [
[
"51717"
]
]
}
]
}
If the contact does not exist, the response rows will be empty.
{
"items": [
{
"tableName": "contacts",
"count": 0,
"columnNames": [
"id"
],
"rows": []
}
]
}
Create Contact if response rows were empty
Contact POST URI
https://example.custhelp.com/services/rest/connect/v1.4/contacts
Sample POST Body with contact name, email address, phone number, and custom fields.
{
"name":{
"first":"Craig",
"last":"Daniels"
},
"emails":{
"addressType":{
"id":0
},
"address":"newuser@domain.com"
},
"phones":{
"phoneType":{
"id":1
},
"number":"720-340-1313"
},
"address":{
"city":"Denver",
"street":"110 Main St",
"country":{
"lookupName":"US"
},
"postalCode":"80207",
"stateOrProvince":{
"lookupName":"CO"
}
},
"customFields":{
"c":{
"has_cdl":true,
"driving_preference":{
"lookupName":"Solo Driving"
},
"cdl_type":{
"lookupName":"Class A"
}
}
}
}
JavaScript Sample Contact Create Request
var data = JSON.stringify({
"name": {
"first": "Craig",
"last": "Daniels"
},
"emails": {
"addressType": {
"id": 0
},
"address": "craig.daniels@mastechinfotrellis.com"
},
"phones": {
"phoneType": {
"id": 1
},
"number": "720-340-1313"
},
"address": {
"city": "Denver",
"street": "110 Main St",
"country": {
"lookupName": "US"
},
"postalCode": "80207",
"stateOrProvince": {
"lookupName": "CO"
}
},
"customFields": {
"c": {
"has_cdl": true,
"driving_preference": {
"lookupName": "Solo Driving"
},
"cdl_type": {
"lookupName": "Class A"
}
}
}
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
let primaryContactId = responseText.id;
console.log(primaryContactId);
}
});
xhr.open("POST", "https://example.custhelp.com/services/rest/connect/v1.4/contacts");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("OSvC-CREST-Application-Context", "create contact");
xhr.setRequestHeader("Authorization", "Basic yourusername:yourpassword");
xhr.send(data);
Sample Contact Create Response
The response returns all contact information including the primary key id on Line 2. Save this id for the next step to create an incident for this contact.
{
"id": 51718,
"lookupName": "Craig Daniels",
"createdTime": "2021-12-27T17:51:57.000Z",
"updatedTime": "2021-12-27T17:51:57.000Z",
"address": {
"city": "Denver",
"country": {
"links": [
{
"rel": "self",
"href": "https://example.custhelp.com/services/rest/connect/v1.4/countries/1"
},
{
"rel": "canonical",
"href": "https://example.custhelp.com/services/rest/connect/v1.4/countries/1"
},
{
"rel": "describedby",
"href": "https://example.custhelp.com/services/rest/connect/v1.4/metadata-catalog/countries",
"mediaType": "application/schema+json"
}
]
},
"postalCode": "80207",
"stateOrProvince": {
"id": 7,
"lookupName": "CO"
},
"street": "110 Main St"
},
"customFields": {
"c": {
"cdl_type": {
"id": 96,
"lookupName": "Class A"
},
"driving_preference": {
"id": 14,
"lookupName": "Solo Driving"
},
"has_cdl": true
}
},
"emails": {
"links": [
{
"rel": "self",
"href": "https://example.custhelp.com/services/rest/connect/v1.4/contacts/51718/emails"
},
{
"rel": "full",
"href": "https://example.custhelp.com/services/rest/connect/v1.4/contacts/51718/emails/{email_id}",
"templated": true
}
]
},
"name": {
"first": "Craig",
"last": "Daniels"
},
"phones": {
"links": [
{
"rel": "self",
"href": "https://example.custhelp.com/services/rest/connect/v1.4/contacts/51718/phones"
},
{
"rel": "full",
"href": "https://example.custhelp.com/services/rest/connect/v1.4/contacts/51718/phones/{phone_id}",
"templated": true
}
]
}
}
Create the Incident (Service Request)
Incident POST URI
https://example.custhelp.com/services/rest/connect/v1.4/incidents
Sample POST Request
This request creates the incident for the contact, sets the incident subject and some incident custom fields.
Note: The primaryContact in the payload below is the ID returned from querying or creating the contact above.
{
"primaryContact":{
"id":51718
},
"subject":"Application - Contractor Driver",
"customFields":{
"c":{
"application_source":{
"lookupName":"CDL Job Now"
},
"application_type":{
"lookupName":"Contractor Driver"
},
"truck_type":{
"lookupName":"Straight Truck"
}
}
}
}
JavaScript Sample Request
var data = JSON.stringify({
"primaryContact": {
"id": 51718
},
"subject": "Application - Contractor Driver",
"customFields": {
"c": {
"application_source": {
"lookupName": "CDL Job Now"
},
"application_type": {
"lookupName": "Contractor Driver"
},
"truck_type": {
"lookupName": "Straight Truck"
}
}
}
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if(this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://example.custhelp.com/services/rest/connect/v1.4/incidents");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("OSvC-CREST-Application-Context", "create contact");
xhr.setRequestHeader("Authorization", "Basic yourusername:yourpassword");
xhr.send(data);