The HTTP API

The HTTP API takes GET requests in the following schema:

With several available combinations:

Common parameters

• API name: smatching
• API current version: d04
• GET parameters:
  • codeapiaccess: Mandatory, this is he access code that have been provided to you when you have created your account. You can find it in your profile page.
  • format: json par défaut, vous pouvez indiquer xml pour un retour au format XML.

Parameters for specific calls (cf. examples)

Load the list of questionnaires

• GET parameters:
  • rlist: Mandatory filled with the value qs: allows to return a list of questionnaires.
  • target: Leaved empty, we will return the whole liwt of your questionnaires. Use this parameter to filter the results on the type of the target: 0 (persons) or 1 (enterprises)
  • qslabel: This parameter allows you to filter the result on the label. You will receive only the questionnaires which label contains this string.
• Returns:
  This call will return an array in JSON or XML format, containing one line per result with the following datas:
  • total_displayed: Number of found occurences.
  • id_questionnaire: idof the questionnaire. You will need it in your next calls.
  • qslabel: Label of the questionnaire.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • qsdescription: Description du questionnaire.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • target: The target population of the questionnaire: 0 for persons, 1 for companies.
• Error messages:
  • result: Returns 'no result' if no questionnaire has been found.

Example:

Get the first question of a qustionnaire

• GET parameters:
  • qs: Mandatory Id of the questionnaire
  • uid: Unique id of one of your users. You chose this value. It will be used to identifie the user in our side, so you can collect its answers and results. If this value exists in this first step, we will check if this user has already begone this questionnaire and send you his next question instead of the first of the questionnaire.
• Returns:
  This call will return an array in JSON or XML format, containing one line per result with the following datas:
  • total_displayed: Total number of couples question / response found.
  • id_question: Id of the question.
  • qnlabel: Label of the question.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • qndescription: Description of the question.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • id_response: id of the response.
  • rslabel: Label of the response.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • rsdescription: Description of the response.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.

Example:

Get the next question

• GET parameters:
  • rs: Mandatory Id of the response selected. This id was sent to your system via the last call (first question of the questionnary, or last answer)
  • uid: Mandatory Id of the user. unique in your environment, it will be used to return the results for this person or company. It can be any value, number or string of your choice.
• Returns:
  This call will return an array in JSON or XML format, containing one line per result with the following datas:
  • total_displayed: Total number of couples question / response found.
  • id_question: Id of the question.
  • qnlabel: label of the question.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • qndescription: Description of the question.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • id_response: Id of the réponse.
  • rslabel: Label of the response.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • rsdescription: Description of the response.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
• End message:
  • result: Returns 'end' means that you have reached the end of the questionnaire.
• Error messages:
  • result: Returns 'uid missing. Please add this information to the get datas of the link.' if the uid misses.

Example:

Collect the result profile of a user

• GET parameters:
  • rlist: Mandatory Filled with profile.
  • qs: Mandatory Id of the wanted questionnaire.
  • uid: Mandatory Id of the user.
• Returns:
  This call will return an array in JSON or XML format, containing one line per result with the following datas:
  • total_displayed: Total number of caracteristics found.
  • id_profile: Profile id.
  • id_questionnaire: Questionnaire id.
  • uid: User id.
  • label: Label of the profile.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • description: Description of the profile.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • ponderation: Cumulated number of ponderation points for this profile or caracteristics.
  • nb_responses: Number of responses used in the calculation of this ponderation. It allows you to calculate the average note.
• Error messages:
  • result: Returns 'Missing: [['uid.'], ['qs'], ['prf']]' if these parameters are missing.

Example:

Delete a result for a user

You can propose to your users to delete a result of a test directly in our database. Just do the following call:

• GET parameters:
  • rlist: Mandatory Filled with del.
  • prf: Mandatory Id of the caracteristics to delete (id_profile returned to you in the former call).
  • qs: Mandatory Id of the questionnaire.
  • uid: Mandatory Idof the user.
• Returns:
  • result: Returns 'Profile ['prf'] for user ['uid'] on questionnaire 'qs': DELETED.' if the deletion succeeded.
• Error messages:
  • result: Returns 'Error: You are not allowed to delete this information.' if the deletion failed.

Example:

Get the list of matching users

