Realtime APIs

4.11 Realtime APIs

This topic combines the Authentication, Match Columns, Realtime Matching, and Realtime GID Generation APIs into a single reference.

Authentication API

The authentication API allows an approved third-party system to obtain a short-lived bearer token. The token must be included when calling protected ER Service APIs.

Table 4-5 Endpoint

Property	Value
Method	POST
Path	`/auth/rtToken`
Full URL	`http://<er-service-host>:<port>/auth/rtToken`
Content Type	`application/json`

Table 4-6 Request Headers

Header	Required	Description
Content-Type	Yes	Must be application/json.
Accept	Recommended	Use application/json to request JSON response format.

Table 4-7 Request Body

Field	Type	Required	Description
clientId	String	Yes	Client identity assigned during onboarding. Example: `BATCH_USER`.
username	String	Yes	Consumer user or system user associated with the token request.

{
  "clientId": "BATCH_USER",
  "username": "testuser"
}

Sample Request

POST http://<er-service-host>:<port>/auth/rtToken
Content-Type: application/json
Accept: application/json

{
  "clientId": "BATCH_USER",
  "username": "testuser"
}

Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tokenType": "Bearer",
  "accessToken": "<access-token>",
  "clientId": "BATCH_USER",
  "username": "testuser",
  "expiresAt": "2026-06-09T10:15:00Z",
  "expiresInSeconds": 86400
}

Table 4-8 Success Response

Field	Description
tokenType	Token scheme. Consumers must send the token as Authorization: Bearer <access-token>.
accessToken	The issued access token. Treat this value as a secret.
clientId	Client identity for which the token was issued.
username	Username for which the token was issued.
expiresAt	Timestamp after which the token is no longer valid.
expiresInSeconds	Token lifetime remaining at issue time, expressed in seconds.

Table 4-9 Error Responses

Scenario	HTTP Status	Example Body	Consumer Action
Invalid request or missing required field	400 Bad Request	{"status":"BAD_REQUEST","message":"Invalid token request"}	Correct request body and retry.
Unauthorized or unrecognized client identity	400 Bad Request	{"status":"BAD_REQUEST","message":"Invalid token request"}	Verify assigned clientId with ER Service onboarding team.
Internal error	500 Internal Server Error	{"status":"ERROR","message":"Unable to process request"}	Retry later if appropriate; escalate if repeated.

Match Columns API

This API allows an approved third-party system to retrieve the matching input columns configured for a selected matching rule set. The API accepts a ruleSetId and returns each configured ruleId, ruleName, and the list of attributes. Users should call this API before invoking the Realtime Matching API so they know which column names must be included in the searchString request object.

Table 4-10 Endpoint

Property	Value
API Name	Realtime Rule Columns API
Method	GET
Path	`/realTimeMatching/columns`
Full URL	`http://<er-service-host>:<port>/realtimematching/columns?ruleSetId=<ruleSetId>`
Content Type	application/json

Pre-Requisites

Matching ruleset must be created
The selected rule set must be available for realtime matching.
Entity-resolution must be configured with the matchingServiceOt.url value in ##OFS_COMPLIANCE_STUDIO_INSTALLATION_HOME##/deployed/entity-resolution/conf/application.yml

Table 4-11 Request Parameter

Field	Type	Required	Description
ruleSetId	String	Yes	Matching rule set identifier from FCC_MATCH_RULESET. The API uses this value to retrieve rule configuration from V_QUERY_JSON.

Sample Request

GET http://<er-service-host>:<port>/realTimeMatching/columns?ruleSetId=2066 
Accept: application/json

Success Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "ruleId": 1781097703,
    "ruleName": "Name and Email Match",
    "indexCols": [
      "concat_name",
      "email",
      "incorporation_date"
    ]
  },
  {
    "ruleId": 1781097706,
    "ruleName": "Name and Address Match",
    "indexCols": [
      "concat_name",
      "address",
      "country",
      "city",
      "incorporation_date"
    ]
  }
]

Table 4-12 Success Response

Field	Description
`ruleId`	Rule identifier configured within the selected rule set.
`ruleName`	Business name of the matching rule.
`indexCols`	List of column names configured in the rule’s indexCols array. These columns should be used to prepare the searchString object for realtime matching.

