Contacts

Requires Admin API Key

Contact endpoints require an Admin API key. Read operations need contacts:read, write operations need contacts:write. See API Keys.

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

Endpoints

Method	Path	Scope	Description
`GET`	`/get-contacts`	`contacts:read`	List contacts in an audience
`GET`	`/get-contact`	`contacts:read`	Get a single contact by ID or email
`POST`	`/add-contact`	`contacts:write`	Add a contact to an audience
`PATCH`	`/update-contact`	`contacts:write`	Update contact fields
`DELETE`	`/delete-contact`	`contacts:write`	Delete a contact

List Contacts

GET /api/v1/public/contacts/get-contacts

Query Parameters

Parameter	Type	Required	Default	Description
`audienceId`	`UUID`	Yes	-	The audience to list contacts from
`page`	`number`	No	`1`	Page number
`limit`	`number`	No	`50`	Results per page (max 1000)
`sortBy`	`string`	No	`createdAt`	`firstName`, `lastName`, `email`, `createdAt`, `deliverabilityScore`
`sortDir`	`string`	No	`asc`	`asc` or `desc`
`subscribedOnly`	`boolean`	No	`false`	When `true`, returns only subscribed contacts

Response

The list response returns a slim contact shape. Use Get Contact for full details.

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "019dd571-7fd1-7182-b941-2bbc8331b331",
        "email": "[email protected]",
        "firstName": "John",
        "lastName": "Doe",
        "companyName": "Acme Corp",
        "jobTitle": "Engineer",
        "phoneNumber": "+1 555 000 0001",
        "status": "subscribed",
        "tags": ["vip", "newsletter"]
      }
    ],
    "page": 1,
    "limit": 50,
    "total": 142,
    "totalPages": 3
  },
  "message": "Contacts retrieved"
}

Examples

curl "https://api.keplars.com/api/v1/public/contacts/get-contacts?audienceId=019dd568-1ac3-7320-ad48-ea6189b937d0&page=1&limit=50" \
  -H "Authorization: Bearer $KEPLARS_ADMIN_KEY"

const res = await fetch(
  'https://api.keplars.com/api/v1/public/contacts/get-contacts?audienceId=019dd568-1ac3-7320-ad48-ea6189b937d0&page=1&limit=50',
  { 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/contacts/get-contacts?audienceId=019dd568-1ac3-7320-ad48-ea6189b937d0&page=1&limit=50',
    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/contacts/get-contacts?audienceId=019dd568-1ac3-7320-ad48-ea6189b937d0&page=1&limit=50", 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/contacts/get-contacts?audienceId=019dd568-1ac3-7320-ad48-ea6189b937d0&page=1&limit=50');
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/contacts/get-contacts?audienceId=019dd568-1ac3-7320-ad48-ea6189b937d0&page=1&limit=50"
);
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/contacts/get-contacts?audienceId=019dd568-1ac3-7320-ad48-ea6189b937d0&page=1&limit=50")
        .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/contacts/get-contacts?audienceId=019dd568-1ac3-7320-ad48-ea6189b937d0&page=1&limit=50");
    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/contacts/get-contacts?audienceId=019dd568-1ac3-7320-ad48-ea6189b937d0&page=1&limit=50");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

Get Contact

GET /api/v1/public/contacts/get-contact?id={contactId}
GET /api/v1/public/contacts/get-contact?email={email}

Provide either id or email - not both.

Response

Returns the full contact object including all fields.

{
  "success": true,
  "data": {
    "id": "019dd571-7fd1-7182-b941-2bbc8331b331",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "companyName": "Acme Corp",
    "jobTitle": "Engineer",
    "phoneNumber": "+1 555 000 0001",
    "linkedin": "https://linkedin.com/in/johndoe",
    "timezone": "America/New_York",
    "deliverabilityScore": 0.98,
    "emailVerificationDate": "2026-04-01T00:00:00.000Z",
    "customHeaders": null,
    "status": "subscribed",
    "tags": ["vip", "newsletter"],
    "customAttributes": { "plan": "pro", "signupSource": "website" },
    "createdAt": "2026-04-28T18:54:38.547Z",
    "updatedAt": "2026-04-28T19:09:48.486Z"
  },
  "message": "Contact retrieved"
}

Examples - by ID

curl "https://api.keplars.com/api/v1/public/contacts/get-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331" \
  -H "Authorization: Bearer $KEPLARS_ADMIN_KEY"

const res = await fetch(
  'https://api.keplars.com/api/v1/public/contacts/get-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331',
  { 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/contacts/get-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331',
    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/contacts/get-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331", 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/contacts/get-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331');
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/contacts/get-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331"
);
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/contacts/get-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331")
        .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/contacts/get-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331");
    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/contacts/get-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

Examples - by email

curl "https://api.keplars.com/api/v1/public/contacts/get-contact?email=john%40example.com" \
  -H "Authorization: Bearer $KEPLARS_ADMIN_KEY"

const res = await fetch(
  'https://api.keplars.com/api/v1/public/contacts/get-contact?email=john%40example.com',
  { 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/contacts/get-contact?email=john%40example.com',
    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/contacts/get-contact?email=john%40example.com", 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/contacts/get-contact?email=john%40example.com');
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/contacts/get-contact?email=john%40example.com"
);
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/contacts/get-contact?email=john%40example.com")
        .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/contacts/get-contact?email=john%40example.com");
    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/contacts/get-contact?email=john%40example.com");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}

Add Contact

POST /api/v1/public/contacts/add-contact

Adds a contact to an audience. If a contact with the same email already exists in your workspace, their profile is updated and they are added to the audience.

Request Body

Field	Type	Required	Description
`email`	`string`	Yes	Contact email address
`audience_id`	`UUID`	Yes	Audience to add the contact to
`first_name`	`string`	No	First name
`last_name`	`string`	No	Last name
`company_name`	`string`	No	Company name
`job_title`	`string`	No	Job title
`phone_number`	`string`	No	Phone number
`linkedin`	`string`	No	LinkedIn profile URL
`timezone`	`string`	No	IANA timezone (e.g. `America/New_York`)
`tags`	`string`	No	Pipe-separated tag list: `"vip\|newsletter"`
`custom_attributes`	`object`	No	Key-value pairs for custom data

{
  "email": "[email protected]",
  "audience_id": "019dd568-1ac3-7320-ad48-ea6189b937d0",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme Corp",
  "job_title": "Engineer",
  "tags": "vip|newsletter",
  "custom_attributes": {
    "plan": "pro",
    "signupSource": "website"
  }
}

Response

Returns 201 Created with the new contact ID.

{
  "success": true,
  "data": { "id": "019dd571-7fd1-7182-b941-2bbc8331b331" },
  "message": "Contact added to audience"
}

Examples

curl -X POST "https://api.keplars.com/api/v1/public/contacts/add-contact" \
  -H "Authorization: Bearer $KEPLARS_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","audience_id":"019dd568-1ac3-7320-ad48-ea6189b937d0","first_name":"John","last_name":"Doe","tags":"vip|newsletter"}'

const res = await fetch(
  'https://api.keplars.com/api/v1/public/contacts/add-contact',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.KEPLARS_ADMIN_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
    email: '[email protected]',
    audience_id: '019dd568-1ac3-7320-ad48-ea6189b937d0',
    first_name: 'John',
    last_name: 'Doe',
    tags: 'vip|newsletter',
  }),
  },
);
const { data } = await res.json();

