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

# Quickstart

> Send your first test claim and watch it arrive in the OSA app.

This walk-through uses a **test key** and one of your firm's **test accounts**, so nothing touches real claims and nothing is billed. You need:

* your `osa_test_` key, sent by OSA through a one-time link;
* the sign-in for one of your test accounts, and the OSA app from the App Store. OSA sends your firm the test accounts and their passwords; if you don't have one, ask whoever at your firm received them.

<Warning>
  Keep keys on your servers. Never put an API key in a browser, a mobile app, or source control.
</Warning>

<Steps>
  <Step title="Check your key">
    ```bash theme={"system"}
    curl https://api.osaconnection.com/v1/me \
      -H "Authorization: Bearer $OSA_API_KEY"
    ```

    The response shows your firm, `"environment": "test"`, and the key's `scopes` (its permissions).
  </Step>

  <Step title="Find your test accounts">
    ```bash theme={"system"}
    curl https://api.osaconnection.com/v1/adjusters \
      -H "Authorization: Bearer $OSA_API_KEY"
    ```

    A test key lists only your firm's test accounts. Copy the `osa_id` of one with `"status": "active"`.
  </Step>

  <Step title="Send a claim">
    ```bash theme={"system"}
    IDEMPOTENCY_KEY=$(uuidgen)   # make it once; a retry must send the same value

    curl https://api.osaconnection.com/v1/claims \
      -H "Authorization: Bearer $OSA_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
      -d '{
        "external_id": "CMS-TEST-0001",
        "claim_number": "TEST-2026-0001",
        "adjuster_osa_id": "<test account osa_id>",
        "loss": { "date": "2026-09-27" },
        "policy": { "number": "8705123456" },
        "carrier": {
          "name": "Gulf Coast Mutual Insurance",
          "phone": "8005550199",
          "email": "claims@gulfcoastmutual.example.com",
          "address": {
            "street": "2100 Harbour Island Boulevard, Suite 300",
            "city": "Tampa",
            "state": "FL",
            "zip": "33602"
          }
        },
        "loss_location": {
          "street": "418 Bayshore Drive",
          "city": "Tampa",
          "state": "FL",
          "zip": "33606"
        },
        "policyholder": {
          "first_name": "Maria",
          "last_name": "Delgado",
          "phone": "8135550142"
        }
      }'
    ```

    You get `201 Created` with OSA's claim `id`, your `external_id`, `"test": true`, and `"assignment": { "status": "pending_acceptance", … }`.

    If the call times out, send exactly the same request again with the **same** `Idempotency-Key`: run the `curl` again without the first line. You get `201` with the claim's current state, and no second claim is created.
  </Step>

  <Step title="Accept it in the app">
    Sign in to the OSA app as the test account. The claim is in **Incoming**, marked TEST. Tap **Accept**.
  </Step>

  <Step title="See the acceptance">
    ```bash theme={"system"}
    curl "https://api.osaconnection.com/v1/claims?updated_since=2026-09-28T00:00:00Z" \
      -H "Authorization: Bearer $OSA_API_KEY"
    ```

    The claim's `assignment` now shows `"status": "accepted"` and a `responded_at` time. In production you would run this poll every few minutes; see [Polling](/polling).
  </Step>
</Steps>

## Next steps

* Try a rejection: reject a test claim in the app, read the `rejection_reason`, then offer it to another test account with `POST /v1/claims/{id}/assignment`.
* Send more of what your claims system knows: see [Claim details](/claim-details), [Occupancy and building type](/occupancy-and-building-type) and [Carrier details](/carrier-details).
* Handle every error your code can receive: see [Errors](/errors).
* Read [Testing with test accounts](/testing) before you plan your go-live.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.