Audiences

Requires Admin API Key

All audience endpoints require an Admin API key with the audiences:manage scope. Regular (send-email) keys are rejected with 403. See API Keys for how to create one.

Base path: https://api.keplars.com/api/v1/public/audiences

Endpoints

Method	Path	Description
`GET`	`/get-audiences`	List all audiences
`GET`	`/get-audience?id=`	Get a single audience
`POST`	`/add-audience`	Create a new audience
`DELETE`	`/delete-audience?id=`	Delete an audience

List Audiences

GET /api/v1/public/audiences/get-audiences

Query Parameters

Parameter	Type	Default	Description
`page`	`number`	`1`	Page number
`limit`	`number`	`50`	Results per page (max 1000)
`sortBy`	`string`	`createdAt`	`name`, `contactCount`, `createdAt`
`sortDir`	`string`	`desc`	`asc` or `desc`

Response

{
  "success": true,
  "data": {
    "audiences": [
      {
        "id": "019dd568-1ac3-7320-ad48-ea6189b937d0",
        "name": "Newsletter",
        "contactCount": 142,
        "subscribeUrl": "https://keplars.com/s/a3f9bc4d...",
        "createdAt": "2026-04-01T10:00:00.000Z"
      }
    ],
    "page": 1,
    "limit": 50,
    "total": 3,
    "totalPages": 1
  },
  "message": "Audiences retrieved"
}

Examples

curl "https://api.keplars.com/api/v1/public/audiences/get-audiences" \
  -H "Authorization: Bearer $KEPLARS_ADMIN_KEY"

const res = await fetch(
  'https://api.keplars.com/api/v1/public/audiences/get-audiences',
  { headers: { Authorization: `Bearer ${process.env.KEPLARS_ADMIN_KEY}` } },
);
const { data } = await res.json();

import requests, os
res = requests.get(
    'https://api.keplars.com/api/v1/public/audiences/get-audiences',
    headers={'Authorization': f'Bearer {os.environ["KEPLARS_ADMIN_KEY"]}'},
)
data = res.json()['data']

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://api.keplars.com/api/v1/public/audiences/get-audiences", nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("KEPLARS_ADMIN_KEY"))
    resp, _ := (&http.Client{}).Do(req)
    defer resp.Body.Close()
    b, _ := io.ReadAll(resp.Body)
    fmt.Println(string(b))
}

<?php
$ch = curl_init('https://api.keplars.com/api/v1/public/audiences/get-audiences');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('KEPLARS_ADMIN_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add(
    "Authorization", $"Bearer {Environment.GetEnvironmentVariable("KEPLARS_ADMIN_KEY")}"
);
var response = await client.GetAsync(
    "https://api.keplars.com/api/v1/public/audiences/get-audiences"
);
var body = await response.Content.ReadAsStringAsync();

use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let res = client
        .get("https://api.keplars.com/api/v1/public/audiences/get-audiences")
        .header("Authorization", format!("Bearer {}", std::env::var("KEPLARS_ADMIN_KEY")?))
        .send()
        .await?;
    let data: serde_json::Value = res.json().await?;
    println!("{}", data);
    Ok(())
}

#include <curl/curl.h>
#include <cstdlib>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    std::string auth = std::string("Authorization: Bearer ") + std::getenv("KEPLARS_ADMIN_KEY");
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, auth.c_str());
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.keplars.com/api/v1/public/audiences/get-audiences");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
}

#include <curl/curl.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    CURL* curl = curl_easy_init();
    char auth[256];
    snprintf(auth, sizeof(auth), "Authorization: Bearer %s", getenv("KEPLARS_ADMIN_KEY"));
    struct curl_slist* headers = NULL;
    headers = curl_slist_append(headers, auth);
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.keplars.com/api/v1/public/audiences/get-audiences");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

Get Audience

GET /api/v1/public/audiences/get-audience?id={audienceId}

Query Parameters

Parameter	Type	Required	Description
`id`	`UUID`	Yes	Audience ID

Response

{
  "success": true,
  "data": {
    "id": "019dd568-1ac3-7320-ad48-ea6189b937d0",
    "name": "Newsletter",
    "contactCount": 142,
    "subscribeUrl": "https://keplars.com/s/a3f9bc4d...",
    "createdAt": "2026-04-01T10:00:00.000Z"
  },
  "message": "Audience retrieved"
}

Examples

curl "https://api.keplars.com/api/v1/public/audiences/get-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0" \
  -H "Authorization: Bearer $KEPLARS_ADMIN_KEY"

const res = await fetch(
  'https://api.keplars.com/api/v1/public/audiences/get-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0',
  { headers: { Authorization: `Bearer ${process.env.KEPLARS_ADMIN_KEY}` } },
);
const { data } = await res.json();

