Insert/Update CRM customer

To insert or update a customer you need to execute a POST request and all the customer data need to be specified in a JSON object inside the body of the request.

In the JSON need also to be specified the action type you want to execute, so the action attribute is mandatory and it can assume these values:

I → if you want to perform an INSERT

U → if you want to perform an UPDATE

Below a JSON example with the mandatory attributes:

{
  subjectsRecords: [
    {
      subjects: {
        customerCode: "13245",
        system: "DW",
        subjectName: "Alessandro",
        subjectName2: "Gino",
        subjectSurname: "Covris",
        subjectCompanyName: "Sinesy",
        subjectType: "FIDELITY",
        subjectSubtype: "4",
        extSubCompanyName: "",
        subjectDenomination: "",
        lawNature: "",
        address1: "via Pordenone 1",
        address2: "",
        zipCode: "33170",
        municipality: "",
        city: "Pordenone",
        province: "PN",
        region: "FVG",
        state: "",
        country: "IT",
        latitude: "",
        longitude: "",
        language: "",
        currency: "EUR",
        note: "",
        sex: "M",
        birthday: "",
        birthPlace: "",
        countryBirth: "IT",
        fiscalCode: "",
        companyVatCode: "",
        passport: "",
        maritialStatus: "",
        occupation: "",
        title: "",
        origin: "",
        functionCode: "",
        saleChannel: "",
        organizationLevel: "",
        territory: "",
        purchaseInclination: "",
        employeesNumber: 60,
        employeesDate: "",
        attractionLevel: "",
        identificationLevel: "",
        subjectBlockReason: "",
        poBox: "",
        payment: "",
        discount: 0,
        decisionLevel: "",
        isCompany: "F",
        macAddress: "",
        ecommerceLastVisit: "2016-03-24",
        ecommerceLastLogin: "2016-03-24",
        ecommerceGuestRegister: "",
        discountAuthorization: "",
        childNumber: 2,
        foreignPerson: "F",
        maximumValue: 1000,
        countryRegistration: "IT",
        houseNumber: 10,
        Floor: 2,
        appartmentNumber: "",
        entrance: "",
        block: ""
      },
      contacts: [
        {
          contactType: "PHONE",
          value: "1234567890"
        },
        {
          contactType: "EMAIL",
          value: "test.test@test.it"
        }
      ],
      privacy: [
        {
          privacyType: "",
          privacyConsent: "",
          consentDate: "",
          recessDate: ""
        }
      ],
      subjectDestinations: [
        {
          destinationType: "RES",
          address1: "via Tolmiech",
          address2: "",
          zipCode: "33170",
          municipality: "",
          city: "Pordenone",
          province: "PN",
          region: "",
          state: "",
          country: "IT",
          fax: "",
          mobile: "",
          email: "",
          note: "Test note",
          phone: ""
        }
      ],
      mappings: [
        {
          system: "DW",
          externalField: "CUSTOMER_ID",
          externalCode: 12345
        },
        {
          system: "DW",
          externalField: "CUSTOMER_NO",
          externalCode: 67890
        }
      ],
      subjectSources: [
        {
          source: ""
        }
      ],
      commercialDivisions: [
        {
            commercialDivision: "Prodotto"
        }
      ],
      subjectRelations: [
        {
            relationType: "PARTNER",
            system: "DW",
            slaveSubject: "a002p000012xBJaAAM",
            masterSubject: "a00D000000RkjU6IAJ"
        }
      ],
      subjectAreas: [
        {
            "areaLevel": "REGIONI",
            "commercialDivision": "Prodotto",
            "areaValue": "FVG"
        }
      ],
      subjectTags: [
        {
            tag: "Nazionale"
        }
      ],
      economicData: [
        {
            potentialRevenue: null,
            totalOutstanding: 0,
            year: 2020,
            totalRevenue: 0,
            realRevenue: null,
            businessVolume: null
        }
      ]
    }
  ]
}

Subjects section

