The Data Dictionary

Retrieve the Data Dictionary

You can retrieve the entire contents of the Data Dictionary in a single call, or you can specify a list of specific data elements you wish to retrieve from the Data Dictionary.

Retrieve all

To retrieve an array of all data elements within the Data Dictionary, send a GET request to the Retrieve Data Element Definitions URL:
https://<<hostName>>/api/v1/commons/data_dictionary/data_elements

This operation provides a summarized view of each data element's definition, structured as shown:

{
  "key": "PEOPLE_HIRE_DATE",
  "label": "Hire Date",
  "metadata": {
    "description": "Hire Date",
    "views": [
      0
    ],
    "dataType": "DATE",
    "displayPolicy": {
      "sort": "DEFAULT",
      "format": "LONGDATE"
    },
    "entity": "PEOPLE",
    "licenses": [
      "DEFAULT"
    ],
    "facp": [
      "HIRE_DATE:VIEW"
    ]
  },
  "active": true
}

Notes of interest

• key is a unique ID that maps to the keys passed in the select array in the Retrieve Data operation:

{
  "select": [
    {
      "key": "PEOPLE_HIRE_DATE"
    },
    {
      "key": "EMP_COMMON_FULL_NAME"
    }
  ]
}

• When parameterized appears in the metadata object, it indicates that the data element requires properties to be specified when it is invoked by a Retrieve Data call. The parameterized property only appears in the Data Dictionary JSON response when it is true. Parameterized data elements are structured as shown:

{
  "key": "LOCATION_NAME",
  "label": "Location Name",
  "metadata": {
    "description": "Location Name",
    "views": [
      1
    ],
    "dataType": "STRING",
    "displayPolicy": {
      "sort": "DEFAULT",
      "round": 6,
      "scale": 0,
      "format": "DEFAULT"
    },
    "entity": "LOCATION",
    "parameterized": true,
    "licenses": [
      "DEFAULT"
    ]
  },
  "active": true,
  "properties": [
    {
      "key": "0",
      "value": "Company"
    },
    {
      "key": "54",
      "value": "Country"
    },
    {
      "key": "4",
      "value": "Business"
    },
    ...
    {
      "key": "-999",
      "value": "EMPLOYEE"
    }
  ]
}

• Refer to the Resource Details of the Retrieve Data Element Definitions GET /v1/commons/data_dictionary/data_elements operation for descriptions of each object, array, and property.

Retrieve by key

When you have already identified a list of data elements, you can POST a call to the Retrieve Data Element Definitions by Keys URL to retrieve only those elements:
https://<<hostName>>/api/v1/commons/data_dictionary/data_elements/multi_read

Include keys for all of the desired data elements in the request body:

[
  "LOCATION_ADDRESS","LOCATION_NAME"
]

The response schema is identical to the Retrieve Data Element Definitions response schema defined in Retrieve all.

Next steps

Once you retrieve the Data Dictionary:

1. Parse the Data Dictionary for the keys needed to construct your Retrieve Data request.
2. For every call you build, retrieve the appropriate property keys for all parameterized data elements to incorporate into your call.

To learn more about using Data Dictionary keys to build basic Dataview-like queries using the Retrieve Data operation, proceed to the Employee-based queries topic.