Table 4-13 Error Responses

Scenario	HTTP Status	Example Body	User Action
Missing ruleSetId	400 Bad Request	Error body may vary by gateway/framework.	Provide a valid ruleSetId query parameter.
Invalid or unavailable ruleSetId	500 Internal Server Error or failed response	{"status":"FAILED","message":"RuleSet not found"}	Verify that the rule set exists in FCC_MATCH_RULESET
Invalid V_QUERY_JSON configuration	500 Internal Server Error or failed response	{"status":"FAILED","message":"Unable to parse rule JSON"}	Correct the rule configuration and retry.
Internal processing error	500 Internal Server Error	{"status":"FAILED","message":"Processing failed: <reason>"}	Retry only when appropriate; escalate with ruleSetId and timestamp.

Realtime Matching API

The Realtime Matching API allows an approved third-party system to submit party attribute values and receive realtime candidate matches based on a configured ER matching rule set. The API accepts additionalRequestDetails, ruleSetId, and searchString. The request is received by entity-resolution and returns candidate match details.

Table 4-14 Endpoint

Property	Value
API Name	Realtime Matching API
Method	POST
Path	/realTimeMatching
Full URL	http://<er-service-host>:<port>/realTimeMatching
Invocation Type	Synchronous / Real-Time
Input	Rule set, ER schema details, and search values
Output	Candidate matches, scores, rule metadata, global ID, and processing status
Content Type	application/json

Pre-Requisites

At least one ER batch execution should have created and stored matching rules in FCC_MATCH_RULESET.

Table 4-15 Required Headers

Header	Required	Example	Description
Content-Type	Yes	application/json	Request body format.
Accept	Recommended	application/json	Expected response format.
Authorization	Yes	Bearer <access-token>	Bearer token returned by the authentication API.
X-ER-Client-Id	Yes	BATCH_USER	Client identity associated with the issued token.
X-ER-Username	Yes	testuser	Username associated with the issued token.

Table 4-16 Request Body

Field	Type	Required	Description
`additionalRequestDetails`	Object	Yes	Contains ER schema connection details used for realtime matching execution.
`additionalRequestDetails.walletAlias`	String	Yes	Wallet alias for the ER schema that contains the real-time matching procedures.
`additionalRequestDetails.walletPath`	String	Conditional	Wallet path for the ER schema. Required only when the alias is not already available in the configured wallet path.
`additionalRequestDetails.tnsPath`	String	Conditional	TNS path for the ER schema. Required only when the alias is not already available in the configured wallet path.
`ruleSetId`	String	Yes	Matching rule set identifier from FCC_MATCH_RULESET.
`searchString`	Object	Yes	JSON object containing search values for the distinct columns returned by the Rule Columns API. Each key is a column name, and each value is an array.

Sample Request

POST http://<er-service-host>:<port>/realTimeMatching
Authorization: Bearer <access-token>
X-ER-Client-Id: BATCH_USER
X-ER-Username: testuser
Content-Type: application/json
Accept: application/json

{
  "additionalRequestDetails": {
    "walletAlias": "ER_SP_8131",
    "walletPath": "/scratch/appuser/OFS_COMPLIANCE_STUDIO/wallet",
    "tnsPath": "/scratch/appuser/OFS_COMPLIANCE_STUDIO/wallet"
  },
  "ruleSetId": "2066",
  "searchString": {
    "concat_name": ["Isabelle Grant"],
    "email": [],
    "incorporation_date": [],
    "doc_id": [],
    "phone": [],
    "address": ["75 Bridge Street"],
    "country": ["USA"],
    "city": ["Gorran Churchtown"],
    "postal_code": ["4564"]
  }
}

Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "SUCCESS",
  "message": "Result size for RuleSet (2066): 1",
  "matches": [
    {
      "finalScore": 95.0,
      "indexName": "FCC_ER_FULL_OT",
      "id": "CU-CSS-0000000214",
      "globalId": "G1000000137",
      "ruleId": 1781097706,
      "ruleName": "Name and Address Match",
      "ruleSetId": "2066",
      "matchCols": [
        {
          "searchString": "isabelle grant",
          "colName": "concat_name",
          "colValue": "Isabelle Grant",
          "searchType": "fuzzy",
          "score": 100.0,
          "scoringMethod": "mlboostednamematching"
        }
      ],
      "additionalInfo": [
        {
          "field": "jurisdiction",
          "value": "AMEA"
        }
      ]
    }
  ],
  "id": "2066",
  "ruleId": 0,
  "runSkey": "183"
}