Field	Description	Type	Mandatory
customerCode	Code of the customer in the external system	Varchar(250)	✓
system	External system present in KeepIT. This is a fixed value to specify in the call	Varchar(250)	✓
subjectName	Name of the subject	Varchar(250)
subjectSurname	Surname of the subject	Varchar(250)
subjectCompanyName	In case of Company it is the Company Name	Varchar(250)
extSubCompanyName	Extension of the Company name	Varchar(250)
subjectName2	Second name of the subject	Varchar(500)
subjectType	Subject type of the subject. It is a fixed value to specify in the call	Varchar(250)	✓
subjectSubtype	Subject subtype. It is a list of values defined in the system.	Varchar(250)	✓
lawNature	Law nature	Varchar(250)
address1	Address of the subject	Varchar(100)
address2	Extension of the address	Varchar(100)
zipCode	Zip code	Varchar(20)
municipality	Municipality	Varchar(250)
city	City	Varchar(250)
province	Province code. (referenced on the relative master table)	Varchar(3)
region	Region code. (referenced on the relative master table)	Varchar(250)
state	USA State	Varchar(250)
country	ISO2 Initial of the country	Varchar(3)
latitude	Latitude of the address	Varchar(250)
longitude	Longitude of the address	Varchar(250)
language	Language code. (referenced on the relative master table)	Char(2)
currency	Currency code. (referenced on the relative master table)	Char(3)
note	Note	Varchar(250)
sex	Sex	Char(1) - Values admitted ‘M’ - male or ‘F’ - female
birthday	Date of birth	Date
countryBirth	ISO2 Initial of the country of birth	Char(3)
fiscalCode	Fiscal Code	Varchar(50)
companyVatCode	Vat Code	Varchar(50)
passport	Passport number	Varchar(100)
maritialStatus	Maritial status. (referenced on the relative master table)	Varchar(250)
occupation	Occupation code. (referenced on the relative master table)	Varchar(250)
title	Title of the subject. (referenced on the relative master table)	Varchar(250)
origin	Origin of the contact. (referenced on the relative master table)	Varchar(250)
functionCode	Function code in the company. (referenced on the relative master table)	Varchar(250)
saleChannel	Sale channel code. (referenced on the relative master table)	Varchar(250)
organizationLevel	Organization level code. (referenced on the relative master table)tabella di anagrafica)	Varchar(250)
territory	Territory code. (referenced on the relative master table)	Varchar(250)
purchaseInclination	Purchase inclination code. (referenced on the relative master table)	Varchar(250)
employeesNumber	Number of employees in case of company	Decimal(6)
employeesDate	Date survey number of employees	Date
attractionLevel	Attraction level code. (referenced on the relative master table)	Varchar(250)
identificationLevel	Identification level code. (referenced on the relative master table)	Varchar(250)
subjectBlockReason	Block reason. (referenced on the relative master table)	Varchar(250)
poBox	Postal office box	Varchar(20)
payment	Payment code. (referenced on the relative master table)	Varchar(250)
discount	Percentage of discount	Decimal(6,2)
decisionLevel	Decision level code. (referenced on the relative master table)	Varchar(250)
isCompany	It indicates if the subjects is a company or not.	Char(1) - Values admitted 'T' for company, 'F' for person. It must always be set with ‘F’ in this case	✓
macAddress	Mac address of the mobile device	Varchar(25)
ecommerceLastVisit	Last visit in the site	Timestamp
ecommerceLastLogin	Last login in the site	Timestamp
ecommerceGuestRegister	‘G’= Guest, ‘R’= Registered	Char(1)
discountAuthorization	Note for discount authorization	Varchar(250)
phone	Main phone	Varchar(250)
website	Main website	Varchar(250)
email	Main email	Varchar(250)
childNumber	Number of child	Decimal(5)
foreignPerson	It indicates if the subject is national or fireign	Char(1) - Values admitted 'T' for foreign or 'F' for national
maximumValue	Maximum purchase value	Decimal(15,2)
countryRegistration	ISO2 Initial of the country registration	Char(3)	✓
houseNumber	House number	Varchar(20)
floor	Apartment floor	Varchar(20)
appartmentNumber	Apartment number	Varchar(20)
entrance	Entrance	Varchar(20)
block	Block	Varchar(20)

