Know How: API calls for a Profile page

Business

The examples below propose examples of calls to process the changes to an individual contact (main data, addresses, opt-ins, criteria...)

All the examples can be executed on the following endpoint: https://mosa.demo-ws.secutix.com/tnco/external-remoting/com.secutix.service.contact.v2_21.ContactInformationPublicService.webservice

Concepts

A contact of type Individual represents a person in S-360 system. Please refer to : [../contacts#model-description to](the model description) for an explanation about the concepts used in the page below.

Does a given contact already exist ?

It is possible to search a contact by its number.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://v2_21.ContactInformationPublicService.service.secutix.com/">
   <soapenv:Header>
      <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-1" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>MOSA_B2C</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">P@ssw0rd</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <v2:getContactData>
         <contactNumber>333</contactNumber>
         <details>GENERAL</details>
         <details>ADDRESSES</details>
      </v2:getContactData>
   </soapenv:Body>
</soapenv:Envelope>

It is also possible to search it via its email. In S-360, many contacts can share the same email, but only one contact with role PUBLIC can have a login with a given email.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://v2_21.ContactInformationPublicService.service.secutix.com/" xmlns:ns2="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <SOAP-ENV:Header>
      <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken>
            <wsse:Username>MOSA_B2C</wsse:Username>
            <wsse:Password>P@ssw0rd</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
      <ns1:searchContactByCriteria>
         <contactTextSearch>
            <searchFields>EMAIL</searchFields>
            <searchText>ulrich.pabst@yopmail.com</searchText>
         </contactTextSearch>
         <!-- Put true in the value below if you want to search the contacts who do not have login -->
         <includeWithoutConnection>true</includeWithoutConnection>
      </ns1:searchContactByCriteria>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Updating a contact

All the manipulations on a given individual are made through the saveIndividualContactData method.

This method allows to pass many elements:

  • IndividualContactData to pass the main identity elements
  • Addresses
  • Authorizations
  • Criteria
  • others...

The first parameter (contactNumber) indicates which contact you will be updating. If empty, it tries to create a new contact.

It is possible to call the method by passing only the individualContactData, or the addresses, or the criteria or authorizations, or all at once.

Storing main identity elements (firs name, last name, title...)

Call the method saveIndividualContactData passing an IndividualContactData object.

If you are creating a new contact

The minimal fields are the following:

  • First name
  • Last name
  • Title
  • Preferred language

Beware: for historical reasons, the object IndividualContactData contains some address elements (like zipcode, town, etc.).

Those elements cannot be updated through this object. You must use address objects instead.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://v2_22.ContactInformationPublicService.service.secutix.com/">
       <soapenv:Header>
      <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-1" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>MOSA_B2C</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">P@ssw0rd</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security></soapenv:Header>
   <soapenv:Body>
        <v2:saveIndividualContactData>
         <individualContactData>
            <email>martin.faerber@yopmail.com</email>
            <individualFirstname>Martin</individualFirstname>
            <individualLastname>Faerber</individualLastname>
            <individualTitle>MR</individualTitle>
            <individualPreferredLanguage>DE</individualPreferredLanguage>
            <individualBirthdate>1993-10-24T00:00:00+01:00</individualBirthdate>
         </individualContactData>
      </v2:saveIndividualContactData>

   </soapenv:Body>
</soapenv:Envelope>

If you are updating a contact

The first parameter of saveIndividualContactData must be contactNumber of the contact that you are updating.

The second parameter must be the individualContactData object that you retrieved through a call to getContactData.

It is NOT possible to pass an IndividualContactData object containing only the fields that you want to change.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://v2_22.ContactInformationPublicService.service.secutix.com/">
       <soapenv:Header>
      <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-1" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>MOSA_B2C</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">P@ssw0rd</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security></soapenv:Header>
   <soapenv:Body>
        <v2:saveIndividualContactData>
        <contactNumber>31821</contactNumber>

         <individualContactData>
            <email>martin.faerber@yopmail.com</email>
            <individualFirstname>Martin</individualFirstname>
            <individualLastname>Faerber</individualLastname>
            <individualTitle>MR</individualTitle>
            <individualPreferredLanguage>DE</individualPreferredLanguage>
            <individualBirthdate>1993-10-24T00:00:00+01:00</individualBirthdate>

         </individualContactData>
      </v2:saveIndividualContactData>

   </soapenv:Body>
</soapenv:Envelope>

Phone numbers

Phone numbers must be stored in E164 format. Example: +497361751810

A contact can have a cellphone number, 3 other phone numbers and a fax number.

If you pass a cellphone number into the number phoneNumber1, it will be moved to cellPhoneNumber. If you pass a landline number into the cellPhoneNumber, it will be moved to phoneNumber1.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://v2_22.ContactInformationPublicService.service.secutix.com/">
       <soapenv:Header>
      <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-1" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>MOSA_B2C</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">P@ssw0rd</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security></soapenv:Header>
   <soapenv:Body>
        <v2:saveIndividualContactData>
        <contactNumber>31821</contactNumber>

         <individualContactData>
            <email>martin.faerber@yopmail.com</email>
            <individualFirstname>Martin</individualFirstname>
            <individualLastname>Faerber</individualLastname>
            <individualTitle>MR</individualTitle>
            <individualPreferredLanguage>DE</individualPreferredLanguage>
            <individualBirthdate>1993-10-24T00:00:00+01:00</individualBirthdate>
            <phoneNumber1>+497361751810</phoneNumber1>

         </individualContactData>
      </v2:saveIndividualContactData>

   </soapenv:Body>
</soapenv:Envelope>

Updating the address

A contact can have many addresses. One of those must be the main address. An address must contain at least the following 3 fields: Country, Town and Zipcode.

To add an address to a contact, pass the parameter fullAddresses to false. To update an address of a contact, pass its address id along, or pass the full list of all its addresses with parameter fullAddresses=true

(this full... boolean logic also applies to the other objects of a contact like authorizations and criteria)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://v2_22.ContactInformationPublicService.service.secutix.com/">
   <soapenv:Header>
      <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-1" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>MOSA_B2C</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">P@ssw0rd</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <v2:saveIndividualContactData>
         <contactNumber>31821</contactNumber>
         <addresses>
            <billingAddress>true</billingAddress>
            <countryCode>DE</countryCode>
            <line1>Borstelmannsweg 92</line1>
            <main>true</main>
            <name>Main address</name>
            <shippingAddress>true</shippingAddress>
            <town>92650</town>
            <zipCode>Grafenwöhr</zipCode>
         </addresses>
         <addresses>
            <billingAddress>false</billingAddress>
            <countryCode>DE</countryCode>
            <line1>Karl-Liebknecht-Strasse 98</line1>
            <name>Secondary address</name>
            <shippingAddress>true</shippingAddress>
            <town>28816</town>
            <zipCode>Stuhr</zipCode>
         </addresses>
         <fullAddresses>true</fullAddresses>

      </v2:saveIndividualContactData>
   </soapenv:Body>
</soapenv:Envelope>

Updating the authorizations (opt-ins)

The list of available authorization codes can be accessed through the method =getAvailableAuthorizations=

The result of this method can be cached on the caller side as this list does not change very often.

This list allows to display the available authorizations on an update profile page.

Updating the authorizations is done using the same =saveIndividualContactData= method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://v2_22.ContactInformationPublicService.service.secutix.com/">
   <soapenv:Header>
      <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-1" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>MOSA_B2C</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">P@ssw0rd</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <v2:saveIndividualContactData>
         <contactNumber>31821</contactNumber>
         <authorizations>
            <allowed>true</allowed>
            <authorizationCode>CNIL_O</authorizationCode>
         </authorizations>
         <fullAuthorizations>false</fullAuthorizations>
      </v2:saveIndividualContactData>
   </soapenv:Body>
</soapenv:Envelope>

Updating the contact criteria (for example, to subscribe to a newsletter)

The list of available criteria codes can be accessed through the method =getAvailableContactCriteria=

The result of this method can be cached on the caller side as this list does not change very often.

This list allows to display the available criteria on an update profile page.

Updating is done through saveIndividualContactData method.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v2="http://v2_22.ContactInformationPublicService.service.secutix.com/">
   <soapenv:Header>
      <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
         <wsse:UsernameToken wsu:Id="UsernameToken-1" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
            <wsse:Username>MOSA_B2C</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">P@ssw0rd</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <v2:saveIndividualContactData>
         <contactNumber>31821</contactNumber>
            <externalContactCriterionData>
            <criterionIdCode>NEWSLET</criterionIdCode>
            <values>true</values>
         </externalContactCriterionData>
         <fullContactCriteria>false</fullContactCriteria>

      </v2:saveIndividualContactData>
   </soapenv:Body>
</soapenv:Envelope>