getRecommendedCriteriaForEntity

For an authenticated user, return the array or criteria specified by the admin in SAM for an entity (company or event). This criteria is the same array of criteria used by both frontend and backend to match up a users basic profile details with the criteria for discovery/search and when verifying a request to connect is eligible.

See link for further details: https://docs.google.com/document/d/11alwVD_i64tv-Cy8J7SCYEZ_J9JjQwG94MWAbKREG40/edit#heading=h.hbt5b26dirl7

Request

POST /rest/user/recommended/entityCriteria

Headers

Header	Required	Description
x-nextinteract-authtoken	Yes	Auth token returned from loginUser

Response

200 OK

Returns a JSON array of dictionaries. If no results are returned, an empty array is to be returned.

{
   "criteria" : [
      {
          "criteriaId" : 1000,
          "countries" : ["AU"],
          "professions" : [1],
          "specialties" : [1],
          "identifiers" : [100]
      },
      {
          "criteriaId" : 1001,
          "countries" : ["US"],
          "professions" : [1],
          "specialties" : [1],
          "identifiers" : [200]
      },
      {
          "criteriaId" : 1002,
          "countries" : ["AU", "US"],
          "professions" : [1],
          "specialties" : [1],
          "identifiers" : [100, 200]
      },
      {
          "criteriaId" : 1003,
          "countries" : [],
          "professions" : [],
          "specialties" : [],
          "identifiers" : []
      }
   ],
   "identifierDefinitions" : [
      {
          "identifierId" : 100,
          "name": "AHPRA",
          "desc": "Australian Health Practitioner Regulation Agency",
          "formatDesc": "e.g. XYZ0123456789",
          "formatRegex": "^([a-zA-Z]{3})([\\d]{10})$",
          "countryCode": "AU"
      },
      {
          "identifierId" : 200,
          "name": "USHPRA",
          "desc": "United States Health Practitioner Regulation Agency (a fake identifier)",
          "formatDesc": "e.g. XYZ0123456789",
          "formatRegex": "^([a-zA-Z]{3})([\\d]{10})$",
          "countryCode": "US"
      }
   ]
}

The payload returned is a JSON dictionary with two fields/sections... the criterion section which contains the array of criteria which is a mirror of what the admin in SAM entered for their company etc, allowing for discoverability by users. The second section is identifierDefinitions which is all the specification of the identifiers used/referenced in the criteria in the criterion array. Separating this, allows for a more compact response and allows reuse and reference in other sections of the payload.

Fields specific to criterion section:

Field	Type	Description
criteriaId	String or Number	The criteria ID in SAM of a criteria for a specific company/event etc that assists in matching.
countries	Array of Strings	Zero or more ISO country codes (lowercase). Empty array implies “don’t care” or “All Countries”.
professions	Array of Numbers	Zero or more profession IDs. Empty array implies “don’t care” or “Any Profession”.
specialties	Array of Numbers	Zero or more specialty IDs. Empty array implies “don’t care” or “Any Specialty”.

NOTE: In SAM, you can specify a criteria which does not specify a profession, which should imply any profession, which indirectly implies any specialty. If the user does specify profession, the requirements we defined, says we can only specify at most one profession, thus specialty is defined as one or more (or all) specialties for that profession.

NOTE: professions is an array not a single id, in case we made a mistake and want to support more professions, it’s easier for future compatibility.

Fields specific to identifierDefinitions section:

Field	Type	Description
identifierId	Number	SAM primary key ID of the identifier.
name	String	Short name describing identifier.
desc	String	Verbose name describing identifier.
formatDesc	String	Placeholder text in the UI, giving an example of what the identifier value should look like.
formatRegex	String	Regular Expression used to validate the identifier value. Currently only validates the format.
countryCode	String	ISO 2 character country code, see SAM reference data API, used to correlate which identifiers are allowed in which country.

NOTE: this will work, as the requirement in SAM UI is such that, the admin is only allowed to pick ONE identifier per country per criteria.

Response Headers

{ "version" : 1, "entityType" : "company", "entityId" : "1234" }

Field	Type	Description
version	Number	Currently set to the number 1.
entityType	String	Specifies the type of entity we are querying about: ”company” for a company, ”event” for an event (RESERVED FOR FUTURE USE).
entityId	String	The value is dependent on the entity type. For a company it will be a company ID (number), for an event it will be the event ID (UUID). Represented and passed as a string.

Errors

Exception	Description
WSInvalidParameterException	See Error Definitions
WSUnsupportedVersionException	See Error Definitions
WSInvalidAuthTokenException	See Error Definitions
WSCacheServiceException	See Error Definitions
WSDiscoverableServiceException	See Error Definitions