Creating Lead Lists

Endpoint Overview

Create a new lead list to group and organize leads within your organization.

• HTTP Method: POST
• Endpoint URL: https://api.trywhiteowl.com/api/v1/lists
• Authentication: Bearer Token (API Key)
• Required Permission: list:create (Ensure your API key has Create permission under List)

---

Request Headers

Header	Type	Required	Description
Authorization	String	Yes	Bearer token format: Bearer YOUR_API_KEY
Content-Type	String	Yes	application/json

---

Request Body

Field	Type	Required	Description
name	String	Yes	The name of the new lead list.

Example Payload:

{
  "name": "Q4 Webinar Attendees"
}

---

Code Examples

cURL

curl -X POST "https://api.trywhiteowl.com/api/v1/lists" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 Webinar Attendees"
  }'

JavaScript (Fetch)

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Q4 Webinar Attendees'
  })
};

fetch('https://api.trywhiteowl.com/api/v1/lists', options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

Python (Requests)

import requests

url = "https://api.trywhiteowl.com/api/v1/lists"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "name": "Q4 Webinar Attendees"
}

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

---

Response Structure

Success Response (200 OK)

{
  "success": true,
  "message": "Successfully created a new list",
  "data": [
    {
      "id": 3,
      "name": "Q4 Webinar Attendees",
      "organization": "org_12345",
      "created_at": "2026-09-17T12:10:00Z"
    }
  ]
}

Error Responses

• Missing Required Field:

{
  "success": false,
  "message": "The field name is required"
}

• Missing Permissions (403 Forbidden):

{
  "success": false,
  "message": "Your API key does not have the 'list:create' permission"
}

• Internal / Server Error (500 Internal Server Error):

{
  "success": false,
  "message": "There was an error creating lead list"
}