home

Explore

DiscoverStartExploreModelIntegrateEngage
DiscoverStartExploreModelIntegrateEngage

Accelerate the Value of Data

Show Contents

thumbnailExplore

RDM API

RDM Lookups API

Overview of the RDM Lookups API

The RDM Lookups API allows you to create lookup types that are consistent across industries and applications. You can also list lookup codes by tenant and URIs, scan the database, update and delete Lookup codes, get lookup codes by applying search filters or facet search, and scan the database with filters. Only ROLE_ADMIN_TENANT_{{tenant}} or ROLE_ADMIN_CUSTOMER_{{Customer}} or ROLE_RDM_EDIT has access to these APIs.

Lookup Code Description

{
	"lookupType": "lookupTypes/Country",
	"code": "US",
	"updatedBy": "Sergei.Ionin",
	"updateDate": 123456789,
	"version": 123456789,
	"enabled": true,
	"startDate": 0,
	"endDate": 123456789000,
	"parents": ["rdm/Continent/NA",...],
	"sourceMappings": [{
		"source": "AMS",
		"mappings": [{
			"code": "Am",
			"value": "America",
			"canonicalValue": false
		}, {
			"code": "0341",
			"value": "United States",
			"downStreamDefaultValue": true
		}]
	}, {
		"source": "ABCD",
		"mappings": [{
			"code": "1",
			"value": "United States",
			"canonicalValue": true
		}]
	}],
	"localization": [{
		"languageCode": "fr-ca",
		"value": "Etats-Unis d'Amerique",
		"description": "..."
	}, {
		"languageCode": "es-mx",
		"value": "Estados Unidos de America",
		"description": "..."
	}]
	}

Setting a Default Value

You can set a default value of LoV bounded fields. Use the downStreamDefaultValue property. If set to true, the code and value become the default values for that source. Only one value can be set to true per source.