Contacts section

Field	Description	Type	Mandatory
contactType	Contact type (referenced on the relative master table)	Varchar(250) - Values admitted PHONE - EMAIL- CELL - FAX	✓ (for type EMAIL)
value	Value of the contacts	Varchar(250)

Privacy section

Field	Description	Type	Mandatory
privacyType	Privacy type (referenced on the relative master table)	Varchar(250)	✓
privacyConsent	It indicates if the subject has given consent for data processing	Char(1) - Values allowed 'T'- Consent ok or 'F' - Consent ko
consentDate	Date in which the subject give his consent	Date
recessDate	Date in which the subject remove the consent	Date

Destinations section

Field	Description	Type	Mandatory
destinationType	Destination type (referenced on the relative master table)	Varchar(250)	✓ (in case of data for difference addresses)
address1	Address	Varchar(100)
address2	Extension of address	Varchar(100)
zipCode	Zip code	Varchar(20)
municipality	Municipality	Varchar(250)
city	City	Varchar(250)
province	Province code. (referenced on the relative master table)	Char(3)
region	Region code. (referenced on the relative master table)	Varchar(250)
state	USA state	Varchar(250)
country	ISO2 Initial of the country	Char(3)
fax	Fax number	Varchar(250)
mobile	Mobile number	Varchar(250)
email	Email	Varchar(250)
note	Note	Varchar(250)
phone	Phone	Varchar(250)

Mappings section

Field	Description	Type
system	Code of the system related to the encoding.	Varchar(250)
externalField	Name of the field representing the encoding	Varchar(250)
externalCode	Value of the code of the data in the external system	Varchar(250)

Sources section

Field	Description	Type	Mandatory
source	Source of the data. (referenced on the relative master table)	Varchar(250)	✓ (in case of data to insert)
[other fields]	It's possible to set alphanumeric, numeric, date and true/false fields, but the name of the fields is dynamically set. Contact support to know the name of the fields in your environment

Subject Relations section

Field	Description	Type	Mandatory
relationType	Relation type (referenced on the relative master table)	Varchar(250)	✓ (in case of data to insert)
system	Code of the system related to the encoding.	Varchar(250)
masterSubject	External system code of the master subject of the relation	Varchar(250)
slaveSubject	External system code of the slave subject of the relation	Varchar(250)

Subject Areas section

Field	Description	Type	Mandatory
areaLevel	Alphanumeric code of the area level	Varchar(250)	✓ (in case of data to insert)
commercialDivision	Commercial division related to the area	Varchar(250)	✓ (in case of data to insert)
areaValue	Value of the specified area level	Varchar(250)	✓ (in case of data to insert)

Subject Tags section

Field	Description	Type	Mandatory
tag	Tag that has to be related to the customer	Varchar(250)	✓ (in case of data to insert)

Economic data section

Field	Description	Type	Mandatory
potentialRevenue	Potential revenue of the customer.	Decimal(20,6)
totalOutstanding	Amount of the outstanding	Decimal(20,6)
year	Year related to the economic data	Decimal(4,0)	✓ (in case of data to insert)
totalRevenue	Total revenue of the company	Decimal(20,6)
realRevenue	Real revenue of the customer	Decimal(20,6)
businessVolume	Business volume of the customer	Decimal(20,6)

Positive response example:

{
    "message":"Inserimento/Update riuscito con successo.", 
    "success":true,
    "code":200,
    "errorObjects":[],
    "insertedObjects":[ 
        {
            "progId":70,
            "customerCode": 2134,
            "email":xxx@test.it
        }
    ]
}

Multiple customer code mappings

If the calling system has multiple customer codes, there is the possibility to add all of them in the "mappings" object array, in order to provide them to 4WS.KeepIT and let them be stored.
Each code needs to be specified as an object inside the array and below there is an example of these objects:

{
    "system" : "DW",
    "externalField" : "CUSTOMER_ID",
    "externalCode" : 12345
}

