Proposal for Client and Contact Creation via REST API

PROPOSAL SUMMARY 

This proposal covers the scope of the integration to create client and contact records in NetSuite via REST API. 

REQUIREMENT 

Integration between the NetSuite & external website to create client and contact records in NetSuite when a new client signs up on the website. 

When a user registers with existing CQC Number then create a contact record against the client. 

If a new user registers with new CQC number then create a new client and contact record in NetSuite. 

When a user register with new CQC Number and existing client name then create a child client and contact record.  

OUR SOLUTION 

Three REST let scripts will be implemented in the NetSuite for creating APIs for NetSuite to accept the POST request sent to NetSuite to create client and contact records on a real-time basis. After creating the client or Contact records we will trigger the Map Reduce script (Customer Transmission Map Reduce). 

CASE 1: CONTACT CREATION ENDPOINT 

 
When the REST API gets the data, it will check to see whether the CQC number exists in NetSuite. If it is found that it already exists for a client, create a contact record for this matching client (using the CQC number). If there are multiple clients with the same CQC number, we will use the most recently updated client to create the contact. 

CASE 2: CLIENT AND CONTACT CREATION ENDPOINT 

When the Contact and client creation REST API gets data from the website, it will check whether the CQC number exists in NetSuite. If the CQC Number is not existing in the NetSuite then check that the client exists using the client’s name.  If the client is also discovered to be non-existent, create a parent client record. Then create a contact record for this client. 

CASE 3: CHILD CLIENT AND CONTACT CREATION ENDPOINT 

Child client and contact creation REST API gets the data from website, and the CQC number is not discovered and the corresponding client name is existing in NetSuite with the category “Group head office”, then create a child client and contact record is created against the newly created client. 

CLIENT CREATION FIELDS 

Fields on API Request Body 

JSON Request Field NetSuite Field Internal ID Description/Default Values 
companyName Company name   companyname Mandatory field 
customerType Customer Type custentity_customertype Mandatory field  
email Email email Mandatory field 
category  Category category Group Head Office 
cqcNumber Authority ID  Mandatory filed 
addressee Addressee addressee Same as company name 
address1 Address 1 addr1   
city City city   
country Country country   
postCode Zip zip   
tier Tier territory  

Default Field values 

NetSuite Field Internal ID Description/Default Values 
Primary Subsidiary subsidiary Blueleaf Limited 
Type isperson  Company 
Location custentity_custlocation Southwater Depot 
Default Shipping Address defaultshipping True 
Default Billing address defaultbilling True 
Shipping Method shippingitem Nextday (Standard) 
Tier territory Mandatory field 
Account Type custentity_region Sales 
Visit Frequency Per Year custentity_supportlevel 0 
Group Account manager custentity_groupaccountmanager E368 Service & Support Team 
Internal Account manager custentity_internalaccountmanager E368 Service & Support Team 
Regional Account Manager custentity_internalaccountmanagerstatus E368 Service & Support Team 
CRM Account custentity_client_crm_account Yes 
Lead Source leadsource Ecommerce 
Terms terms Due on receipt/Card 
Primary Currency currency GBP 
Invoice Frequency custentity_invoicefrequency Daily 
Statement Requirement custentity_statement_not_required Individual Statement required 
Invoice Format custentity_invoiceformat GCL Invoice 
Cash Sale Format custentity_cashsaleformat GCL Cash Sale 
Sales Order Format custentity_salesorderformat GCL Sales Order 
Statement Template custentity_statementtemplate GCL Statement 

CONTACT CREATION FIELDS 

Fields on API Request Body 

JSON Request Field NetSuite Field Internal ID Description/Default values 
contactName Contact entityid   Mandatory field 
email Email email Mandatory field 
PhoneNumber Main Phone phone Mandatory field 
jobTitle Job Title custentity3 Mandatory field  
Role Role custentity2 Mandatory field  
cqcNumber Authority ID  Mandatory field  
client_internalid Company company Company internal id 

Default Field values 

NetSuite Field Internal ID Description/Default values 
Subsidiary subsidiary Blueleaf Limited 

SAMPLE JSON REQUEST AND RESPONSE 

JSON Response Field Description 
statusCode Response status as Success or Failure   
internalid The internal id of the created client or contact record 
entityid The entity id of the created client or contact record 
Error  NetSuite error or standard message if the statusCode is failure 

Case 1 Contact Creation 

Sample Request 

{ 

      “cqcNumber”:”CQC12345”, 
     “contactName “: “TEST TEST”, 
     “role”: “Primary Contact”, 
     “email”: “test@abc.com“ 
     “jobTitle”: “Other” 
     “phoneNumber”: “789456455” 
} 

Sample Response 

{ 
     “statusCode”: “SUCCESS”, 
     “internalid”: “45612 “, 
      “entityid”: “1595067 “, 
} 

Case 2 Client and Contact Creation  