Note: This is applicable only for reverse transcoding when there are several values/codes for the same source. For more information on reverse transcoding, see Transcode API.
Here is an example of setting the one default value:
"sourceMappings": [
        {
          "source": "Reltio",
          "values": [
            {
              "code": "US",
              "value": "USA",
              "enabled": true,
              "canonicalValue": true,
              "downStreamDefaultValue": true,
              "description": "its description"
            },
...
Example:
[
  {
    "uri": "rdm_tenant_name/Country/US",
    "value": {
      "tenantId": "rdm_tenant_name",
      "updatedBy": "anton.artemyev",
      "updateDate": 1488465334673,
      "version": 3,
      "type": "rdm/lookupTypes/Country",
      "code": "US",
      "enabled": true,
      "sourceMappings": [
        {
          "source": "Reltio",
          "values": [
            {
              "code": "US",
              "value": "USA",
              "enabled": true,
              "canonicalValue": true,
              "downStreamDefaultValue": true,
              "description": "some description"
            },
            {
              "code": "Am",
              "value": "America",
              "enabled": true,
              "canonicalValue": false,
              "downStreamDefaultValue": false
            }
          ]
        },
        {
          "source": "FB",
          "values": [
            {
              "code": "1",
              "value": "United States",
              "enabled": true,
              "canonicalValue": false,
              "downStreamDefaultValue": true
            }
          ]
        }
      ],
      "localizations": [
        {
          "languageCode": "es-mx",
          "value": "Estados Unidos de America",
          "description": "some description"
        },
        {
          "languageCode": "fr-ca",
          "value": "Etats-Unis d'Amerique",
          "description": "..."
        }
      ],
      "parents": [],
      "attributes": [
        {
          "name": "Continent",
          "value": "North America"
        },
        {
          "name": "Population",
          "value": "324947000"
        }
      ],
      "startDate": 0,
      "endDate": 0
    }
  }
]
Table 1. Description
Field Description Create Lookup Value Required
uri Full URI of lookup code. No
value Yes
tenantId RDM tenant name. Yes
updatedBy The user who last made the changes. No
updateDate Date of last update. No
version Current version. No
type Type of Lookup code. Yes
code Lookup code. Yes
enabled No
sourceMappings List of codes and values from different sources. Yes
source Yes
values List of codes and values from one source. Yes
code Lookup code in certain source. Yes
value Lookup value in certain source. Yes
enabled No
canonicalValue Set to true if you want to make this source code and value canonical (but only one canonical may be made per one Lookup code). No
downStreamDefaultValue Set to true if you want to make this code and value for one source default (but only one value may be set true for one source). No
description Some description. No
localization No
languageCode Code of localization. Yes
value Name of this value on this localization. Yes
description No
parents No
attributes List of attribute values with the type of Lookup code. No
name Attribute name. No
value Attribute value. No
startDate No
endDate No

Data API

List lookup codes for tenant

Request: 

GET https://{{rdm-service}}/lookups/rdm_tenant_name
Authorization: Bearer {{token}}

Response: 

[
  {
    "tenantId": "rdm_tenant_name",
    "updatedBy": "anton.artemyev",
    "updateDate": 1488465334673,
    "version": 3,
    "type": "rdm/lookupTypes/Country",
    "code": "US",
    "enabled": true,
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "code": "US",
            "value": "USA",
            "enabled": true,
            "canonicalValue": true,
            "downStreamDefaultValue": true
          },
          {
            "code": "Am",
            "value": "America",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false
          }
        ]
      },
      {
        "source": "FB",
        "values": [
          {
            "code": "1",
            "value": "United States",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": true
          }
        ]
      }
    ],
    "localizations": [
      {
        "languageCode": "es-mx",
        "value": "Estados Unidos de America",
        "description": "some description"
      },
      {
        "languageCode": "fr-ca",
        "value": "Etats-Unis d'Amerique",
        "description": "..."
      }
    ],
    "parents": [],
    "attributes": [
      {
        "name": "Continent",
        "value": "North America"
      },
      {
        "name": "Population",
        "value": "324947000"
      }
    ],
    "startDate": 0,
    "endDate": 0
  },
  {
    "tenantId": "rdm_tenant_name",
    "updatedBy": "anton.artemyev",
    "updateDate": 1488465458384,
    "version": 1,
    "type": "rdm/lookupTypes/State",
    "code": "AR",
    "enabled": true,
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "code": "AR",
            "value": "Arkansas",
            "enabled": true,
            "canonicalValue": true,
            "downStreamDefaultValue": true
          }
        ]
      }
    ],
    "localizations": [],
    "parents": [
      "rdm/lookupTypes/Country/US"
    ],
    "startDate": 0,
    "endDate": 0
  }
]

List lookup codes for tenants by type

Request: 

GET https://{{rdm_uri}}/lookups/rdm_tenant_name/State
Authorization: Bearer {{token}}

Response: 

[
  {
    "tenantId": "rdm_tenant_name",
    "updatedBy": "anton.artemyev",
    "updateDate": 1488465458384,
    "version": 1,
    "type": "rdm/lookupTypes/State",
    "code": "AR",
    "enabled": true,
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "code": "AR",
            "value": "Arkansas",
            "enabled": true,
            "canonicalValue": true,
            "downStreamDefaultValue": true
          }
        ]
      }
    ],
    "localizations": [],
    "parents": [
      "rdm/lookupTypes/Country/US"
    ],
    "attributes": [
      {
        "name": "Population",
        "value": "3000942"
      }
    ],
    "startDate": 0,
    "endDate": 0
  }
]

By URIs

Request: 

POST https://{{rdm_uri}}/lookups/rdm_tenant_name/_byUris
Authorization: Bearer {{token}}
 
{
    "uris" : [
        "rdm_tenant_name/State/AR",
        "rdm_tenant_name/State/CA",
        "rdm_tenant_name/State/KA",
        ...
    ]
}

Response: 

[
  {
    "tenantId": "rdm_tenant_name",
    "updatedBy": "anton.artemyev",
    "updateDate": 1488465458384,
    "version": 1,
    "type": "rdm/lookupTypes/State",
    "code": "AR",
    "enabled": true,
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "code": "AR",
            "value": "Arkansas",
            "enabled": true,
            "canonicalValue": true,
            "downStreamDefaultValue": true
          }
        ]
      }
    ],
    "localizations": [],
    "parents": [
      "rdm/lookupTypes/Country/US"
    ],
    "attributes": [
      {
        "name": "Population",
        "value": "3000942"
      }
    ],
    "startDate": 0,
    "endDate": 0
  },
  ...
]

