Transcode API
API to transcode lookup values
Most of the time reference data is standardized before being imported or used by enterprise systems or applications. However, some data elements are represented differently in different applications. These differences can cause problems when different systems or applications interact. Reltio's Transcoding APIs can be used to convert the source system data to canonical (standardized) values before bringing in this data into Reltio. You can transcode simple and hierarchical lookups. In addition, reverse transcoding can be performed.
Transcode Simple Lookup
Request
To transcode a simple lookup value, send a POST request with the lookup type, value, and source system as shown below.
POST https://{{rdm-service}}/transcode/rdm_tenant_name/value
Authorization: Bearer {{token}}
{
"type": "rdm/lookupTypes/State",
"value": "AR",
"source": "rdm/sources/Reltio"
}Response
On success, the API returns the canonical value corresponding to the provided source value, along with a success flag confirming the transcoding result.
{
"type": "rdm/lookupTypes/State",
"code": "AR",
"value": "Arkansas",
"source": "rdm/sources/Reltio",
"success": true
}Transcode Hierarchical Lookups
The Transcode API resolves a parent lookup (such as Country) alongside one or more dependent child lookups (such as State) in a single request. The response preserves the parent-child relationship between the values.
Request
To transcode hierarchical lookups, send a POST request that includes both the parent lookup values and their dependent child lookup values in a nested structure.
POST https://{{rdm-service}}/transcode/rdm_tenant_name
Authorization: Bearer {{token}}
[
{
"values": {
"rdm/lookupTypes/Country": [
{
"value": "US",
"source": "rdm/sources/Reltio"
}
]
},
"dependentValues": [
{
"values": {
"rdm/lookupTypes/State": [
{
"value": "AR",
"source": "rdm/sources/Reltio"
}
]
}
}
]
}
]Response
The API returns the resolved canonical values for both the parent and child lookups, maintaining the original hierarchical structure in the response.
[
{
"values": {
"rdm/lookupTypes/Country": [
{
"code": "US",
"value": "USA",
"source": "rdm/sources/Reltio",
"success": true
}
]
},
"dependentValues": [
{
"values": {
"rdm/lookupTypes/State": [
{
"code": "AR",
"value": "Arkansas",
"source": "rdm/sources/Reltio",
"success": true
}
]
}
}
]
}
]How parent child validation works
When the transcode engine resolves a hierarchical request, its validation logic enforces three specific characteristics that deviate from the default resolution behavior:
- Source is not used for parent-child validation : The source system of the child value (for example,
BFO) and the source system of the parent value (for example,Planon) are not correlated during validation. The engine validates the parent-child relationship using canonical codes of resolved parent values only, not the source systems they came from. - There is no row-level pairing : The engine does not pair individual parent rows with individual child rows. Instead, all successfully resolved parent values of the same lookup type are collapsed into a single set of canonical codes. If the child value's resolved canonical code is a valid child of any canonical code in that set, the child resolves successfully.
- Cross-source resolution is by design: When multiple source systems contribute values for a parent lookup type, RDM checks whether at least one resolved parent canonical code is a valid parent for the requested child value. If so, the child resolves successfully. RDM does not return a lookup error, even when the resolved parent and child originate from different source systems.
The following example shows how the API resolves parent lookup values first and then evaluates dependent child values in that parent context. In this example, the parent lookup type is Country, and the dependent child lookup type is State. The canonical code IN is the parent of the canonical code KL, so the value Kerala resolves successfully when it is evaluated under that parent relationship. By contrast, Keralam is defined with no parent, so it does not match the parent-child mapping in this example.
Example Request
The following request example shows the parent lookup values and dependent child values sent to the API for hierarchical transcoding.
POST https://{{RdmApiUrl}}/transcode/{{RdmTenant}}
Authorization: Bearer {{token}}
[
{
"values": {
"rdm/lookupTypes/Country": [
{
"type": "rdm/lookupTypes/Country",
"value": "India",
"source": "SAP"
},
{
"type": "rdm/lookupTypes/Country",
"value": "Bharath",
"source": "OKTA"
}
],
"dependentValues": [
{
"values": {
"rdm/lookupTypes/State": [
{
"type": "rdm/lookupTypes/State",
"value": "Keralam",
"source": "SAP"
},
{
"type": "rdm/lookupTypes/State",
"value": "Kerala",
"source": "OKTA"
}
]
}
}
]
}
}
]Example Response
The following response example shows how the API returns the resolved parent lookup values and the evaluated dependent child values based on the parent-child mapping.
[
{
"values": {
"rdm/lookupTypes/Country": [
{
"code": "IN",
"value": "India",
"source": "rdm/sources/SAP",
"success": true
},
{
"code": "BH",
"value": "Bharath",
"source": "rdm/sources/OKTA",
"success": true
}
]
},
"dependentValues": [
{
"values": {
"rdm/lookupTypes/State": [
{
"error": "1003: RDM canonical value mapping not found for value [Keralam] and source [SAP] in tenant [RDM_tenantId]",
"value": "Keralam",
"source": "rdm/sources/SAP",
"success": false
},
{
"code": "KL",
"value": "Kerala",
"source": "rdm/sources/OKTA",
"success": true
}
]
}
}
]
}
]Reverse Transcoding
Reverse transcoding is applied using Transcode
API, with &targetSource=AHA in request parameters.
targetSource is not specified or contains a non-existing source system,
API request will return a canonical value.Request
To perform reverse transcoding, send a POST request with the targetSource query parameter specifying the target source system, along with the lookup type and value to be transcoded.
POST {{rdm_uri}}/transcode/{{rdm_tenant}}/value?targetSource=AHA
HEADERS:
Accept-Language: es-mx
BODY:
{
"type": "rdm/lookupTypes/Country",
"value": "US",
"source": "rmd/sources/Reltio"
}Response
The API returns the value translated into the target source system's representation, including the corresponding code and a success flag indicating a successful reverse transcode.
{
"type": "rdm/lookupTypes/Country",
"code": "080",
"value": "USA",
"source": "rdm/sources/Reltio",
"success": true
}