Sample Request for Client Creation 

 { 

     “cqcNumber”:”CQC1234”, 
     “companyName”: “TEST Customer”, 
     “customerType”: “Business”, 
     “email”: “test@abc.com“, 
     “address”: 
             { 
                 “address1”: “test address”, 
                 “city”: “test city”, 
                 “country”: “GB”, 
                 “postCode”: “456789”, 
             }, 
         “tier”: “Tier 1” 
} 

Sample Response of Client Creation 

{ 
     “statusCode”: “SUCCESS”, 
    “internalid”: “123456 “, 
     “entityid”: “1595067 “, 
 
} 

CONTACT CREATION 

Sample Request for Contact Creation 

 
{ 

      “cqcNumber”:”CQC123499”, 
     “client_internalid”:” 123456”, 
     “contactName “: “TEST TEST”, 
     “role”: ” Primary Contact “, 
     “email”: “test@abc.com“ 
     “jobTitle”: “Other” 
     “phoneNumber”: “789456455” 
} 

Sample Response for Contact Creation 

{ 
     “statusCode”: “SUCCESS”, 
     “contact_internalid”: “45612 “, 
    “entityid”: “1595347 “, 

 
} 

Case 3 Child Client and Contact Creation 

Sample Request for Child Client Creation 

{ 

     “cqcNumber”:”CQC123495”, 
     “companyName”: “TEST Customer”, 
    “category”: “Group Head Office”, 
    “customerType”: “Charity”, 
     “email”: “test@abc.com“, 
     “address”: 
             { 
                 “address1”: “test address”, 
                 “city”: “test city”, 
                 “country”: “GB”, 
                 “postCode”: “456789”, 
             }, 
         “tier”: “Tier 1” 
} 

Sample Response for Child Client Creation 

{ 
     “statusCode”: “SUCCESS”, 
     “internalid”: “12345677 “, 
     “entityid”: “10095067 “, 

 
} 

Sample Request for Contact Creation 

{ 

      “cqcNumber”:”CQC123454”, 
      ” client_internalid “: “12345677 “ 
     “contactName “: “CHILD TEST”, 
     “role”: ” Primary Contact”, 
     “contactEmail”: “test@abc.com“ 
     “jobTitle”: “Other” 
     “phoneNumber”: “789456455” 
} 

Sample Response for Contact Creation 

{ 
     “statusCode”: “SUCCESS”, 
     “internalid”: “4539 “, 
     “entityid”: “9095067 “, 
} 

ERROR RESPONSE 

Sample Response  

{ 
     “statusCode”: “FAILURE”, 
     “error”: “Company Name is mandatory”, 
} 

ERROR HANDELING AND EMAIL NOTIFICATION 

We will be creating a custom record for tracking errors that happen during API requests. It will be used for both APIs customers and contact. 

API SETUP 

 API credentials will be shared to the Application user to send request to NetSuite. The Integration record will be created in the NetSuite with Auth 1.0 credentials. The token will be generated for the customized role. 

Steps in customized role setup:  

  • “External API User” role will be created in the account for the user to Use the API with limited permissions  
  •  Employee records will be created for the external API user.  
  •  Role will be added to the new user  
  •  Token will be generated for the new customised role 

TRIGGER MAP-REDUCE 

We will be triggering the existing Customer Transmission Map Reduce script to send customer or contact information from NetSuite to the website after successful completion of creation of a customer or contact record in NetSuite. 

ASSUMPTIONS 

  • We will only be creating POST request APIs for the creation of Customer and Contact records in NetSuite and we are not updating the already existing records. 
  • No validations are used in the REST API since the REST API gets the validated data from website. 
  • Deletion of the record are out of scope. 
  • We will be creating a custom record for only error handling in NetSuite if the request is failed. If the request is success, we will not be creating any custom record entry. 
  • Inactivating fields and changing field type is out of scope. 
  • Phone Number digits should be greater than 7 digits. 
  • There is no email validation is added. 
  • Request data should be in JSON format. 
  • Only one record will be created for a single request. Blue leaf can initiate separate request per record. 
  • Duplication detection of records out of scope. 
  • We assume the integration to send customer information from NetSuite to the website exist already in website. We just only need to trigger existing map reduce script. 
  • The NetSuite has concurrency limits. Hence if any request is failed then the website should resend the request after some time. 
  • We assume that CQC number is available with every REST API Request. 
  • If we identify multiple clients with the same CQC number during contact creation, then we will use the most recently updated client for contact creation. 
  • The parent client should be the exact match of the company name during the child client creation. 
  • The tier values in JSON should be exactly match with the territory values in NetSuite during the client record is creation. 
  • Country value in the API request JSON body should be ISO country code (Alpha 2). 
  • When a client record is created, category values should exactly match category values in NetSuite. 
  • The customer type values in the JSON data should perfectly match with NetSuite customer type values. 
  • For the contact creation, the job title and role values JSON data should exactly match the corresponding NetSuite job title and role values. 

Leave a comment

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