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

# Quickstart

> The fastest path to a successful API call against Raise — from credentials to your first response in a few minutes.

This page walks through making a successful API call against Raise. It assumes you have an API token already; if you don't, see [Authentication](/raise/authentication) for how to obtain one.

The goal is a working request and response, not a deep dive. Once you have one of each, the rest of the docs will make more sense.

## Prerequisites

* A Raise account at the customer organization you'll be integrating with.
* A Raise API token. See [Authentication](/raise/authentication).
* An HTTP client. The examples below use `curl` and Node.js `fetch`, but anything that can make a JSON HTTP request works.

## The first call: list donors

The simplest read endpoint to test against is `GET /api/Donor/list` — it returns a paginated list of donor records and confirms your token works.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://prod-api.raisedonors.com/api/Donor/list?Take=5 \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://prod-api.raisedonors.com/api/Donor/list?Take=5',
    {
      headers: {
        Authorization: `Bearer ${process.env.RAISE_API_TOKEN}`,
      },
    }
  );

  const data = await response.json();
  console.log(`Total donors: ${data.total}`);
  console.log(`First ${data.items.length} donors:`, data.items);
  ```
</CodeGroup>

A successful response looks like:

```json theme={null}
{
  "items": [
    {
      "id": 12345,
      "firstName": "Bruce",
      "lastName": "Wayne",
      "email": "bruce@wayne.example",
      "createdAt": "2024-12-15T14:30:00Z"
    },
    {
      "id": 12346,
      "firstName": "Diana",
      "lastName": "Prince",
      "email": "diana@themyscira.example",
      "createdAt": "2024-12-14T09:15:00Z"
    }
  ],
  "total": 8421
}
```

Two things worth noting in the response:

* **The envelope is `items`/`total`**, not `list`/`total` like CRM+. Every paginated Raise endpoint uses this shape — see [Pagination and Filtering](/raise/pagination).
* **The `total` is the full result count**, not just the number returned. With `Take=5`, you see 5 items but `total` shows you there are 8,421 donors in the organization.

## What just happened

The request succeeded because three things lined up:

1. **The host was right.** Raise is at `prod-api.raisedonors.com` — not the CRM+ host.
2. **The token was valid.** The `Authorization: Bearer YOUR_API_TOKEN` header carried a JWT that Raise recognized.
3. **The endpoint exists.** `/api/Donor/list` is a real Raise endpoint that accepts the `Take` query parameter.

If any of those weren't right, the response would have been:

* `401 Unauthorized` — bad token or missing header.
* `404 Not Found` — wrong path (probably a typo like `/api/Donors/list`).
* A network or DNS error — wrong host.

See [Error Handling](/raise/error-handling) for the full error envelope and remediation guide.

## Reading more of the data

`Take=5` capped the response to five items. To page through more, use `Skip` to advance:

<CodeGroup>
  ```bash cURL theme={null}
  # Page 2: skip the first 5, take the next 5
  curl "https://prod-api.raisedonors.com/api/Donor/list?Skip=5&Take=5" \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://prod-api.raisedonors.com/api/Donor/list?Skip=5&Take=5',
    {
      headers: { Authorization: `Bearer ${process.env.RAISE_API_TOKEN}` },
    }
  );
  const page2 = await response.json();
  ```
</CodeGroup>

The maximum `Take` value is bounded by the API — typically 1,000 for bulk operations. See [Pagination and Filtering](/raise/pagination) for the full iteration pattern.

## A second call: submit a donation

Reading is one half of the API. The other half is the donation-submission endpoint that's distinctive to Raise: `POST /api/Raise/give`. This is the only path that creates Gift records — there's no `POST /api/Gift`.

```bash cURL theme={null}
curl -X POST https://prod-api.raisedonors.com/api/Raise/give \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": 1234,
    "campaignId": 5678,
    "amount": 50.00,
    "donor": {
      "firstName": "Bruce",
      "lastName": "Wayne",
      "email": "bruce@wayne.example"
    },
    "paymentMethod": {
      "...": "see Process a Donation workflow"
    }
  }'
```

The full request body shape — including the payment method, designation breakdown, and donor matching parameters — is covered in [Process a Donation](/raise/workflows/process-a-donation). Don't try this against production data without reading that page first.

<Tip>
  For development and testing, Raise exposes a `POST /api/Raise/generate-test-payment-method` endpoint that returns a payment method usable in test mode. Use this to drive end-to-end test flows without real card numbers. The Process a Donation workflow covers this in detail.
</Tip>

## What to read next

Now that you have a working call:

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/raise/authentication">
    Full coverage of the token format, header, and credential lifecycle.
  </Card>

  <Card title="Base URLs and Environments" icon="server" href="/raise/base-urls">
    The Raise host, sandbox setup, and environment selection.
  </Card>

  <Card title="Pagination and Filtering" icon="list" href="/raise/pagination">
    The full iteration pattern for `items`/`total` paginated responses.
  </Card>

  <Card title="Process a Donation" icon="hand-holding-dollar" href="/raise/workflows/process-a-donation">
    The end-to-end `POST /api/Raise/give` workflow with the full request shape.
  </Card>
</CardGroup>