> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snappy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Digital Cards API

Use the **Digital Cards API** to look up digital cards issued through Snappy, and — for integrations that use access-code authentication — to retrieve the access codes needed to complete each redemption.

A digital card is created whenever someone places an order for a digital card product; it captures the card-specific aspects of that order (redemption URL and authentication method today, with more card-level details planned). Digital cards include gift cards, prepaid cards, and similar card-based rewards. All are delivered by email rather than physical shipment.

<Note>
  Digital cards are created through order placement, not directly. To create a new digital card, place an order for a digital card variant via `POST /v3/orders`. The digital card entity is created and activated as part of the order flow and can then be retrieved via this API.
</Note>

## Authentication methods

Every digital card is redeemed with one of two authentication methods. The method is set for your Company during onboarding by the Snappy team and applies to all your digital cards — you don't need to check `authentication.method` per card, and changing methods later requires coordination with Snappy.

* `OTP` — the recipient authenticates by entering a one-time password. When they open the digital card page in Snappy's UI, Snappy sends a fresh, single-use code; a new code is issued on each access attempt. Snappy manages the entire flow end-to-end: notifications, code generation and delivery, and any recipient support. This is Snappy's default configuration for most integrations.
* `accessCode` — the recipient authenticates with a static code that Snappy generates at order placement and returns to you via this API. From that point on, you own the recipient communication (email, SMS, in-app message, or however your platform reaches recipients) and any related support. This setup fits integrations that want to embed the code in a single, unified notification they send themselves rather than a separate Snappy email.

If you're not sure which method your Company is on — or you want to change it — talk to your Snappy representative.

## When to use

Whether you need these endpoints depends on your Company's authentication method:

* If your Company is on `OTP`: Snappy handles the entire redemption flow, so you don't need to call these endpoints to complete a redemption. They're still available for auditing — use them to verify that a digital card was created for an order, or to keep a local record for reporting.
* If your Company is on `accessCode`: use this API to retrieve access codes after order placement, then send them to recipients through your own channel. Typical flow:
  1. Place an order for a digital card variant via `POST /v3/orders`.
  2. List digital cards with `GET /v3/digital-cards?filter[orderId]={orderId}` to get each `digitalCardId`.
  3. Call `GET /v3/digital-cards/{digitalCardId}/access-code` to retrieve the code.
  4. Include the code in your notification to the recipient.

Digital card products live in a dedicated catalog. Use `GET /v3/products?filter[catalog]=digitalCards` to browse available digital card products and their variants before placing an order.

## Endpoints

**List digital cards**

```text theme={null}
GET /v3/digital-cards
```

Retrieves a paginated list of digital cards. Supports `filter[orderId]` to scope to a specific order, `include=brand` to expand brand details, and `page[number]` / `page[size]` for pagination (max 150, default 100).

**Get digital card by ID**

```text theme={null}
GET /v3/digital-cards/{digitalCardId}
```

Retrieves a single digital card by its stable ID. Add `include=brand` to expand brand details on the response.

**Get digital card access code**

```text theme={null}
GET /v3/digital-cards/{digitalCardId}/access-code
```

Retrieves the static access code for a digital card. Returns `422` if your Company is on `OTP` authentication.

## Permissions

All Digital Cards endpoints require the `digital-card:read` scope.

## Error responses

All errors follow the standard V3 error envelope:

```json theme={null}
{
  "status": 404,
  "errorCode": "404_DGTC_001",
  "message": "Digital card not found."
}
```