import requests, os
res = requests.get(
    'https://api.keplars.com/api/v1/public/audiences/get-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0',
    headers={'Authorization': f'Bearer {os.environ["KEPLARS_ADMIN_KEY"]}'},
)
data = res.json()['data']

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("GET",
        "https://api.keplars.com/api/v1/public/audiences/get-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0", nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("KEPLARS_ADMIN_KEY"))
    resp, _ := (&http.Client{}).Do(req)
    defer resp.Body.Close()
    b, _ := io.ReadAll(resp.Body)
    fmt.Println(string(b))
}

<?php
$ch = curl_init('https://api.keplars.com/api/v1/public/audiences/get-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('KEPLARS_ADMIN_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add(
    "Authorization", $"Bearer {Environment.GetEnvironmentVariable("KEPLARS_ADMIN_KEY")}"
);
var response = await client.GetAsync(
    "https://api.keplars.com/api/v1/public/audiences/get-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0"
);
var body = await response.Content.ReadAsStringAsync();

use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let res = client
        .get("https://api.keplars.com/api/v1/public/audiences/get-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0")
        .header("Authorization", format!("Bearer {}", std::env::var("KEPLARS_ADMIN_KEY")?))
        .send()
        .await?;
    let data: serde_json::Value = res.json().await?;
    println!("{}", data);
    Ok(())
}

#include <curl/curl.h>
#include <cstdlib>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    std::string auth = std::string("Authorization: Bearer ") + std::getenv("KEPLARS_ADMIN_KEY");
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, auth.c_str());
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.keplars.com/api/v1/public/audiences/get-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
}

#include <curl/curl.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    CURL* curl = curl_easy_init();
    char auth[256];
    snprintf(auth, sizeof(auth), "Authorization: Bearer %s", getenv("KEPLARS_ADMIN_KEY"));
    struct curl_slist* headers = NULL;
    headers = curl_slist_append(headers, auth);
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.keplars.com/api/v1/public/audiences/get-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

Create Audience

POST /api/v1/public/audiences/add-audience

Request Body

{
  "name": "VIP Customers"
}

Field	Type	Required	Description
`name`	`string`	Yes	Audience display name (max 255 chars)

Response

Returns 201 Created with the new audience object. The subscribeUrl is immediately available for sharing.

{
  "success": true,
  "data": {
    "id": "019dd568-1ac3-7320-ad48-ea6189b937d0",
    "name": "VIP Customers",
    "contactCount": 0,
    "subscribeUrl": "https://keplars.com/s/f8c2a1b9...",
    "createdAt": "2026-04-29T12:00:00.000Z"
  },
  "message": "Audience created"
}

Examples

curl -X POST "https://api.keplars.com/api/v1/public/audiences/add-audience" \
  -H "Authorization: Bearer $KEPLARS_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"VIP Customers"}'

const res = await fetch(
  'https://api.keplars.com/api/v1/public/audiences/add-audience',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.KEPLARS_ADMIN_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
    name: 'VIP Customers',
  }),
  },
);
const { data } = await res.json();

import requests, os
res = requests.post(
    'https://api.keplars.com/api/v1/public/audiences/add-audience',
    json={
        'name': 'VIP Customers',
    },
    headers={'Authorization': f'Bearer {os.environ["KEPLARS_ADMIN_KEY"]}'},
)
data = res.json()['data']

package main

import (
    "bytes"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    body := bytes.NewBufferString(`{"name":"VIP Customers"}`)
    req, _ := http.NewRequest("POST",
        "https://api.keplars.com/api/v1/public/audiences/add-audience", body)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("KEPLARS_ADMIN_KEY"))
    req.Header.Set("Content-Type", "application/json")
    resp, _ := (&http.Client{}).Do(req)
    defer resp.Body.Close()
    b, _ := io.ReadAll(resp.Body)
    fmt.Println(string(b))
}

<?php
$ch = curl_init('https://api.keplars.com/api/v1/public/audiences/add-audience');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'name' => 'VIP Customers',
    ]),
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('KEPLARS_ADMIN_KEY'),
        'Content-Type: application/json',
    ],
]);
$data = json_decode(curl_exec($ch), true)['data'];
curl_close($ch);

using System.Net.Http;
using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add(
    "Authorization", $"Bearer {Environment.GetEnvironmentVariable("KEPLARS_ADMIN_KEY")}"
);
var response = await client.PostAsJsonAsync(
    "https://api.keplars.com/api/v1/public/audiences/add-audience",
    new
{
    name = "VIP Customers"
}
);
var body = await response.Content.ReadAsStringAsync();

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let res = client
        .post("https://api.keplars.com/api/v1/public/audiences/add-audience")
        .header("Authorization", format!("Bearer {}", std::env::var("KEPLARS_ADMIN_KEY")?))
        .json(&json!({
    "name": "VIP Customers"
}))
        .send()
        .await?;
    let data: serde_json::Value = res.json().await?;
    println!("{}", data);
    Ok(())
}

