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

# Quickstart

> Learn how to file your first dispute with the Decisionly API

Filing disputes is a time consuming and often confusing process. Use the Decisionly API to quickly and confidently file your disputes. Our API ensures that you will meet all the requirements and timelines for the type of dispute you wish to file.

<Info>
  New to disputes? Read [What Are Disputes?](/guide) first to understand the dispute lifecycle, card network rules, and key terminology.
</Info>

<Info>
  Before you can make requests to the Decisionly API, you will need to grab your API key from your dashboard [settings](https://decisionly.com/settings).
</Info>

<Note>
  **Replace the sample API key.** The key `test_d0019b48d05849a6` used in these examples is for illustration only and will return an `Invalid API key` error. Substitute your real API key from the dashboard [settings](https://decisionly.com/settings).
</Note>

## Step 1: Create a case

Create a case with cardholder information, card details, transaction information, and dispute details:

<CodeGroup>
  ```bash Create a case theme={null}
  curl https://api.decisionly.com/v2/issuer/cases \
    -u test_d0019b48d05849a6: \
    -H "Content-Type: application/json" \
    -d '{
      "cardholder": {
        "billing_address": {
          "city": "San Francisco",
          "country": "US",
          "line1": "742 Evergreen Terrace",
          "line2": "Unit 5B",
          "postal_code": "94102",
          "state": "CA"
        },
        "email": "jane@example.com",
        "issuer_id": "9529456289",
        "name": "Jane Smith",
        "type": "individual"
      },
      "dispute": {
        "amount": 2990,
        "currency": "USD",
        "date": "2026-04-20T00:00:00.000Z",
        "raised_by": "cardholder",
        "reason": "product_not_received"
      },
      "issuer_evidence": {
        "cardholder_explanation": "I never received this order",
        "product": {
          "type": "merchandise"
        },
        "delivery": {
          "expected_date": "2026-04-05T00:00:00.000Z"
        },
        "merchant_contact": {
          "was_attempted": true,
          "date": "2026-04-08T00:00:00.000Z",
          "was_successful": false,
          "description": "Contacted merchant via email but received no response"
        }
      },
      "merchant": {
        "category_code": "5812",
        "name": "FoodHub"
      },
      "transaction": {
        "amount": 2990,
        "arn": "48162855246353338636162",
        "card": {
          "expiry_month": 12,
          "expiry_year": 2028,
          "last4": "4242",  
          "network": "mastercard",
          "type": "credit"
        },
        "currency": "USD",
        "date": "2026-03-28T00:00:00.000Z"
      }
    }'
  ```
</CodeGroup>

<Note>
  **Keep dates within the filing window.** The `product_not_received` reason requires filing within 120 days of the transaction date. If `delivery.expected_date` is provided, filing must also be after that date. Replace the dates in this example with current transaction and delivery dates.
</Note>

## Step 2: File the case

File the case with the card network:

<CodeGroup>
  ```bash File a case theme={null}
  curl https://api.decisionly.com/v2/issuer/cases/case_abc123/file \
    -u test_d0019b48d05849a6: \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "file_mode": "auto"
    }'
  ```
</CodeGroup>

Set `file_mode` to `auto` to let your workflow rules determine how the case should be filed, or `chargeback` to file the case as a chargeback.

## Next Steps

<CardGroup cols={2}>
  <Card title="Dispute Types" icon="list" href="/dispute-types">
    Learn about the different dispute reasons and requirements
  </Card>

  <Card title="Workflow Rules" icon="diagram-project" href="/workflow-rules">
    Set up rules to automate your filing decisions
  </Card>
</CardGroup>