External, Internal & Unique IDs

Most elements in Core, such as objects, fields, reports, relationships, and configuration elements, are assigned an internal ID and an external reference ID, which represents these elements in the API when making calls. Some elements, like fields and object types, are also assigned a unique ID, which helps end-users identify them in Core.

Because external reference IDs don't change when moving them from one org to another, it's recommended that external reference IDs are used when testing and working with an integration, using the following approach: 

1. Write the integration using the retrieved external reference IDs.
2. Retrieve the object type data and store it.
3. If object types' internal IDs are necessary for a particular endpoint, cross-reference them using the external reference IDs.

See the sections below for more detailed information on internal IDs and external reference IDs.

Internal IDs

• Intended for internal use.
• Created for most elements within Core.
• Automatically assigned.
• Numeric.
• Cannot be modified.
• Visible in Swagger and the URL when viewing associated admin settings in Core.

An object type's internal ID in the URL.

External Reference IDs

• Also known as external ref IDs.
• Created for most elements within Core.
• Alphanumeric.
• Unique within your org.
• Can only be modified from Swagger.

Object External Reference IDs

• Intended for cross-referencing records with external systems.
• Automatically assigned a unique MD5 hash when created in Core.
• Imported objects must be assigned a new external reference ID upon import.
• Can be retrieved from Swagger or from the External Reference ID property on a report table.

Configuration Element External Reference IDs

• Intended to maintain the relationships between configuration components across multiple orgs with the same configuration (i.e., sandboxes and production orgs).
• Automatically assigned when created.
• Preserved when exporting and importing a configuration file from one org to another, but assigned a new internal ID upon import.
• Visible only in Swagger.

Examples

 GET  /object/report

{
  "data": [
    {
      "id": 9017, <--Report internal ID
      "name": "Risks & Controls By Location",
      "description": "",
      "nameKey": "app:report:name:820c6f98-b82d-496f-9df2-2e2da44a866f",
      "descriptionKey": "app:report:description:231e091c-296b-43bf-a2d9-91a5eca5913b",
      "objectTypeId": 4211,
      "created": "2019-12-09T19:06:56.042Z",
      "modified": "2019-12-09T19:14:58.577Z",
      "org": 46,
      "externalRefId": "8e197f22-774f-459f-b9a1-a087055c1fb7", <--Report external reference ID
      "type": 1,
      "showArchiveData": false,
      "nestloop": "org"
    }

 GET  /object/objectType/{id}

{
  "id": 2373, <--Object type Internal ID
  "name": "Incident",
  "pluralName": "Incidents",
  "description": "",
  "monogram": "INC",
  "nameKey": "app:objectType:name:5ac171c8-69e2-4b7e-aa9a-0ce17c22aa2a",
  "descriptionKey": "app:objectType:description:e130ff47-cf9a-419c-8e74-f70e4ee504f7",
  "pluralNameKey": "app:objectType:pluralName:552ff26a-abea-49ed-9f08-c4dd6e70fdec",
  "monogramKey": "app:objectType:monogram:998fd41f-9cd5-42fd-ad61-d08aee707574",
  "color": "#fff57a",
  "objectLifeCycleId": 2490,
  "externalRefId": "Incident", <--Object type External Reference ID
  "created": "2017-12-14T20:28:06.519Z",
  "modified": "2019-02-07T15:18:02.255Z",
  "nextElement": 34,
  "org": 8,
  "assessment": false,
  "anchor": null,
  "anchorRelationship": null,
  "dataDefinitionId": null
}

 GET  /data/object

    {
      "id": 758, <--Object internal ID
      "name": "Service agreements are maintained for hardware and software",
      "description": "Service agreements are maintained for hardware and software to ensure support during a disaster.",
      "externalRefId": "CON-13:1", <--Object external reference ID
      "uniqueId": "13.1", <--Object Unique ID
      "objectTypeId": 4188,
      "evaluations": {
        "12339": {
          "value": null
        }