#include <curl/curl.h>
#include <cstdlib>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    std::string auth = std::string("Authorization: Bearer ") + std::getenv("KEPLARS_ADMIN_KEY");
    const char* payload = "{\"name\":\"VIP Customers\"}";
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, auth.c_str());
    headers = curl_slist_append(headers, "Content-Type: application/json");
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.keplars.com/api/v1/public/audiences/add-audience");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
}

#include <curl/curl.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    CURL* curl = curl_easy_init();
    char auth[256];
    snprintf(auth, sizeof(auth), "Authorization: Bearer %s", getenv("KEPLARS_ADMIN_KEY"));
    const char* payload = "{\"name\":\"VIP Customers\"}";
    struct curl_slist* headers = NULL;
    headers = curl_slist_append(headers, auth);
    headers = curl_slist_append(headers, "Content-Type: application/json");
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.keplars.com/api/v1/public/audiences/add-audience");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

Delete Audience

DELETE /api/v1/public/audiences/delete-audience?id={audienceId}

Returns 204 No Content on success.

Deleting an audience removes all its contact memberships. Contacts that belong to no other audience are also permanently deleted. This cannot be undone.

Examples

curl -X DELETE "https://api.keplars.com/api/v1/public/audiences/delete-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0" \
  -H "Authorization: Bearer $KEPLARS_ADMIN_KEY"

const res = await fetch(
  'https://api.keplars.com/api/v1/public/audiences/delete-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0',
  {
    method: 'DELETE',
    headers: {
      Authorization: `Bearer ${process.env.KEPLARS_ADMIN_KEY}`,
    },
  },
);

import requests, os
res = requests.delete(
    'https://api.keplars.com/api/v1/public/audiences/delete-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0',
    headers={'Authorization': f'Bearer {os.environ["KEPLARS_ADMIN_KEY"]}'},
)

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    req, _ := http.NewRequest("DELETE",
        "https://api.keplars.com/api/v1/public/audiences/delete-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0", nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("KEPLARS_ADMIN_KEY"))
    resp, _ := (&http.Client{}).Do(req)
    defer resp.Body.Close()
    b, _ := io.ReadAll(resp.Body)
    fmt.Println(string(b))
}

<?php
$ch = curl_init('https://api.keplars.com/api/v1/public/audiences/delete-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('KEPLARS_ADMIN_KEY'),
    ],
]);
curl_exec($ch);
curl_close($ch);

using System.Net.Http;

var client = new HttpClient();
client.DefaultRequestHeaders.Add(
    "Authorization", $"Bearer {Environment.GetEnvironmentVariable("KEPLARS_ADMIN_KEY")}"
);
var response = await client.DeleteAsync(
    "https://api.keplars.com/api/v1/public/audiences/delete-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0"
);

use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let res = client
        .delete("https://api.keplars.com/api/v1/public/audiences/delete-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0")
        .header("Authorization", format!("Bearer {}", std::env::var("KEPLARS_ADMIN_KEY")?))
        .send()
        .await?;
    Ok(())
}

#include <curl/curl.h>
#include <cstdlib>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    std::string auth = std::string("Authorization: Bearer ") + std::getenv("KEPLARS_ADMIN_KEY");
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, auth.c_str());
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.keplars.com/api/v1/public/audiences/delete-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE");
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
}

#include <curl/curl.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    CURL* curl = curl_easy_init();
    char auth[256];
    snprintf(auth, sizeof(auth), "Authorization: Bearer %s", getenv("KEPLARS_ADMIN_KEY"));
    struct curl_slist* headers = NULL;
    headers = curl_slist_append(headers, auth);
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.keplars.com/api/v1/public/audiences/delete-audience?id=019dd568-1ac3-7320-ad48-ea6189b937d0");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE");
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

Audience Object

Field	Type	Description
`id`	`UUID`	Unique audience identifier
`name`	`string`	Display name
`contactCount`	`number`	Number of contacts currently in this audience
`subscribeUrl`	`string`	Public signup form URL - share this with your users
`createdAt`	`ISO 8601`	Creation timestamp

Errors

Status	Code	When
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Key is not an Admin key
403	`INSUFFICIENT_SCOPE`	Key missing `audiences:manage` scope
404	`AUDIENCE_NOT_FOUND`	Audience ID does not exist in your workspace
409	`AUDIENCE_HAS_CAMPAIGNS`	Audience has associated campaigns and cannot be deleted
400	`VALIDATION_ERROR`	Invalid or missing request fields

Audiences

On this page