The system attribute is not mandatory and if it is not specified 4WS.KeepIT will consider the value in the homonym attribute specified in the subjects object.
The externalField and the externalCode are mandatory fields, so if they are not specified 4WS.KeepIT will respond with an error.

If the mappings array is not empty, among the values must be present the same value specified in the customeCode attribute of the subjects object and must be presente the externalField attribute as well.
In insertion of a non present customer with a valid email (duplicates check passed), 4WS.KeepIT will consider all the customer codes passed; if a code is already used for the same external system but for a different customer (ex. two eCommerce customer with same code), 4WS.KeepIT will return an error and will not proceed with the insertion.
In UPDATE of an existing customer, all the non existing codes will be inserted, whereas the ones already existing will be discarded.

The discriminant to distinguish an existing code is the tuple:

   system - externalField - externalCode

Response

The web service as response provides a JSON structured like below:

success : request result as boolean (true/false).

code : response code.

200 everything went well

204 you are trying to insert an existing customer, so it is a duplicate

206 some customers have been inserted other not

400 something in the JSON request is wrong

500 generic error server

message : recap of the insertion/update.

errroObjects : contains an array of:

customerCode : customer code of the calling system

errorMessage : error description

insertedObjects : contains an array of the inserted customers data

progId : 4WS.KeepIT customer code

customerCode : customer code of the calling system

duplicatedObjects : list of the customer duplicate in 4WS.KeepIT

customerCode : customer code of the calling system

errorMessage : error description

{
    "message": "1 record inseriti/aggiornati",
    "success": true,
    "code": 200,
    "errorObjects": [],
    "insertedObjects": [
        {
            "progId": 70,
            "customerCode": xxx,
            "email": xxx@test.it
        }
    ]
}

Error list

Below a list of relevant errors and the JSON response for each type of error:

Record not found

{ 
    "success": false,
    "code": 400,
    "message": "Errore: non è stato eseguito l'inserimento/update, verificare il messaggio di errore dei record ritornati.",
    "errorObjects": [
        {
            "customerCode": "xxxx",
            "errorMessage": "Nessun record trovato per:..."
        }
    ],
    "insertedObjects": [],
    "duplicatedObjects":[]
}

Duplicate insertion attempt

{ 
    "success": true,
    "code": 204,
    "message": "Attenzione: esistono uno o più doppioni, inserimento/update non eseguito.",
    "errorObjects": [],
    "insertedObjects": [],
    "duplicatedObjects":[
        {
            "customerCode":"xxx",
            "errorMessage":"The customer already exists."
        }
    ]
}

API not found

{ 
    "success": false, 
    "message": "No alias found for '...'" 
}

Mandatory field not found in the JSON request

{
    "success": false,
    "code": 400,
    "message": "Errore: non è stato eseguito l'inserimento/update, verificare il messaggio di errore dei record ritornati.",
    "errorObjects": [
        {
            "customerCode": "xxx",
            "errorMessage": "Errore: xxx non valorizzato."
        }
    ],
    "insertedObjects": [],
    "duplicatedObjects":[]
}

Customer code value not found in the mappings array

{
    "success": false,
    "code": 400,
    "message": "Errore: non è stato eseguito l'inserimento/update, verificare il messaggio di errore dei record ritornati.",
    "errorObjects": [
        {
            "customerCode": "xxx",
            "errorMessage": "Il customer code non è specificato nell'array mappings."
        }
    ],
    "insertedObjects": [],
    "duplicatedObjects":[]
}

Notes

There's a limit of 100 calls for this API.

Insert/Update CRM customer

Response

Error list

Record not found

Duplicate insertion attempt

API not found

Mandatory field not found in the JSON request

Customer code value not found in the mappings array

Request

Request Code Samples

Responses

Insert/Update CRM customer

Response#

Error list#

Record not found#

Duplicate insertion attempt#

API not found#

Mandatory field not found in the JSON request#

Customer code value not found in the mappings array#

Request

Request Code Samples

Responses

Response

Error list

Record not found

Duplicate insertion attempt

API not found

Mandatory field not found in the JSON request

Customer code value not found in the mappings array