Table 4-17 Success Response

Field	Description
status	Processing status. SUCCESS indicates the realtime matching request completed.
message	Human-readable processing summary, including result size when available.
matches	List of candidate matches returned by the matching process.
matches.finalScore	Final score assigned to the matched candidate.
matches.indexName	Table name on which domain index is created.
matches.id	Candidate record identifier.
matches.globalId	Global ID associated with the matched candidate, when available.
matches.ruleId	Rule identifier that produced the match.
matches.ruleName	Rule name that produced the match.
matches.ruleSetId	Rule set identifier used for matching.
matches.matchCols	Column-level match details.
matches.matchCols.colName	Column on which the match was evaluated.
matches.matchCols.searchString	Search value submitted for the column.
matches.matchCols.colValue	Candidate value matched against the submitted search value.
matches.matchCols.searchType	Matching type, such as exact or fuzzy.
matches.matchCols.score	Score for the individual column match.
matches.matchCols.scoringMethod	Scoring method used for the column, where applicable.
matches.additionalInfo	Additional configured fields returned with the candidate.
id	Rule set identifier echoed in the response.
runSkey	Runtime execution key generated for the realtime matching request.

GID Generation API

The Realtime GID Generation API enables real-time generation of a Global ID (GID) for new parties in the Entity Resolution system when no matching entity is identified. The API is protected and requires a valid bearer token.

Table 4-18 Endpoint

Property	Value
API Name	Realtime GID Generation API
Method	`POST`
Path	`/realTimeMapping/generateGID`
Full URL	`http://<er-service-host>:<port>/realTimeMapping/generateGID`
Invocation Type	Synchronous / Real-Time
Input	Party and ER pipeline details
Output	Generated Global ID and processing status
Content Type	application/json

Key Assumptions

The party does not already exist in the Entity Resolution repository.
A real-time search has already been performed and no matches were found.
Party information is pre-populated before API invocation.
The source system provides a unique Party ID.

Pre-Requisites

Required party data must be available in the staging/pre-processing layer.
The party must exist in STG_PARTY_MASTER_PRE for that successful batch's FIC_MIS_DATE.
Appropriate API authentication and authorization must be configured.
Specify that at least one successful ER batch is required for the supplied processingGroupName.

Authentication Requirements

A token must be obtained from POST /auth/rtToken before calling this API.
The token must be supplied in the Authorization header using the Bearer scheme.
The X-ER-Client-Id header must match the client identity used when the token was issued.
The X-ER-Username header must match the username used when the token was issued.
If the token is expired, replaced, malformed, missing, or mismatched, the GID flow is not executed.

Table 4-19 Required Headers

Header	Required	Example	Description
Authorization	Yes	Bearer <access-token>	Bearer token returned by the Authentication API.
X-ER-Client-Id	Yes	BATCH_USER	Client identity associated with the issued token.
X-ER-Username	Yes	testuser	Username associated with the issued token
Content-Type	Yes	application/json	Request body format.
Accept	Recommended	application/json	Expected response format.

Table 4-20 Request Body

Field	Type	Required	Description
partyId	String	Yes	Party identifier for which a GID is requested.
erModelVersion	String	Yes	ER model or FSDF version applicable to the request.
pipelineId	String	Yes	Pipeline identifier used for the ER processing context.
processingGroupName	String	Yes	Processing group or batch group name.
erSchemaWalletAlias	String	Yes	ER schema wallet alias configured for the target environment.
erSchemaWalletPath	String	Yes	Wallet path configured for the target environment.
erSchemaTnsPath	String	Yes	TNS path configured for the target environment.

Sample Request

