COmanage Match can be used with Registry or as a standalone product complementary to your other tools. Match has an API that enables you to integrate the Match engine to meet your needs. This group of pages provides details for working with the Match API.

COmanage Match User Guide

1. Match API

1.1. About the API

COmanage Match is a standalone Matching solution based on the ID Match Strawman API that was initially drafted in 2011. The API was since formalized by the TIER API/Reg Working group. The current full documentation for the API can be found in the API Schema Github repository.

View Match API Documentation

IMPORTANT

The information provided on this page is designed to provide a high-level description of the API, though will be insufficient for API use. The reader is advised to reference the documentation linked above for more information.

1.2. API Base URL for Match Users

The Match API is available via

https://yourserver/match/api/matchgrid_id/v1/

where matchgrid_id indicates the Matchgrid to access. Authentication and authorization for Match API access is controlled by API Users. The matchgrid_id is available on the page for configuring Matchgrid API Users, or by inspecting the URL of most Matchgrid-specific pages.

More on the Accessing the Match API Reference page...

1.3. API Attributes

Two types of attributes are used by the Identity Match protocol, Core Schema Attributes (which are largely used to transfer information about the subject to be matched) and Match API Attributes (which are defined by the protocol).

1.3.1. Core Schema Attributes

These attributes are generally sent to Match from Sources of Record to be used for comparing records for matches. The API uses the TAP Attribute Dictionary JSON Representation for transporting the attributes via the API. This specification has several representations for attributes; the match API uses two of them as noted below.

While any attributes defined in the TAP Attribute Dictionary are permitted in match requests, the following list contains the most common attributes used with the Match API by their JSON representation style:

1.3.1.1. REPRESENTATION: Simple Attribute with Multiple Values

{
  "citizenships": [
    "CA",
    "NL"
  ]
}
  • dateOfBirth
  • gender
  • primaryAffiliation
  • primaryCampus

1.3.1.2. REPRESENTATION: Complex Attribute with Multiple Values

{
  "names": [
    {
      "given": "Patricia",
      "family": "Lee",
      "type": "official"
    },
    {
      "given": "Pat",
      "family": "Lee",
      "type": "preferred"
    }
  ]
}
  • address
  • emailAddress
  • name
  • telephoneNumber
  • identifier
    • sor
    • national
    • network
    • enterpris

1.3.2. Match API Attributes

Match API Attributes are used to manage match requests and responses. These attributes include the following (please refer to documentation for details):

  • confidence - A representation of the Match Engine’s confidence of a result, from 0 (lowest confidence) through 100 (maximum confidence).
  • explanation - A human readable explanation generated by the Match Engine as to why a specific result was generated, intended to provide guidance to an administrator trying to resolve a potential match.
  • matchRequest - A transaction identifier assigned by the Match Engine to represent a specific match request action.
  • referenceId - The unique identifier assigned by the Match Engine to each individual subject identified by the match algorithm.
  • sorId - The unique identifier used within the System of Record for the record being referenced. 
  • sorLabel -A short string identifying the calling System of Record, such as sis or hrms. It typically will be assigned by the Match Engine.

API Calls Overview

One may use the Match API to make two types of requests:

  • Standard Request (adding a record for matching) - a request that submits a record from a System of Record for the purposes of adding the record to the set of those matched and returning the result of that match. 
  • Search Request - a requests that does the same as the Standard Request, but does not add the record to matchgrid set. This request type is useful for retrieving the referenceId of an already matched record, if available.

These requests will return one of the following responses:

  • Unique Match Found (200 OK) - A unique match has been found for the records sent with your Request. This response will contain the referenceID for the matched record.

  • New Identifier Assigned (201 Created) - No matches were found for the record sent with your Request. This response will contain the new referenceID that has been assigned to the record sent.
  • Potential Match Found (300 Multiple Choices) - One or more potential matches have been identified for the record sent with your Request. The response will include a list of one or more candidates that are potential matches. This response will be provided when the system of record has been configured with an Interactive Resolution Mode.
  • Potential Match Found - Externally Handled (202 Accepted) - One or more potential matches have been identified for the record sent with your Request. The response will include the matchRequest identifier assigned by the Match Engine. This response will be provided when the system of record has been configured with an External Resolution Mode.
  • Error With Request (400 Bad Request) - Provided when the match engine encounters an error due to the client request, such as failing to submit required attributes, or submitting invalid values.

2. Developer Reference Materials

2.1. Match API Users

COmanage Match supports three types of API Users:

  1. Platform API Users have full access to the API.
  2. Matchgrid API Users have full access to a specific Matchgrid.
  3. System of Record API Users have authority only for records associated with a specific System of Record.

More on the Match API Users Reference page...

2.2. Match Data Model

The COmanage Match Data Model revolves around the Matchgrid, which is a single, dynamically managed table representing matching state.

  • COmanage Match is multi-tenant. Each tenant has its own Matchgrid.
  • Data is loaded into a Matchgrid from one or more Systems of Record (SOR). Each record from an SOR must have a key that is unique across all records from that SOR, this key is referred to as the System of Record Identifier (SORID).
  • Each unique individual identified by COmanage Match is assigned a Reference Identifier. A given Reference Identifier can be associated with one or more SORIDs from one or more SORs.

More on the Data Model Reference page...

3. Advanced Topics

3.1. Endpoint Notification Protocol

When a Pending Match Request is resolved, Match can be configured to send a JSON message to a URL endpoint. This allows automatic business processes to be triggered once a Reconciliation Manager reviews and resolves a Pending Match.

(This Notification protocol is not part of the TAP Match API.)

More on the Endpoint Notification Protocol Reference page...

3.2. Custom Interfaces for Reviewing Pending Match Request

Although authorized users may view and resolve Pending Match requests from within the Match application, the Match API also provides the ability to obtain a list of potential matches that have not been resolved yet, allowing one to create a custom interface for users to resolve these matches.

More on the Match API Reference page...