Get all people lists

What it does

Returns the people lists reachable from your API key: lists created via the API, lists with “Share to API” turned on, and global lists curated by Specter. Lists shared only within your team are not returned.

Why you’d use it

Discover which people cohorts you can work with and see their sizes before fetching individual records.

Key behaviors

• Each list object includes the number of people in the list.
• To retrieve the people IDs in a list, call the corresponding GET endpoint with that list’s ID.
• Only lists that meet the availability criteria above are returned.

GET /lists/people

Get all people lists

cURL

curl --request GET \
  --url https://app.tryspecter.com/api/v1/lists/people \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://app.tryspecter.com/api/v1/lists/people"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://app.tryspecter.com/api/v1/lists/people', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.tryspecter.com/api/v1/lists/people",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://app.tryspecter.com/api/v1/lists/people"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://app.tryspecter.com/api/v1/lists/people")
  .header("X-API-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.tryspecter.com/api/v1/lists/people")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

200

[
  {
    "id": "b73c8bed-3b92-48f9-a879-40ee114dca03",
    "name": "Favourites",
    "created_at": "2024-11-14T10:36:12.625Z",
    "updated_at": "2024-11-14T10:36:12.625Z",
    "is_global": false,
    "people_count": 10,
    "shared_with": [
      "user_2PFJ2V8IR837k6TPguVCIFhNsWA"
    ]
  }
]

{
  "errorCode": "API_KEY_MISSING",
  "message": "No API Key was presented on the header X-API-KEY"
}

{
  "errorCode": "NOT_PERMITTED",
  "message": "You do not have permission to access this resource."
}

{
  "errorCode": "<string>",
  "message": "<string>"
}

Authorizations

X-API-Key · string · header · required

Response

200

application/json

The people lists

id · string

List Id

Example:

"b73c8bed-3b92-48f9-a879-40ee114dca03"

name · string

Name of the list

Example:

"Favourites"

created_at · string<date-time>

Date list was created

Example:

"2024-11-14T10:36:12.625Z"

updated_at · string<date-time>

Date the list was last updated

Example:

"2024-11-14T10:36:12.625Z"

is_global · boolean

This flags lists recommended by Specter for all users

Example:

false

people_count · number

The number of people in this list

Example:

10

shared_with · string[]

The user ids of the users this list is shared with

User Id