This call returns a list of matching uid of users whose answers to the questionnaire matches the reference uid according to our correlation algorithm..

• GET parameters:
  • rlist: Mandatory Filled with the value matching.
  • uid: Mandatory Id of the user.
  • qs: Mandatory Id of the questionnaire to use to make the matching.
  • ratio: Integer between 0 and 100 setting the minimum ratio needed in one caracteristics at least to be selected.
  • target: If not defined, we eturn only the compatible uid, that is to say the enterprises id (target=1) if the reference uid is a person (target=0). If target is defined, we will return the targeted population, even if it is the same value as the reference uid's target type.
  • limit: Allows to limit the number of result. By default we will return 20 results.
• Returns:
  This call will return an array in JSON or XML format, containing one line per result with the following datas:
  • total: Total number of ponderation points obtained by this uid.
  • uid: id of the user (person or enterprise) found in our database.
  • profiles: array containing the results of the uid for each caracteristics.
    This array is composed as follows:
    • id_profile: id of the profile (or caracteristics).
    • score: Average notation between -5 and +5, obtained for this caracteristic. -5 means a reject of the value described by the carcacteristic, +5 a perfect agreement or identification.
    • compatibility: Compatibility ratio calculated for this profile (or caracteristic). ((reference score * compared score / square value of the reference score) * 100).
    • ref_score: Reference score obtained by the uid passed in parameter for this profile (caracteristic). Average score between -5 and +5. -5 means a reject of the value described by the carcacteristic, +5 a perfect agreement or identification.
    • max: Global refrence value = sum of the square values for each profile (caracteristic) obtained by the reference uid in this questionnaire. Used to calculate the global compatibility ratio.
  • glob_compat: Global compatibility ratio, calculated with all caracteristics of the uid.
• Error messages:
  • result: Returns 'Ratio parameter must be an integer between 0 and 100.'.
  • result: Returns 'UID parameter is mandatory.'.
  • result: Returns 'The UID indicated is not known by our service.'.
  • result: Returns 'The qs parameter is mandatory.'.

Example:

get the values and description of a profile or caracteristic with its id

In the smatching call returns, you will obtain a list of uids and its scores in the compatible profile ids (id_profile).
To find the readable informations of this profile, just use the following parameters:

• GET parameters:
  • rlist: Mandatory Filled with the value profile.
  • prf: Mandatory Id of the needed profile (or caracteristic).
• Returns:
  This call will return an array in JSON or XML format, containing one line per result with the following datas:
  • id_profile: Id of the profile.
  • label0: Label of the profile or caracteristic written for the target type 'persons'.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • label1: Label of the profile or caracteristic written for the target type 'companies'.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • description0: Description of the profile or caracteristic written for the target type 'persons'.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
  • description1: Description of the profile or caracteristic written for the target type 'companies'.
    Notice: the textual data are encoded in html entites. You might need the html_entity_decode function or equivalent to display it properly.
• Error messages:
  • result: Returns 'Missing: [['uid.'], ['qs'], ['prf']]' if a parameter is missing.

Example:

Compare 2 uid's profiles

This call allows you to compare the results of 2 users on a test.

• GET parameters:
  • rlist: Mandatory Filled with compare.
  • qs: Mandatory Id of the questionnaire.
  • uid: Mandatory Contains the two uid to compare, separated with a comma.
• Returns:
  This call will return an array in JSON or XML format, containing one line per result with the following datas:
  • ref_uid: Reference uid.
  • comp_uid: The uid to compare.
  • ref_max: Reference score.
  • profiles: Table of each compared caracteristic or profile:
    • id_profile: Id of the profile or the caracteristic.
    • ref_score: Average score obtained by the reference uid on this caracteristic.
    • score: Average score obtained by the compared uid on this caracteristic.
    • compatibility: Compatibility ratio calculated for this profile or caracteristic. Equals 'NA' if not relevant for this caracteristic. A score of 0 is considered as irrelevant
  • comp_score: Global score of the compared uid.
  • compatibility: Global compatibility ratio.
• Error messages:
  • result: 'The qs parameter is mandatory' .
  • result: 'UID parameter is mandatory.'.
  • result: 'The UID XYZ is not known by our service.'.

Exemple: