Contact API

Quick Reference

This document describes the public contact API of S-360 360.

The web service ContactInformationService allows an external system to create contacts and structures, associate them to addresses, phone number, emails... Give them authorization or set contact criteria for them.

The web service ContactAuthenticationService handles authentication questions.

It allows also to set login and password for the Ticketshop of even authenticate.

S-360 standard for web-services

Please refer to that document. Both SOAP and REST are available for these APIs.

Unless otherwise specified, all those methods are transactionnal and idempotent.

Non Functional consideration

Remember call rate limitation explained in API Terms and Conditions.

Error codes

Error codes are referenced here

Contact data model

Model description

S-360 handles two kind for contacts : individuals and structures.

Individuals are physical persons, interacting with the organization (B2C).

Structures are corporations or associations. each structure being able to have a list of members : professional individuals which have a role towards the structure.

Each contact is associated to a list of associated objects : addresses (postal), commercial advantages, authorizations, criteria.

A contact criterion is a criterion qualifying a contact. Each institution pre-defines, durting set up, its proper list of criteria. Those critieria may be used for commercial or statistic reasons.

Example : inscription to a given newsletter, domain of interest, socio-professional category, etc.

A contact authorization is the way that marketing information can be communicated to a contact, if and only if this contact authorized it. Authorizations are very often called "opt-ins".

Most of the time, authorizations defined for an institution are amongst those ones:

• Authorization to communicate information
• Authorization to communicate offers from third parties
• Authorization to transfer contact address to third parties
• Authorization to communicate via mail, phone, SMS or email.

Every contact has a contactNumber, defined as a string, identifying him or her, unique for a given institution. This contact number may appear in communications sent by S-360. This contact number cannot be edited, neither via the APIs nor via the screens.

Contact Information Public Service

Reading and finding contacts

getContactData : the most useful method of this API. Allows to read information associated to a contact. The details field allows to select the granularity of data.

searchContactByCriteria : Allow to search for contacts passing a choice of filters.

Handing individuals

saveIndividualContactData : method to create/update an individual contact.

Handling structures

saveStructureContactData : This method allows to modify or create a contact of the type structure

saveStructureAdministrativeNumbers : This method saves the list of administrative numbers for the given structure.

saveStructureMember : This method allows to modify or create a contact member of a structure.

deleteStructureMember : This method remove a contact member of a structure.

listStructureMembersByCriteria : This method lists all the contact matching the give search criterion

Retrieve static data

Those methods allow to list some static data defined at the level of the organization. Those methods do not need to be called frequently. Caching their results for at least 2 hours is recommanded.

getStructureTypes : listing the structure types (Here comes captain obvious !)

getAvailableContactCriteria : listing the available contact criteria.

getAvailableAutorizations : listing the available authorizations.

getAvailableAdmnistrativeNumbers : the administrative numbers to be associated to structures.

Contact Authentication Service

This service provides methods related to contact authentication.

authenticate : This method is used to authenticate a contact based on his login and password and more attributes available from ContactAuthenticationData.

recoverPassword : This method allows a contact identified by the given email address to request a new randomly generated password for authentication.

changePassword : This method allows to modify the current password of a contact identified by its contact number.

listAuthorizedPOS : This method returns the list of point of sales authorized for given contact who needs to be authenticated

Remember me cookie

It is possible, from the authenticate method, to generate a cookie allowing to log on the ticket shop.

This cookie must be built this way:

• Must be httpOnly, secure
• Must be named : stx_rememberMe_<InstitutionCode>_<saleChannelCode>

• Must contain the following information:

  {
    pointOfSalesId = "<pointOfSalesId>",
    rememberUniqueId = "<ContactAuthenticationResult .identification>",
    token = "<ContactAuthenticationResult .uniqueToken>",
    virtualOperator = "<InstitutionCode>_<saleChannelCode>"
  }