# Delete a Card

> DELETE /v1/cards/{id} · Apps platform API

Source: https://developer.kustomer.com/api/apps-platform/delete-a-card

```http
DELETE https://{orgname}.api.kustomerapp.com/v1/cards/{id}
Authorization: Bearer <API key>
```

## Authorization

Requires any one of these roles: `org.permission.apps.delete`; or legacy `org.admin.apps.write`. The API key or user must hold at least one of them. Legacy roles predate permission sets and still work.

Deletes a card by ID

## About Cards

A card is a web page you host that Kustomer loads in an iframe in the agent desktop next to a customer, conversation, company or custom object. Cards are the older way to embed your own UI; new integrations should use a KView with a DynamicCard instead.

A card pairs a `url` with the record types it should appear on. When an agent opens a record of one of those types, Kustomer loads the page so it can show related information from your system. Cards have two stages. First a card is made available, either by an app that includes it or with `POST /v1/cards/available`. Then it is installed into one or more contexts, which creates the installed card that agents see and that `GET /v1/cards` lists.

The `cards` section of an app definition is deprecated. For new work, use a [KView](https://developer.kustomer.com/docs/apps/kviews) that renders your page with `DynamicCard`, which embeds it with the Cards SDK, commands and theming documented there. These endpoints remain for managing existing cards.

#### Fields

| Field | Meaning |
| --- | --- |
| `name` | Identifier for the card, up to 128 characters of letters, digits, `-`, `_` and `.` |
| `description` | What the card shows, up to 4,096 characters |
| `url` | The page Kustomer loads |
| `contexts` | Where the card appears. At least one, with no duplicates. |
| `app` | Optional, when creating. The app the card belongs to. |

#### Contexts

A context is a record type:

| Context | Card appears on |
| --- | --- |
| `customer` | Customer timelines |
| `conversation` | Conversations |
| `company` | Companies |
| `kobject.<klass>` | Custom objects of that Klass, such as `kobject.order` |

`GET /v1/cards` accepts a `context` filter to list only the cards installed for one record type.

#### Which endpoint to use

| To | Call |
| --- | --- |
| Make a new card available to install | [`POST /v1/cards/available`](https://developer.kustomer.com/api/apps-platform/create-a-card) |
| Install an available card into one or more contexts | [`POST /v1/cards/available/{id}/install`](https://developer.kustomer.com/api/apps-platform/install-a-card) |
| List installed cards, optionally for one context | [`GET /v1/cards`](https://developer.kustomer.com/api/apps-platform/get-cards) |
| Read one installed card | [`GET /v1/cards/{id}`](https://developer.kustomer.com/api/apps-platform/get-card) |
| Change where an installed card appears | [`PUT /v1/cards/{id}`](https://developer.kustomer.com/api/apps-platform/update-a-card) |
| Remove an installed card | [`DELETE /v1/cards/{id}`](https://developer.kustomer.com/api/apps-platform/delete-a-card) |

`PUT /v1/cards/{id}` only accepts `contexts`, and the list you send replaces the current one. To change a card's `url` or `name`, create and install a new card, then delete the old one. Reading cards needs an apps read role; creating, installing, updating and deleting need an apps write role, which admins have.

Related: [KViews](https://developer.kustomer.com/docs/apps/kviews), [Embed your own UI](https://developer.kustomer.com/docs/apps/kviews#embed-your-own-ui), [Apps](https://developer.kustomer.com/api/apps-platform#apps)

### Recipes

#### 1. Add your own card to conversations

Show a page from your system next to every conversation, for example an account summary, by making a card available and installing it.

**Step 1.** [`POST /v1/cards/available`](https://developer.kustomer.com/api/apps-platform/create-a-card.md). Make the card available with a `name`, `description`, the `url` of your page and its `contexts`. The response is an `available_card`; keep its `id`. This step doesn't show anything to agents yet.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/cards/available" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "acme-account-summary",
    "description": "Plan, renewal date and open invoices from Acme Billing",
    "url": "https://billing.acme.example/kustomer/card",
    "contexts": ["conversation"]
  }'
```

```bash title="kusty"
AVAILABLE_ID=$(kusty api POST /v1/cards/available --data @card.json | jq -r '.data.id')
```

**Step 2.** [`POST /v1/cards/available/{id}/install`](https://developer.kustomer.com/api/apps-platform/install-a-card.md). Install it into the record types where agents should see it. The response is the installed `card`, with a new `id` that the other card endpoints take.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/cards/available/$AVAILABLE_ID/install" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"contexts": ["conversation"]}'
```

```bash title="kusty"
CARD_ID=$(kusty api POST /v1/cards/available/$AVAILABLE_ID/install \
  --field 'contexts:=["conversation"]' | jq -r '.data.id')
```

**Step 3.** [`GET /v1/cards`](https://developer.kustomer.com/api/apps-platform/get-cards.md). Confirm it's installed by listing the cards for the context.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/cards?context=conversation" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api GET /v1/cards --query context=conversation --all | jq -r '.data | [.id, .attributes.name] | @tsv'
```

> Cards are the older way to embed your UI. For new work, render your page from a [KView with `DynamicCard`](https://developer.kustomer.com/docs/apps/kviews#embed-your-own-ui).

#### 2. Show an existing card on another record type

Add a card that already appears on conversations to customers as well, without removing it from where it is.

**Step 1.** [`GET /v1/cards/{id}`](https://developer.kustomer.com/api/apps-platform/get-card.md). Read the installed card's current `contexts`. The list you send next replaces it.

```bash title="cURL"
curl "https://api.kustomerapp.com/v1/cards/$CARD_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
CONTEXTS=$(kusty api GET /v1/cards/$CARD_ID | jq -c '.data.attributes.contexts + ["customer"] | unique')
```

**Step 2.** [`PUT /v1/cards/{id}`](https://developer.kustomer.com/api/apps-platform/update-a-card.md). Send the full list with the new context added. `contexts` is the only field `PUT` accepts, and it must have at least one entry with no duplicates.

```bash title="cURL"
curl --request PUT "https://api.kustomerapp.com/v1/cards/$CARD_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"contexts": ["conversation", "customer"]}'
```

```bash title="kusty"
kusty api PUT /v1/cards/$CARD_ID --field "contexts:=$CONTEXTS"
```

#### 3. Point a card at a new URL

Move a card to a new address, such as after you change hosting, given that a card's URL can't be edited.

**Step 1.** [`POST /v1/cards/available`](https://developer.kustomer.com/api/apps-platform/create-a-card.md). Make a new card available with the new `url` and a new `name`.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/cards/available" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name": "acme-account-summary-v2", "description": "Plan, renewal date and open invoices from Acme Billing", "url": "https://cards.acme.example/account", "contexts": ["conversation"]}'
```

```bash title="kusty"
AVAILABLE_ID=$(kusty api POST /v1/cards/available --data @card-v2.json | jq -r '.data.id')
```

**Step 2.** [`POST /v1/cards/available/{id}/install`](https://developer.kustomer.com/api/apps-platform/install-a-card.md). Install it into the same `contexts` as the old card.

```bash title="cURL"
curl --request POST "https://api.kustomerapp.com/v1/cards/available/$AVAILABLE_ID/install" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"contexts": ["conversation"]}'
```

```bash title="kusty"
kusty api POST /v1/cards/available/$AVAILABLE_ID/install --field 'contexts:=["conversation"]'
```

**Step 3.** [`DELETE /v1/cards/{id}`](https://developer.kustomer.com/api/apps-platform/delete-a-card.md). Then delete the old installed card by its ID, so agents don't see both.

```bash title="cURL"
curl --request DELETE "https://api.kustomerapp.com/v1/cards/$OLD_CARD_ID" \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```

```bash title="kusty"
kusty api DELETE /v1/cards/$OLD_CARD_ID --confirm --yes
```

### Example object

A real record from [`GET /v1/cards`](https://developer.kustomer.com/api/apps-platform/get-cards.md):

```json
{
  "type": "card",
  "id": "585a920b629a341100361ac3",
  "attributes": {
    "name": "b2b-all-conversations",
    "description": "Summary of all conversations for employees of the same company",
    "url": "https://kustomer-integrations.s3.amazonaws.com/common/b2bCompanyCases/all_company_conversations.html",
    "contexts": [
      "customer",
      "conversation"
    ],
    "createdAt": "2016-12-21T14:30:35.898Z",
    "updatedAt": "2016-12-21T14:30:35.898Z",
    "modifiedAt": "2016-12-21T14:30:35.898Z"
  },
  "relationships": {
    "org": {
      "links": {
        "self": "/v1/orgs/57d82c6808611a1000663fbd"
      },
      "data": {
        "type": "org",
        "id": "57d82c6808611a1000663fbd"
      }
    },
    "app": {
      "links": {
        "self": "/v1/apps/kustomer-0.1.0"
      },
      "data": {
        "type": "app",
        "id": "kustomer-0.1.0"
      }
    }
  },
  "links": {
    "self": "/v1/cards/585a920b629a341100361ac3"
  }
}
```

Fields:

- `type` (string): `card` for an installed card, the kind agents see. A card that has been made available but not installed has type `available_card`.
- `id` (string): The installed card's ID, used by `GET`, `PUT` and `DELETE /v1/cards/{id}`. Installing takes the available card's ID instead.
- `attributes.name` (string): An identifier of up to 128 letters, digits, `-`, `_` and `.`. It can't be changed; create and install a new card instead.
- `attributes.description` (string): What the card shows, up to 4,096 characters.
- `attributes.url` (string): The page Kustomer loads in an iframe on the record. It can't be changed through the API.
- `attributes.contexts` (array): The record types the card appears on: `customer`, `conversation`, `company` or `kobject.<klass>`. `PUT` replaces the whole list.
- `relationships.app` (object): The app the card belongs to, as an app version ID such as `kustomer-0.1.0`.

### Relationships

- Points to **Apps** via `relationships.app`: The app a card belongs to. On the installed app, the `cards` section records each card the install created and its status.

### Permissions

Fewest roles for a read-only integration: `org.permission.apps.read`. For every endpoint: `org.permission.apps.create`, `org.permission.apps.read`, `org.permission.apps.delete`, `org.permission.apps.update`.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | ID of the Card |

## Responses

### 204

No Content

### 401

Unauthorized

### 403

Forbidden

### 404

Not Found

## Example request

```bash
curl --request DELETE \
  --url 'https://api.kustomerapp.com/v1/cards/5f184e74c61792001af42e49' \
  --header "Authorization: Bearer $KUSTOMER_API_KEY"
```