Register a New Client
The function Register_Client_Json allows you to register a new client record into Hyper's Clients DB.This function is safe to use, it got input Quality Tests and Work procedures in case the client is already registered in the DB.
More so, Validity tests are done and Error Code returns accordingly. Read more about the returned Error Codes 25-29 in the "API Error Codes List" page.
Function input
{
"LastName":"Osbourne",
"FirstName":"Ozzy",
"1stPhone":"12134000976",
"Email":"Ozzy@company1.com",
"StreetAddress":"20 Shamballa rd",
"City":"Santa Monica",
"Region":"Los Angeles",
"Country":"USA"
}
"LastName":"Osbourne",
"FirstName":"Ozzy",
"1stPhone":"12134000976",
"Email":"Ozzy@company1.com",
"StreetAddress":"20 Shamballa rd",
"City":"Santa Monica",
"Region":"Los Angeles",
"Country":"USA"
}
This input is an example for a set of fields that where determined in Hyper's Client Fields Matrix module.
as shown in the picture below. It is likely that each Hyper implementation would be different than explained hereby.
Get Help about Function Input
IF you call this function without posting data, the response will be a fields list that you can post, according to the Matrix (screen shot above).Here is an example of an Help response:
{
"Fields List (Help)":[
{
"Name":"LastName",
"Type":"Name",
"Length":"50",
"Mandatory":"Group 0"
},
{
"Name":"FirstName",
"Type":"Name",
"Length":"40",
"Mandatory":"Group 0"
},
{
"Name":"Email",
"Type":"String",
"Length":"100",
"Mandatory":"Group 0"
},
{
"Name":"1stPhone",
"Type":"Phone",
"Length":"20",
"Mandatory":"Group 0"
},
{
"Name":"StreetAddress",
"Type":"String",
"Length":"80"
},
{
"Name":"City",
"Type":"String",
"Length":"40"
},
{
"Name":"Region",
"Type":"String",
"Length":"40"
},
{
"Name":"Country",
"Type":"String",
"Length":"40"
},
{
"Name":"ZipCode",
"Type":"String",
"Length":"15"
},
{
"Name":"Birthday",
"Type":"Date"
},
{
"Name":"Gender",
"Type":"Status"
},
{
"Name":"IdNumber",
"Type":"Serial",
"Length":"20"
},
{
"Name":"IdDocType",
"Type":"Status"
},
{
"Name":"IdDocValidUntil",
"Type":"Month"
},
{
"Name":"CountryIssuingId",
"Type":"String",
"Length":"40"
}
]
}
"Fields List (Help)":[
{
"Name":"LastName",
"Type":"Name",
"Length":"50",
"Mandatory":"Group 0"
},
{
"Name":"FirstName",
"Type":"Name",
"Length":"40",
"Mandatory":"Group 0"
},
{
"Name":"Email",
"Type":"String",
"Length":"100",
"Mandatory":"Group 0"
},
{
"Name":"1stPhone",
"Type":"Phone",
"Length":"20",
"Mandatory":"Group 0"
},
{
"Name":"StreetAddress",
"Type":"String",
"Length":"80"
},
{
"Name":"City",
"Type":"String",
"Length":"40"
},
{
"Name":"Region",
"Type":"String",
"Length":"40"
},
{
"Name":"Country",
"Type":"String",
"Length":"40"
},
{
"Name":"ZipCode",
"Type":"String",
"Length":"15"
},
{
"Name":"Birthday",
"Type":"Date"
},
{
"Name":"Gender",
"Type":"Status"
},
{
"Name":"IdNumber",
"Type":"Serial",
"Length":"20"
},
{
"Name":"IdDocType",
"Type":"Status"
},
{
"Name":"IdDocValidUntil",
"Type":"Month"
},
{
"Name":"CountryIssuingId",
"Type":"String",
"Length":"40"
}
]
}
Function Output
After successful execution the function will return code 0, otherwise it will return an Error code + Message.Here is an Example:
{
"ResponseCode":0,
"ResponseMsgEng":"New client record was created (no dups found).",
"FunctionName":"Register_Client_Json",
"ClientNumber":500000,
"API_Password":"eBt5yJD3uchz"
}
"ResponseCode":0,
"ResponseMsgEng":"New client record was created (no dups found).",
"FunctionName":"Register_Client_Json",
"ClientNumber":500000,
"API_Password":"eBt5yJD3uchz"
}
Field | Description |
---|---|
ResponseCode | Zero value for success. |
ResponseMsgEng |
This field contain a hint for you about the duplicity checks done during the execution.
|
ClientNumber | This is the entity account number in Hyper's DB. Keep this field in your app DB for further access. |
API_Password | Keep this field in your app DB for further access, every entity has it's own password. |
Description of Operations
The following actions taking place when posting data to this function. The process will stop on a failure, returning a message in json format.-
Check that all mandatory fields were filled.
Push Excess Input Fields (not included in the input fields list) into [hyp_Sale Opportunity Web Input] table. - Check that String (fields) values are in the Acceptable Languages (like the whole CRM configuration).
- If an Email field is included, then Check that address is valid. Including DNS MX test for private domains.
- If a Phone Number field is included, then Check that contain only digits and has a length of 9-13 chars.
-
If a Birthday field is included, then Check that client's age is above the setting [Website Accept Client Age above # years].
-
If a Password field is included, then it must be at least 8 characters long and contain 2 digits and 3 letters.
When using ONLY English characters, it is mandatory to combine uppercase and lowercase letters. -
If an ID Number field is included, then Run a logical test on it when possible (Luhn Algorithm for example).
The test depends on the client field[Country Issuing ID]if available, otherwise it checks the[Country]field.
When both of the fields are empty, then the website assumes that the client is from the same country where the organization / branch operates. -
Duplicity Check
Searching for existing clients according to: Email Address, Phone Number & ID Number.
When duplicity is found, a second check is done for the client's "Handling Status".
-
IF the status is < 4 (0-3) then the first record found will be MERGED with the new registration data.
Any field that cannot merge, will be pushed into [hyp_Sale Opportunity Web Input] table. No data lost. - IF the status is > 3 (4-6) then All data being pushed into [hyp_Sale Opportunity Web Input] table.
To skip client duplicity checks and commit a new client registration, add to the function input:
"CreateNewClient":"1" parameter, this will cause the creation of a NEW client anyway.
-
IF the status is < 4 (0-3) then the first record found will be MERGED with the new registration data.
-
Create a New Client Record
-
Complete some hyp_Clients table fields:
[Docs & Forms Language]to current session Language.
[Use Currency by Default]to default Bookkeeping Currency.
Set the field[Lead Status]to value 1 (Newly Created), and[Last Lead Input]to NOW UTC. -
Decide which Agency to assign this client, Priorities are:
-
IF one of the fields [Default Sales Agent]or[Default Relationship Manager]were posted, then assign to that Agent's Agency !
-
IF [Agency]was posted (not null), then assign to it.
- Default field value, if was written in the Matrix.
- Use default agency by this API instance (every Domain is assigned to a 'Hyper User' or 'Server side Agency').
-
IF one of the fields
-
Set the field [Created on]to Current local time, according to the Agency's timezone.
-
IF checkbox / json field "AcceptCommercialInfoCheckbox" OR "AcceptCommercialInfotoCellphone" posted as true/1;
Then set[Accept Commercial Info to Cell phone]to Current local time, and[Question to use cell phone]to 1 (Website Form). -
IF checkbox / json field "AcceptCommercialInfoCheckbox" OR "AcceptCommercialInfotoEmail" posted as true/1;
Then set[Accept Commercial Info to Email]to Current local time, and[Question to use Email]to 1 (Website Form). -
Setup hyp_Clients Website Ext. Record fields:
-
[Last Registration Step]and[Registration Complete Until Step]= 1 (page 1).
-
[First Reg. Page Date]= Today.[Account Status]is set to 1 (Pending Approval).
-
[Portal Password]and[API Password]are generated.
IF the Matrix includes the field "Password" under "hyp_Clients" table, then it will be copied here. -
IF checkbox / json field "AgreetoTermsCheckbox" posted as true/1; Then [Agree to Terms Checkbox]= Today.
-
This is it, Now saving to Database. Next Step is #12 in this list. -
Complete some hyp_Clients table fields:
-
Merging data with Client LEAD (status 0-3)
-
Copy each new posted field to original tables [hyp_Clients], [hyp_Clients Record Extension], when the Target field is EMPTY !
Otherwise, push that posted field into [hyp_Sale Opportunity Web Input] table. -
Work on hyp_Clients table fields:
-
Change [Docs & Forms Language]to current session Language.
-
IF empty then set [Use Currency by Default]to default Bookkeeping Currency.
-
IF [Handling Status] = 3(not interested) then change it to 0 (new).
-
Set the field [Lead Status]to value 2 (HOT Lead) or 3 (Interested Again) according to current client status.
-
Change
- Complete empty fields in hyp_Clients Website Ext. Record table, To meet the standards from Section 9.F.
-
Copy each new posted field to original tables
-
Handling data when Client is Confirmed / Active (status 4-6)
Push all posted fields into [hyp_Sale Opportunity Web Input] table.
Set the field[hyp_Clients.Lead Status]to value 3 (Interested Again). -
A new Sale Opportunity is created at this point. With link to Client Number (new / exist) and Empty fields completion from the Client record (like phone/email/sales agent etc).
This step is running anyway - even if the previous step (client create / update) has failed (Database error).