Insert/Update 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 (in this case, the progId field in the subjects object is required)

Below a JSON example with the mandatory attributes:

{
  subjectsRecords: [
    {
      subjects: {
        progId: 12345,
        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: "",
        idCard: "",
        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: ""
        }
      ],
      cards: [
        {
          cardType: "FIDELITY",
          cardSubtype: "GEN",
          circuit: "SINESY",
          card: "1357924711",
          cardBarcode: "1357924711",
          issueDate: "2016-03-24",
          active: "",
          activationDate: "2016-03-24",
          expirationDate: "2017-03-24",
          cardMaster: "",
          cardFather: "",
          cardMother: "",
          entityCode: "",
          earnedPoints: 0
        }
      ],
      subjectDestinations: [
        {
          destinationCode: "DESTINATION1",
          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
        }
      ],
      subjectMakeup: {
        skinType: "",
        hairColor: "",
        complexionType: "",
        eyesColor: "",
        makeupProgram: "",
      },
      subjectSources: [
        {
          source: "",
          insertDateSource: "",
          provenance: "",
          participatedCheck: "",
          wonCheck: "",
          surveySelectCheck: "",
          surveyValCheck: "",
          itemCodeWon: "",
          itemDescWon: "",
          itemCodeChosen: "",
          itemDescChosen: "",
          itemCodePur: "",
          itemDescPur: ""
        },
        {
          source: "",
          insertDateSource: "",
          provenance: "",
          participatedCheck: "",
          wonCheck: "",
          surveySelectCheck: "",
          surveyValCheck: "",
          itemCodeWon: "",
          itemDescWon: "",
          itemCodeChosen: "",
          itemDescChosen: "",
          itemCodePur: "",
          itemDescPur: ""
        }
      ]
    }
  ]
}

Subjects section

Field	Description	Type	Mandatory
progId	KeepIT internal code for the customer (required when updating a subject)	Varchar(250)
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)
idCard	Identity card number	Varchar(100)
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)	Varchablocr(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)
lotteryCode	It indicates the code of the lottery for the subject	Varchar(250)

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

Cards section

Field	Description	Type	Mandatory
cardType	Card type (referenced on the relative master table). This is a fixed value to specify in the call	Varchar(250)	✓ (in case of fidelity cards)
cardSubtype	Card subtype (referenced on the relative master table)	Varchar(250)	✓ (in case of fidelity cards)
circuit	Circuit of card (referenced on the relative master table). This is a fixed value to specify in the call	Varchar(250)	✓ (in case of fidelity cards)
card	Progressive of the card	Varchar(250)	✓ (in case of fidelity cards)
cardBarcode	Card barcode	Varchar(50)	✓ (in case of fidelity cards)
issueDate	Date of issue of the card	Date
active	It indicates if the card is active or not	Char(1) - Values allowed 'T' - active, 'F' - not active
activationDate	Data of activation	Date
expirationDate	Expiration ate	Date
cardMaster	This is the card master for manage group of card	Varchar(250)
cardFather	In case of children related this is the card of the father	Varchar(250)
cardMother	In case of children related this is the card of the mother	Varchar(250)
entityCode	Shop that issued the card	Varchar(250)
earnedPoints	Total point earned	Decimal(10)

Destinations section

Field	Description	Type	Mandatory
destinationType	Destination type (referenced on the relative master table)	Varchar(250)	✓ (in case of data for difference addresses)
destinationCode	Destination code, used to update an extisting destination	Varchar(250)
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)

Subject Makeups section

Field	Description	Type
skinType	Skin type. (referenced on the relative master table)	Varchar(250)
hairColor	Hair color. (referenced on the relative master table)	Varchar(250)
complexionType	Complexion type (referenced on the relative master table)	Varchar(250)
eyesColor	Eyes color. (referenced on the relative master table)	Varchar(250)
makeupProgram	Makeup program. (referenced on the relative master table)	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)
insertDateSource	Insert date	Date

Actions section

Field	Description	Type	Mandatory
actionCode	Code of the Action	String	✓
actionType	Code of the ActionType	String	✓
actionStatus	Code of the ActionStatus	String	✓
system	System	String	✓
description	Action description	String
note	Additional notes for the action	String
startDate	Action start date	Date
endDate	Action end date	Date

Positive response example:

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

For each section received in input an array with the progId is returned.

Complete response example:

{
    "message":"Inserimento/Update riuscito con successo.", 
    "success":true,
    "code":200,
    "errorObjects":[],
    "insertedObjects":[
    {
        "progId":70,
        "customerCode": 2134,
        "email":xxx@test.it,
        "mapping": [{
            "progId": "progIdRecord"
        }],
        "contacts": [{
            "progId": "progIdRecord"
        }],
        "privacy": [{
            "progId": "progIdRecord"
        }],
        "cards": [{
            "progId": "progIdRecord"
        }],
        "destinations": [{
            "progId": "progIdRecord"
        }],
        "commercialDivisions": [{
            "progId": "progIdRecord"
        }],
        "makeup": {
            "progId": "progIdRecord"
        },
        "sources": [{
            "progId": "progIdRecord"
        }],
        "actions": [{
            "progId": "progIdRecord"
        }]
}]

}

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