POST http://<er-service-host>:<port>/realTimeMapping/generateGID
Authorization: Bearer <access-token>
X-ER-Client-Id: BATCH_USER
X-ER-Username: testuser
Content-Type: application/json
Accept: application/json

{
   "partyId": "CU-CSS-GHI7",
  "erModelVersion": "813",
  "pipelineId": "CSA_813",
  "processingGroupName": "CSA_812",
  "erSchemaWalletAlias": "ER_SCHEMA_ALIAS",
  "erSchemaWalletPath": "/path/to/wallet",
  "erSchemaTnsPath": "/path/to/tns"
}

Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "requestId": "REQ_20260609_103000_123_1f2e3d4c5b6a7890abcdef1234567890",
  "partyId": "CU-CSS-GHI7",
  "status": "SUCCESS",
  "errorCode": null,
  "message": "Global ID generated successfully",
  "globalId": "GID_100001"
}

Table 4-21 Success Response

Field	Description
requestId	Unique identifier assigned to the GID request. Use this for support and reconciliation.
partyId	Party identifier submitted in the request.
status	Processing status. SUCCESS indicates GID generation completed.
errorCode	Error code when applicable; null or absent for successful processing.
message	Human-readable processing result.
globalId	Generated Global Identifier. Present when GID generation succeeds.

Table 4-22 Error Responses

Scenario	HTTP Status	Example Body	User Action
Missing token	401 Unauthorized	{"status":"UNAUTHORIZED","message":"Authentication failed"}	Obtain a token and resend request.
Invalid, expired, malformed, or replaced token	401 Unauthorized	{"status":"UNAUTHORIZED","message":"Authentication failed"}	Request a new token and retry.
Mismatched clientId or username	403 Forbidden	{"status":"FORBIDDEN","message":"Access denied"}	Use the same clientId and username used to obtain the token.
Missing required payload field	200 OK	{"status":"FAILED_PREVALIDATION","message":"Party Id received is null"}	Correct the request payload and retry.
Malformed JSON	400 Bad Request	Error body may vary by gateway/framework.	Correct JSON syntax.
Unsupported media type	415 Unsupported Media Type	Error body may vary by gateway/framework.	Send Content-Type: application/json.
Internal processing error	500 Internal Server Error	{"status":"FAILED","message":"Processing failed: <reason>"}	Retry only when appropriate; contact Support with requestId.
Party already processed	200 OK	{"status":"FAILED_ALREADY_PROCESSED","errorCode":"FAILED_ALREADY_PROCESSED","message":"Party already processed"}	Verify the party’s existing GID before sending another request.
Party processing already in progress	200 OK	{"status":"PARTY_PROCESSING_IN_PROGRESS","errorCode":"PARTY_PROCESSING_IN_PROGRESS","message":"Party processing is already in progress"}	Wait for the current request to finish before retrying.
GID generation failed before any generation step	500 Internal Server Error	{"status":"FAILED_GID_GENERATION","errorCode":"FAILED_GID_GENERATION","message":"P_MASTER_RT_MAPPING failed before executing any GID generation step"}	Contact Support with the requestId to identify the cause before retrying.
Processing failed; rollback completed	500 Internal Server Error	{"status":"FAILED_ROLLBACK_DONE","errorCode":"FAILED_ROLLBACK_DONE","message":"Processing failed: <reason>"}	Resolve the reported cause before retrying.
Rollback failed or remains pending	500 Internal Server Error	{"status":"FAILED_ROLLBACK_PENDING","errorCode":"FAILED_ROLLBACK_PENDING","message":"Previous rollback must complete before a new GID generation request can proceed"}	Contact Support with the requestId. Retry after rollback is completed.
Rollback completed; status update failed	500 Internal Server Error	{"status":"ROLLBACK_UNKNOWN","errorCode":"ROLLBACK_UNKNOWN","message":"Previous rollback completed but request status update failed"}	Contact Support with the requestId to verify the request state before retrying.

Failure Response

{
"requestId": "REQ_1750000000000_a1b2c3d4e5f6478899aa001122334455",
"status": "FAILED_PREVALIDATION",
"partyId": "P123456789",
"errorCode": "FAILED_PREVALIDATION",
"message": "Required party information is missing"
}

Parent topic: Entity Resolution