import requests, os
res = requests.post(
    'https://api.keplars.com/api/v1/public/contacts/add-contact',
    json={
        'email': '[email protected]',
        'audience_id': '019dd568-1ac3-7320-ad48-ea6189b937d0',
        'first_name': 'John',
        'last_name': 'Doe',
        'tags': 'vip|newsletter',
    },
    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(`{"email":"[email protected]","audience_id":"019dd568-1ac3-7320-ad48-ea6189b937d0","first_name":"John","last_name":"Doe","tags":"vip|newsletter"}`)
    req, _ := http.NewRequest("POST",
        "https://api.keplars.com/api/v1/public/contacts/add-contact", 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/contacts/add-contact');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode([
        'email' => '[email protected]',
        'audience_id' => '019dd568-1ac3-7320-ad48-ea6189b937d0',
        'first_name' => 'John',
        'last_name' => 'Doe',
        'tags' => 'vip|newsletter',
    ]),
    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/contacts/add-contact",
    new
{
    email = "[email protected]",
    audience_id = "019dd568-1ac3-7320-ad48-ea6189b937d0",
    first_name = "John",
    last_name = "Doe",
    tags = "vip|newsletter"
}
);
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/contacts/add-contact")
        .header("Authorization", format!("Bearer {}", std::env::var("KEPLARS_ADMIN_KEY")?))
        .json(&json!({
    "email": "[email protected]",
    "audience_id": "019dd568-1ac3-7320-ad48-ea6189b937d0",
    "first_name": "John",
    "last_name": "Doe",
    "tags": "vip|newsletter"
}))
        .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 = "{\"email\":\"[email protected]\",\"audience_id\":\"019dd568-1ac3-7320-ad48-ea6189b937d0\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"tags\":\"vip|newsletter\"}";
    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/contacts/add-contact");
    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 = "{\"email\":\"[email protected]\",\"audience_id\":\"019dd568-1ac3-7320-ad48-ea6189b937d0\",\"first_name\":\"John\",\"last_name\":\"Doe\",\"tags\":\"vip|newsletter\"}";
    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/contacts/add-contact");
    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;
}

Update Contact

PATCH /api/v1/public/contacts/update-contact?id={contactId}

Updates fields on an existing contact. Only fields you include are changed - all others are left as-is.

Request Body

Same optional fields as Add Contact, except email and audience_id cannot be changed here.

{
  "first_name": "Jonathan",
  "job_title": "Senior Engineer",
  "tags": "vip|newsletter|beta",
  "custom_attributes": {
    "plan": "enterprise"
  }
}

