Creating a Contact List

This endpoint creates a new contact list.

A contact list is a grouping of profiles/contacts that can be used for sending campaigns.
It helps you segment your audience, for example:

• VIP customers
• Beta testers
• Event attendees

Endpoint

POST /list/create

Headers

Header	Value	Required
Authorization	Bearer <your-api-key>	✅ Yes
Content-Type	application/json	✅ Yes

Body Parameters

Parameter	Type	Required	Description
listName	String	✅ Yes	The name of the new list.
listDescription	String	✅ Yes	A description for the new list.
profiles	Array of Strings	❌ Optional	An initial set of profile IDs to associate with the list.

Examples

Request

JavaScript

const response = await fetch("https://api.basicsengage.com/api/v0/dev/list/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <your-api-key>"
  },
  body: JSON.stringify({
    listName: "Beta Testers",
    listDescription: "Users who signed up for beta",
    profiles: ["640cfa8d1", "640cfa8d2"]
  })
});

const data = await response.json();
console.log(data);

Python

import requests

url = "https://api.basicsengage.com/api/v0/dev/list/create"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <your-api-key>"
}
data = {
    "listName": "Beta Testers",
    "listDescription": "Users who signed up for beta",
    "profiles": ["640cfa8d1", "640cfa8d2"]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

C#

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    private static readonly HttpClient client = new HttpClient();

    static async Task Main()
    {
        var url = "https://api.basicsengage.com/api/v0/dev/list/create";
        var apiKey = "Bearer <your-api-key>";

        client.DefaultRequestHeaders.Clear();
        client.DefaultRequestHeaders.Add("Authorization", apiKey);

        var data = new
        {
            listName = "Beta Testers",
            listDescription = "Users who signed up for beta",
            profiles = new string[] { "640cfa8d1", "640cfa8d2" }
        };

        var json = System.Text.Json.JsonSerializer.Serialize(data);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.PostAsync(url, content);
        var responseString = await response.Content.ReadAsStringAsync();

        Console.WriteLine(responseString);
    }
}

PHP

<?php
$url = "https://api.basicsengage.com/api/v0/dev/list/create";

$headers = [
    "Content-Type: application/json",
    "Authorization: Bearer <your-api-key>"
];

$data = [
    "listName" => "Beta Testers",
    "listDescription" => "Users who signed up for beta",
    "profiles" => ["640cfa8d1", "640cfa8d2"]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

cURL

curl -X POST "https://api.basicsengage.com/api/v0/dev/list/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "listName": "Beta Testers",
    "listDescription": "Users who signed up for beta",
    "profiles": ["640cfa8d1", "640cfa8d2"]
  }'

---

Responses

🟢 200

{
  "status": "success",
  "data": {
    "listId": "64b22f999"
  }
}

🔴 400

{
  "status": "error",
  "error": "Missing required field: 'listName'."
}

🔴 401

{
  "status": "error",
  "message": "Invalid API Key"
}

🔴 500

{
  "status": "error",
  "message": "Internal server error. Please try again later."
}