---
title: "Aliases"
canonical_url: "https://docs.getdx.com/webapi/types/aliases/"
md_url: "https://docs.getdx.com/webapi/types/aliases.md"
last_updated: "2026-06-08"
---

# Aliases
Aliases are references to entities in external systems. They are organized by alias type, with each type containing a list of alias entry definitions.

To remove an alias, update or upsert a catalog entity with the alias type and an empty array `[]` as the value instead of any entry identifiers. Omitted alias types will not be affected.

The key in the object is the distinct alias type. Each alias entry must include either `identifier` or `lookup`, but not both.

## Example Request

When creating or updating aliases, use `identifier` when you know the external system's unique identifier for the alias entry. Use `lookup` when you want the API to find a single matching alias entry by name or identifier from the Data Cloud database.

A `lookup` value uses case-insensitive partial matching. If the lookup matches more than one alias entry, the request returns `alias_lookup_ambiguous`.

```json
{
  "github_repo": [
    {
      "lookup": "get-dx/payment-processing"
    }
  ],
  "pagerduty_service": [
    {
      "identifier": "P123ABC"
    }
  ]
}
```

## Example Response

The API response will include the `name` and optional `url` fields that were fetched from the Data Cloud database:

```json
{
  "github_repo": [
    {
      "identifier": "671150935",
      "name": "get-dx/payment-processing",
      "url": "https://github.com/get-dx/payment-processing"
    }
  ],
  "pagerduty_service": [
    {
      "identifier": "P123ABC",
      "name": "Payment Service"
    }
  ]
}
```

## Supported alias types

See the catalog docs for a list of [supported aliases](https://docs.getdx.com/catalog/overview/#supported-aliases).

## Properties

| Key          | Type   | Description                                                                                                                                       |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identifier` | string | The external system's unique identifier for the item. Required when `lookup` is not provided.                                                     |
| `lookup`     | string | A name or identifier fragment used to resolve one matching alias entry from Data Cloud. Required when `identifier` is not provided.               |
| `name`       | string | The display name of the item in the system. Returned in API responses, not required in requests.                                                  |
| `url`        | string | When supported by the alias type, this will be a link to the item in the third-party system. Returned in API responses, not required in requests. |
---

## Sitemap

[Overview of all docs pages](/llms.txt)