Response

{
  "success": true,
  "data": { "id": "019dd571-7fd1-7182-b941-2bbc8331b331" },
  "message": "Contact updated"
}

Examples

curl -X PATCH "https://api.keplars.com/api/v1/public/contacts/update-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331" \
  -H "Authorization: Bearer $KEPLARS_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Jonathan","job_title":"Senior Engineer"}'

const res = await fetch(
  'https://api.keplars.com/api/v1/public/contacts/update-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331',
  {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${process.env.KEPLARS_ADMIN_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
    first_name: 'Jonathan',
    job_title: 'Senior Engineer',
  }),
  },
);
const { data } = await res.json();

import requests, os
res = requests.patch(
    'https://api.keplars.com/api/v1/public/contacts/update-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331',
    json={
        'first_name': 'Jonathan',
        'job_title': 'Senior Engineer',
    },
    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(`{"first_name":"Jonathan","job_title":"Senior Engineer"}`)
    req, _ := http.NewRequest("PATCH",
        "https://api.keplars.com/api/v1/public/contacts/update-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331", 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/contacts/update-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_POSTFIELDS     => json_encode([
        'first_name' => 'Jonathan',
        'job_title' => 'Senior Engineer',
    ]),
    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.PatchAsJsonAsync(
    "https://api.keplars.com/api/v1/public/contacts/update-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331",
    new
{
    first_name = "Jonathan",
    job_title = "Senior Engineer"
}
);
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
        .patch("https://api.keplars.com/api/v1/public/contacts/update-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331")
        .header("Authorization", format!("Bearer {}", std::env::var("KEPLARS_ADMIN_KEY")?))
        .json(&json!({
    "first_name": "Jonathan",
    "job_title": "Senior Engineer"
}))
        .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 = "{\"first_name\":\"Jonathan\",\"job_title\":\"Senior Engineer\"}";
    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/contacts/update-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331");
    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 = "{\"first_name\":\"Jonathan\",\"job_title\":\"Senior Engineer\"}";
    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/contacts/update-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331");
    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 Contact

DELETE /api/v1/public/contacts/delete-contact?id={contactId}

Returns 204 No Content on success.

This permanently deletes the contact from your entire workspace - not just a single audience. All audience memberships and history are removed.

Examples

curl -X DELETE "https://api.keplars.com/api/v1/public/contacts/delete-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331" \
  -H "Authorization: Bearer $KEPLARS_ADMIN_KEY"

const res = await fetch(
  'https://api.keplars.com/api/v1/public/contacts/delete-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331',
  {
    method: 'DELETE',
    headers: {
      Authorization: `Bearer ${process.env.KEPLARS_ADMIN_KEY}`,
    },
  },
);

import requests, os
res = requests.delete(
    'https://api.keplars.com/api/v1/public/contacts/delete-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331',
    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/contacts/delete-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331", 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/contacts/delete-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331');
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/contacts/delete-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331"
);

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/contacts/delete-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331")
        .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/contacts/delete-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331");
    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/contacts/delete-contact?id=019dd571-7fd1-7182-b941-2bbc8331b331");
    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;
}

Contact Object

List Response (slim)

Field	Type	Description
`id`	`UUID`	Unique contact identifier
`email`	`string`	Email address
`firstName`	`string\|null`	First name
`lastName`	`string\|null`	Last name
`companyName`	`string\|null`	Company
`jobTitle`	`string\|null`	Job title
`phoneNumber`	`string\|null`	Phone number
`status`	`string`	`subscribed` or `unsubscribed` - per this audience
`tags`	`string[]`	Tag list

Detail Response (full)

All list fields plus:

Field	Type	Description
`linkedin`	`string\|null`	LinkedIn URL
`timezone`	`string\|null`	IANA timezone
`deliverabilityScore`	`number\|null`	Email deliverability score (0–1)
`emailVerificationDate`	`ISO 8601\|null`	When the email was last verified
`customHeaders`	`object\|null`	Custom email headers
`customAttributes`	`object\|null`	Your custom key-value data
`createdAt`	`ISO 8601`	When the contact was created
`updatedAt`	`ISO 8601`	Last updated timestamp

Status Values

status reflects the contact's subscription state in the queried audience only - the same contact can be subscribed in one audience and unsubscribed in another.

Value	Meaning
`subscribed`	Will receive campaigns sent to this audience
`unsubscribed`	Excluded from campaigns - clicked unsubscribe or removed manually

Errors

Status	Code	When
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Key is not an Admin key
403	`INSUFFICIENT_SCOPE`	Key missing required scope
403	`CONTACTS_LIMIT_REACHED`	Workspace contact limit reached - upgrade your plan
404	`CONTACT_NOT_FOUND`	Contact ID or email does not exist
404	`AUDIENCE_NOT_FOUND`	`audienceId` does not exist in your workspace
409	`CONTACT_ALREADY_IN_AUDIENCE`	Contact is already a member of this audience
400	`VALIDATION_ERROR`	Invalid email format or missing required fields

Contacts

On this page