DB Scan

Request: 

POST https://{{rdm_uri}}/lookups/rdm_tenant_name/_dbscan?limit=100
Authorization: Bearer {{token}}
 
ClwSVmoNcH5wcm9kLTE1NTQyMnIuCxIKT2Z5UkRWYWx1ZSIeYldQUkNMeHNERXhjbnJyL1NwZWNpYWx0eS8xMTg3DKIBFERBVEFfYldQUkNMeHNERXhjbnJyGAAgAA

Response: 

[
  "scrollId": "CokBEoIBag9wfEFfQmlnVGVuYW50NTAwaxgAIAA",
  "values": [
  {
    "tenantId": "rdm_tenant_name",
    "updatedBy": "anton.artemyev",
    "updateDate": 1488465458384,
    "version": 1,
    "type": "rdm/lookupTypes/State",
    "code": "AR",
    "enabled": true,
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "code": "AR",
            "value": "Arkansas",
            "enabled": true,
            "canonicalValue": true,
            "downStreamDefaultValue": true
          }
        ]
      }
    ],
    "localizations": [],
    "parents": [
      "rdm/lookupTypes/Country/US"
    ],
    "attributes": [
      {
        "name": "Population",
        "value": "3000942"
      }
    ],
    "startDate": 0,
    "endDate": 0
  }
 ]
]

Create Lookup Code

Request (for one type): 

POST https://{{rdm-service}}/lookups/rdm_tenant_name/State
Authorization: Bearer {{token}}
[
  {
    "tenantId": "rdm_tenant_name",
    "enabled": true,
    "code": "AR",
    "type": "rdm/lookupTypes/State",
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "code": "AR",
            "value": "Arkansas",
            "enabled": true
          }
        ]
      }
    ],
    "localizations": [],
    "parents": [
        "rdm/lookupTypes/Country/US"
    ],
    "attributes": [
      {
        "name": "Population",
        "value": "3000942"
      }
    ]
  },
    ...(max 100 codes in one request)...
]

Request (Different Types): 

POST https://{{rdm-service}}/lookups/rdm_tenant_name
Authorization: Bearer {{token}}
[
  {
    "tenantId": "rdm_tenant_name",
    "enabled": true,
    "code": "AR",
    "type": "rdm/lookupTypes/State",
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "code": "AR",
            "value": "Arkansas",
            "enabled": true
          }
        ]
      }
    ],
    "localizations": [],
    "parents": [
        "rdm/lookupTypes/Country/US"
    ],
    "attributes": [
      {
        "name": "Population",
        "value": "3000942"
      }
    ]
  },
    ...(max 100 codes in one request)...
]

Response: 

  [
  {
    "uri": "rdm_tenant_name/State/AR",
    "value": {
      "tenantId": "rdm_tenant_name",
      "updatedBy": "anton.artemyev",
      "updateDate": 1488465740166,
      "version": 3,
      "type": "rdm/lookupTypes/State",
      "code": "AR",
      "enabled": true,
      "sourceMappings": [
        {
          "source": "Reltio",
          "values": [
            {
              "code": "AR",
              "value": "Arkansas",
              "enabled": true,
              "canonicalValue": true,
              "downStreamDefaultValue": true
            }
          ]
        }
      ],
      "localizations": [],
      "parents": [
        "rdm/lookupTypes/Country/US"
      ],
      "attributes": [
        {
          "name": "Population",
          "value": "3000942"
        }
      ],
      "startDate": 0,
      "endDate": 0
    }
  }
],
...

Get Lookup Code

Request: 

GET https://{{rdm-service}}/lookups/rdm_tenant_name/State/AR
Authorization: Bearer {{token}}

Response: 

{
  "tenantId": "rdm_tenant_name",
  "updatedBy": "anton.artemyev",
  "updateDate": 1488465740166,
  "version": 3,
  "type": "rdm/lookupTypes/State",
  "code": "AR",
  "enabled": true,
  "sourceMappings": [
    {
      "source": "Reltio",
      "values": [
        {
          "code": "AR",
          "value": "Arkansas",
          "enabled": true,
          "canonicalValue": true,
          "downStreamDefaultValue": true
        }
      ]
    }
  ],
  "localizations": [],
  "parents": [
    "rdm/lookupTypes/Country/US"
  ],
  "attributes": [
    {
      "name": "Population",
      "value": "3000942"
    }
  ],
  "startDate": 0,
  "endDate": 0
}

