# Getting started

### Introduction

Welcome to the Retainful API! \
Our platform streamlines marketing automation, making it easy for developers to integrate audience management, personalized messaging, and growth-driven campaigns into their applications. \
\
Whether you need to add or update contacts, or automate welcome messages, Retainful provides a straightforward, developer-friendly REST API. 

With flexible permissions, clear documentation, and robust endpoints, you can quickly build and scale your marketing workflows—no complicated configurations required.

In the sections that follow, you’ll learn how to set up your API credentials, manage contacts and lists, and customize key aspects of your automation. If you have any questions along the way, our Help Center and support team are here to assist. 

Let’s get started!

### Creating the API Key

Head over to your Retainful Account dashboard -> Settings -> API Keys section.

1. Click **Create API Key** to generate a new key.
2. **Set the Permissions**:
   * **Full Access**: Read and write access to all endpoints.
   * **Read-only**: Read access only—API key cannot modify or write any data.
   * **Custom Access**: Customize the access level for the key for different endpoints. 
3. Save or copy your new API key securely.

### API Host

`apiv2.retainful.net`

### Working with Retainful API

Once you created the API Key, following these steps to start working with the Retainful API

* **Find Your App ID**
  * In the **Settings** → **General** section, you will also see your **App ID**. You need to send the App ID in each request. 
* **Add Headers to Every Request**\
  Retainful’s API requires the following headers for authentication in each request:

  ```http
  Retainful-Api-Key: YOUR_API_KEY
  Retainful-App-Id: YOUR_APP_ID
  ```

  Replace `YOUR_API_KEY` and `YOUR_APP_ID` with the actual values from your account.
* **Use the Endpoints**
  * Refer to the [Contacts API ](/developers/contacts.md)documentation for creating or updating contacts.
  * Refer to the [Lists API](/developers/lists.md) documentation for retrieving audience lists.
* **Test Your Requests**
  * Use tools like cURL or Postman to verify connectivity and ensure your API key permissions are set correctly.
* **Build & Integrate**
  * Once you’ve confirmed authentication and permissions, integrate the API calls into your application or automation workflows.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.retainful.com/developers/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.