# Quick Start

The shortest path to a working GetResponse API integration for AI agents and developers. Create your first campaign (contact list), then read it back. If both requests succeed, your integration is working and you’re ready to explore the [API Reference](https://apireference.getresponse.com/).

## Prerequisites

- An API key generated in your account: [https://app.getresponse.com/api](https://app.getresponse.com/api)
- Every request must include your API key in the `X-Auth-Token` header, prefixed with `api-key`. Replace `YOUR_API_KEY` with the API key from your account:

```
X-Auth-Token: api-key YOUR_API_KEY
```

- Base URL (use the base URL that corresponds to your account type):

| Account type | Base URL |
| --- | --- |
| GetResponse (SMB) | `https://api.getresponse.com/v3` |
| GetResponse MAX (PL) | `https://api3.getresponse360.pl/v3` |
| GetResponse MAX (US) | `https://api3.getresponse360.com/v3` |

**For MAX accounts:**

Ask your account manager if you don’t know which domain your account is hosted on. MAX requests must also include an `X-Domain` header with your account domain, e.g. `X-Domain: example.com`. See [Authentication](https://apidocs.getresponse.com/v3/authentication) for details.

**The examples below use the SMB base URL. For MAX accounts, use your MAX base URL instead.**

## Step 1: Create campaign

Call [POST /campaigns](https://apireference.getresponse.com/#operation/createCampaign) to create a campaign (contact list). Only `name` is required. It must be unique in your account, be 3-64 characters long, and cannot contain `/`, `\`, `@`, `[` or `]`.

```bash
curl -X POST \
     https://api.getresponse.com/v3/campaigns \
     -H 'X-Auth-Token: api-key YOUR_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "quick_start_list"
   }'
```

Here’s an example of the same call from a GetResponse MAX (PL) account:

```bash
curl -X POST \
     https://api3.getresponse360.pl/v3/campaigns \
     -H 'X-Auth-Token: api-key YOUR_API_KEY' \
     -H 'X-Domain: example.com' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "quick_start_list"
   }'
```

A `201 Created` response returns the full campaign resource, including its `campaignId`. Copy the `campaignId` for the next step:

```json
{
    "campaignId": "Ls3jm",
    "href": "https://api.getresponse.com/v3/campaigns/Ls3jm",
    "name": "quick_start_list",
    "techName": "17e911d2d2e32f9a05d722241bdecb45",
    "languageCode": "PL",
    "isDefault": "false",
    "createdOn": "2024-05-14T09:12:31+0000",
    "confirmation": { ... },
    "profile": { ... },
    "postal": { ... },
    "optinTypes": {
        "api": "double",
        "email": "single",
        "import": "single",
        "webform": "double"
    },
    "subscriptionNotifications": { ... }
}
```

If the name is already in use in your account, you’ll get a `409 Conflict` response with error code `1008`. Choose a different name and try again. For more information on possible errors, see [Errors](https://apidocs.getresponse.com/v3/errors).

## Step 2: Retrieve campaign

Call [GET /campaigns/{campaignId}](https://apireference.getresponse.com/#operation/getCampaign) with the `campaignId` returned in step 1 to confirm that the campaign exists.

```bash
curl -X GET \
     https://api.getresponse.com/v3/campaigns/Ls3jm \
     -H 'X-Auth-Token: api-key YOUR_API_KEY'
```

A `200 OK` response with the same `campaignId` and `name` confirms your integration is working end to end. An invalid or missing API key returns `401 Unauthorized` with error code `1014`. For more information on possible errors, see [Errors](https://apidocs.getresponse.com/v3/errors).

## Next steps

- [Authentication](https://apidocs.getresponse.com/v3/authentication) for OAuth 2.0 and GetResponse MAX headers
- [Adding contacts](https://apidocs.getresponse.com/v3/case-study/adding-contacts) to add a contact to the new campaign