Search Filters

Max 1000 results (GAE limitation)

Request
GET https://{{rdm-service}}/lookups/rdm_tenant_name?filter=equals(type,'State')&sort=code&order=asc
Authorization: Bearer {{token}}
Table 2. Search Filter Properties
Filter Properties Description
type Lookup type name
code Lookup code
value Canonical value
enabled Enabled/disabled flag
updateDate last lookup update date
updatedBy The user who last made the changes.
version Current version
startDate Lookup code start date
endDate Lookup code end date
localization localized value
sourceMappings.source Source system in mappings
sourceMappings.values.code Source code in mappings
sourceMappings.values.value Source value in mappings
localizations.languageCode Language code in localizations
localizations.value Localized value in localizations
attributes.name Attribute name
attributes.value Attribute value

Sorting

Same properties as for search filter.

Ordering
Table 3. Ordering
Order Description
asc A to Z, 0 to 9
desc Z to A, 9 to 0
Table 4. Filter Operators
Filter Operators Description
equals(property, value) exact match condition ignoring case
fullText(property, value) combines results into the overall result. Any entity whose title field contains at least one of the specified terms will match the query. The more terms that match, the more relevant the entity
startsWith(property, stricted value) prefix condition; returns entities that have condition property starting with condition value
contains(property, tokenized value)

prefix condition; returns entities that have condition property starting with condition value
lt(property, value) 'less than' condition
lte(property, value) 'less than or equals' condition
gt(property, value) 'greater than' condition
gte(property, value) 'greater than' or equals condition
missing(property) returns entities with fields that have no values for 'property' or 'property' value is empty
exists(property)

returns entities having some value for 'property'
inSameAttributeValue (subquery on sourceMappings/localizations/attributes) Returns the entities that have all values matching to subquery in one single sourceMappings, localizations, or attributes value.
Note: The subquery supports all operands except inSameAttributeValue. All these operands must have sub attributes of one sourceMappings/localizations/attributes value.

For example, sub attribute from type and sourceMappings.source cannot be used inside one inSameAttributeValue query.

Example:

filter=inSameAttributeValue(equals(sourceMappings.source,”Salesforce”) AND equals(sourceMappings.values.value, “United States”))

Filter by localized values

Filter operators for localization property take language from Accept-Language HTTP header and apply this operators to values from localizations of lookups for specified language.

The following query is used to get lookups:

filter=equals(localizations.languageCode,'en-us') OR contains(localizations.value,'United'))
filter=inSameAttributeValue(equals(localizations.languageCode,'en-us') AND equals(localizations.value,'USA')))

Scan with Filter

Request: 
POST https://{{rdm_uri}}/lookups/rdm_tenant_name/_scan?limit=100&filter=equals(type,'State')&sort=code&order=asc
Authorization: Bearer {{token}}
 
{{scroll_id}}
Response: 
[
  "scrollId": "CokBEoIBag9wfEFfQmlnVGVuYW50NTAwaxgAIAA",
  "values": [
  {
    "tenantId": "rdm_tenant_name",
    "updatedBy": "anton.artemyev",
    "updateDate": 1488465458384,
    "version": 1,
    "type": "rdm/lookupTypes/State",
    "code": "AR",
    "enabled": true,
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "code": "AR",
            "value": "Arkansas",
            "enabled": true,
            "canonicalValue": true,
            "downStreamDefaultValue": true
          }
        ]
      }
    ],
    "localizations": [],
    "parents": [
      "rdm/lookupTypes/Country/US"
    ],
    "attributes": [
      {
        "name": "Population",
        "value": "3000942"
      }
    ],
    "startDate": 0,
    "endDate": 0
  }
 ]
]

Facet Search

Facet search calculates the number of searched records for lookups.

