Strategic Software Consultant

I'm the partner of choice for many of the world's leading enterprises. I help businesses elevate their value through solution discovery, software development, design, QA, and consultancy services. As your Strategic Software Consultant, I work across many technology products and delivery teams. The scope of technology is broad, and it is my job to understand how your technology applications holistically support and connect to create a sustainable technology ecosystem. The ecosystem of technologies may span to 3rd party applications, in-house developed solutions, business intelligence, data integrations, and of course, SaaS applications.

Oracle Certified Specialist
B2C Service REST API Oracle B2C Service

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.

AuthorizationBasic
Content-Typeapplication/json
OSvC-CREST-Application-ContextQuery 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

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);

Leave a comment

Your email address will not be published. Required fields are marked *