Certify data using the REST API

The REST API supports testing a record against the certification process without persisting it. This type of query allows applying enrichment, validation, and matching rules defined in the model on any record.

When performing such a query, parameters are available to select which enrichers, validations, and match rules to execute. The content of the response payload (enriched record and potential matches) is also configurable.

Certify one record

Method

POST

Base URL

http://<host>:<port>/semarchy/api/rest/

URL

[base_url]/certify/[data_location_name]/[entity_name]

Request payload

The request payload contains:

record: the record to certify.
options: the certification parameters:
- enrichers: defines the enrichers that should be executed. Possible values are:
  - JOB_PRE_CONSO (default): run all the enrichers configured with a Pre-Consolidation Only or Pre and Post Consolidation scope.
  - ALL: run all enrichers defined for the entity.
  - A list of enricher names in the following format:
    
    [ "<enricher_name>", ... ]
- returnEnrichedRecord: specifies whether the enriched record should be returned.
- validations: defines the validations that should be executed after the enrichers. Possible values are:
  - JOB_PRE_CONSO (default): run all validations configured with a Pre-Consolidation Only or Pre and Post Consolidation scope.
  - ALL: run all the validations defined for the entity.
  - A list of validations with their name and type in the following format:
    
    [ { "validationType": "<validation_type>", "validationName": "<Validation_name>" }, ... ]
    
    Possible validationType values are CHECK, PLUGIN, MANDATORY, LOV, FOREIGN or UNIQUE.
- queryPotentialMatchesRules: defines the match rules to use to detect potential matches. Possible values are:
  - ALL (default): run all the match rules defined for the entity.
  - A list of match rule names, in the following format:
    
    [ "<match_rule_name>", ... ]
    
    The Certify API applies matching rules only to the attributes of the entity being certified. It does not support applying these rules to attributes of child records.
- queryPotentialMatchesHighestScoreOnly: when set to true, the Potential matches section of the response includes only the result of the match rule that generates the match with the highest score. Otherwise, the query returns all matches found.
- queryPotentialMatchesBaseExpressions: defines the set of base attributes to include in the response for the potential matches found. Possible values are:
  - NONE: No attributes.
  - USER_ATTRS (default): all entity attributes, except the built-in attributes and references.
  - VIEW_ATTRS: all entity attributes, except references. Includes the built-in attributes.
  - ID: only the identifier attributes. Depending on the entity type and the matched record’s location, PublisherID, SourceID, the golden ID, and/or the primary key will be returned.
- queryPotentialMatchesExpressions: expressions to include in the response for the potential matches found, in addition to the base attributes (queryPotentialMatchesBaseExpressions). These expressions are in the following format: [alias]:[semql_expression].

Example 1. Certify data: sample request to certify one record

{
  "options": {
    "enrichers": "ALL",           (1)
    "returnEnrichedRecord": true, (1)
    "validations": "JOB_PRE_CONSO", (2)
    "queryPotentialMatchesRules": ["ExactFirstAndLastName","SameBirthDate"], (3)
    "queryPotentialMatchesHighestScoreOnly": true, (3)
    "queryPotentialMatchesBaseExpressions": "VIEW_ATTRS" (3)
  },
  "record": {
    "FirstName": "John",
    "LastName": "Doe",
    "SourceEmail": "john@doe.",
    ...
  }
}

1	Run all enrichers on the incoming record, and return the enriched values
2	Run all pre-consolidation validations.
3	Query potential matches using the two rules, only return the record with the highest score with all entity attributes.

Response format

The response contains the enriched record, the failed validations, the certification steps (enricher, validation, and match rules) processed, and the potential matches found.

Example 2. Certify data: sample response

{
  "enrichedRecord": {
    "entityName": "Person",
    "recordValues": {

        "FirstName": "Johnny",
        "LastName": "Doe"
        ...,
        "PhoneticFirstName": "JN",
        "PhoneticLastName": "T",
        "NormalizedFirstName": "JOHN",
        "NormalizedLastName": "DOE",
        ...
    },
      "failedValidations": [
        {
            "validationType": "PLUGIN",
            "validationName": "InvalidEmail",
            "validationErrorMessage": "Validation failed for Invalid Email"
        }
    ],
    "certificationSteps": {
        "enrichers": [
            "PhonetizeFirstName",
            "PhonetizeLastName",
            ...
        ],
        "validations": [
            {
                "validationType": "MANDATORY",
                "validationName": "SourceEmail"
            },
            ...
        ],
        "matchRules": [
            "ExactNameOrNicknameAddressPhoneEmail",
            "ExactEmailMatch",
            ...
        ]
    },
  "potentialMatches": [
    {
      "matchRuleName": "ExactName",
      "matchScore": 100,
      "matchedRecordLocation": "MD",
      "matchedRecordId": {
        "SourceID": "1368178",
        "PublisherID": "MKT"
      },
      "matchedRecordData": {
        "PublisherID": "CRM",
        "SourceID": "5",
        "FirstName": "John",
        "LastName": "Doe"
        ...
      }
    }
  ]
}