Skip to main content
GET
/
v1
/
contacts
List Contacts
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.topo.io/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "items": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "first_seen_at": "2023-11-07T05:31:56Z",
      "last_seen_at": "2023-11-07T05:31:56Z",
      "email": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "job_title": "<string>",
      "linkedin_url": "<string>",
      "phone_number": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "profile_picture_url": "<string>",
      "company_name": "<string>",
      "company_domain": "<string>"
    }
  ],
  "total_count": 123,
  "total_pages": 123,
  "has_more": true
}

Authorizations

Authorization
string
header
required

Bearer API key issued from Settings → Developers.

Query Parameters

page
integer
default:1

Page number.

Required range: x >= 1
size
integer
default:10

Number of items per page.

Required range: 1 <= x <= 100
sort_by
enum<string> | null

Field to sort by.

Available options:
first_seen_at,
last_seen_at,
email
sort_order
enum<string>
default:asc

Sort direction.

Available options:
asc,
desc
email
string | null

Filter by email (case-insensitive exact match).

linkedin_url
string | null

Filter by LinkedIn profile URL. Matched against all known canonical variants (trailing slash, www. prefix, etc.).

contact_id
string<uuid> | null

Filter by contact ID.

first_seen_after
string<date-time> | null

Return people first seen strictly after this timestamp.

last_seen_after
string<date-time> | null

Return people last seen strictly after this timestamp.

Response

200 - application/json

Successful Response

items
PublicContactOutput · object[]
required

Records on this page.

total_count
integer
required

Total number of records matching the query.

total_pages
integer
required

Total number of pages.

has_more
boolean
required

Whether more pages remain after the current one.