Request
GET https://{{rdm_uri}}/unmapped/rdm_tenant_name/_facets?facet=source&filter=equals(type,'State')
Authorization: Bearer {{token}}
Table 5. Parameters
Name Required Description
facet No Comma-separated list of facets to return. If this parameter is not specified, then all the facets will be returned.

The available facets are - source and type.
filter No

Support all filter functions and operators as described above.
max No The number of terms to return. The default value is 0.
Response 
{
  "source": {
    "Reltio": 1624,
    "Salesforce": 379,
    "Global": 621,
  },
  "type": {
    "rdm/lookupTypes/Country": 253,
    "rdm/lookupTypes/State": 987
  }
}

Update Lookup Code

Request: 

PUT https://{{rdm-service}}/lookups/rdm_tenant_name/State/AR
Authorization: Bearer {{token}}
{
    "tenantId": "rdm_tenant_name",
    "enabled": true,
    "code": "AR",
    "type": "rdm/lookupTypes/State",
    "sourceMappings": [
      {
        "source": "Reltio",
        "values": [
          {
            "code": "AR",
            "value": "Arkansas",
            "enabled": true
          }
        ]
      },
      {
        "source": "FB",
        "values": [
          {
            "code": "AR",
            "value": "Arkansas",
            "enabled": true
          }
        ]
      }
    ],
    "localizations": [],
    "parents": [
        "rdm/lookupTypes/Country/US"
    ]
  }

Response: 

{
  "tenantId": "rdm_tenant_name",
  "updatedBy": "anton.artemyev",
  "updateDate": 1488466088624,
  "version": 6,
  "type": "rdm/lookupTypes/State",
  "code": "AR",
  "enabled": true,
  "sourceMappings": [
    {
      "source": "Reltio",
      "values": [
        {
          "code": "AR",
          "value": "Arkansas",
          "enabled": true,
          "canonicalValue": true,
          "downStreamDefaultValue": true
        }
      ]
    },
    {
      "source": "FB",
      "values": [
        {
          "code": "AR",
          "value": "Arkansas",
          "enabled": true,
          "canonicalValue": false,
          "downStreamDefaultValue": true
        }
      ]
    }
  ],
  "localizations": [],
  "parents": [
    "rdm/lookupTypes/Country/US"
  ],
  "startDate": 0,
  "endDate": 0
}

Delete Lookups by URIs

Use this to delete lookups by their URIs (maximum number of URIs that can be deleted is 1000). The response contains an array of results for each URI, where the "success" status indicates that the lookups are either deleted successfully or do not exist. In case of an error, an error object is returned.

Request: 

POST https://{{rdm_uri}}/lookups/rdm_tenant_name/_delete
Authorization: Bearer {{token}}
 
{
    "uris" : [
        "rdm_tenant_name/State/AR",
        "rdm_tenant_name/State/CA",
        "rdm_tenant_name/State/KA",
        ...
    ]
}

Response: 

[
    {
        "uri": "rdm_tenant_name/State/AR",
        "value": {
            "status" : "success"
        }
    },
    {
        "uri": "rdm_tenant_name/State/CA",
        "value": {
            "status" : "success"
        }
    },
    {
        "uri": "rdm_tenant_name/State/KA",
        "value": {
            "status" : "success"
        }
    },
    ...
]

Delete Lookup Code

Use this to delete a lookup by its type and code. The response returns the "success" status if the lookup is deleted successfully or it does not exist. In case of an error, an error object is returned.

Request: 

DELETE https://{{rdm-service}}/lookups/rdm_tenant_name/State/AR
Authorization: Bearer {{token}}

Response: 

{ 
"status" : "success"
}

Updated on December 14, 2022

Footer

You've found your way to a temporary environment. Content is not complete or final. Looking for Reltio documentation? Go to docs.reltio.com.

Company

Leadership

Careers

Awards

Contact Us

Reltio Newsroom

Press Releases

Media Coverage

Media & Analyst Resources

Customer Support

Support

Reltio Learn

Community

Developer Portal

100 Marine Parkway, Suite 275

Redwood Shores, CA 94065

USA

North America: +1(855)360-3282

Europe: +44(800)368-7643

Email: sales@reltio.com

© 2022-2024 Reltio Intellectual Property. All rights reserved.

Terms, Policies & Cookie Preferences