Skip to main content

​
GET contacts

Fetch a list of contacts. GET /user-api/v1/contacts

​
Query Parameters

​
limit
string
Set a limit to the number of records to return (Default:25)
​
offset
string
Number of records to skip.
​
order_by
string
Sort order: updated_at:asc, updated_at:desc, created_at:asc, created_at:desc, last_team_interaction:asc, last_team_interaction:desc, full_name:asc, full_name:desc
​
include
string
Related data to include: emails, phone_numbers, companies, custom_fields, tags, lists, notes

​
Headers

HeaderValue
x-rolodex-api-keyf1e2d3c4b5a697...

​
Response

{
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1000
  },
  "data": [
    {
      "id": "contact_12345",
      "full_name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "title": "Software Engineer",
      "description": "Senior software engineer specializing in backend systems",
      "location": "San Francisco, CA",
      "image_url": "https://example.com/avatar.jpg",
      "linkedin_slug": "johndoe",
      "website_url": "https://johndoe.com",
      "x_slug": "johndoe",
      "facebook_slug": "johndoe",
      "instagram_slug": "johndoe",
      "birthday_day": 15,
      "birthday_month": 3,
      "birthday_year": 1990,
      "is_starred": false,
      "ignore_merge": false,
      "last_team_interaction": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ]
}

​
With Include Parameters

GET /user-api/v1/contacts?include=emails,phone_numbers,companies,custom_fields,tags,lists,notes

​
Response with all includes

{
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1000
  },
  "data": [
    {
      "id": "contact_12345",
      "full_name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "title": "Software Engineer",
      "description": "Senior software engineer specializing in backend systems",
      "location": "San Francisco, CA",
      "image_url": "https://example.com/avatar.jpg",
      "linkedin_slug": "johndoe",
      "website_url": "https://johndoe.com",
      "x_slug": "johndoe",
      "facebook_slug": "johndoe",
      "instagram_slug": "johndoe",
      "birthday_day": 15,
      "birthday_month": 3,
      "birthday_year": 1990,
      "is_starred": false,
      "ignore_merge": false,
      "last_team_interaction": "2025-01-15T10:30:00Z",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z",
      "emails": [
        {
          "id": "email_123",
          "email_address": "john@example.com",
          "is_primary": true
        }
      ],
      "phone_numbers": [
        {
          "id": "phone_456",
          "phone_number": "5551234567",
          "country_code": "+1",
          "is_primary": true
        }
      ],
      "companies": [
        {
          "id": "company_789",
          "name": "Acme Corp",
          "title": "Senior Software Engineer",
          "is_active": true,
          "start_date": "2023-01-15"
        }
      ],
      "custom_fields": [
        {
          "id": "field_101",
          "name": "Lead Score",
          "field_type": "NUMERIC",
          "value": 85
        },
        {
          "id": "field_102",
          "name": "Department",
          "field_type": "SINGLE_LINE_TEXT",
          "value": "Engineering"
        },
        {
          "id": "field_103",
          "name": "Status",
          "field_type": "SINGLE_SELECT",
          "value": {
            "id": "option_101",
            "value": "Active"
          }
        },
        {
          "id": "field_104",
          "name": "Skills",
          "field_type": "MULTI_SELECT",
          "value": [
            {
              "id": "option_201",
              "value": "JavaScript"
            },
            {
              "id": "option_202",
              "value": "React"
            }
          ]
        }
      ],
      "tags": [
        {
          "tag": {
            "id": "tag_123",
            "name": "Lead"
          }
        }
      ],
      "lists": [
        {
          "list": {
            "id": "list_456",
            "name": "Q1 Prospects"
          }
        }
      ],
      "notes": [
        {
          "note": {
            "id": "note_789",
            "body": "Great conversation about their tech stack"
          }
        }
      ]
    }
  ]
}

​
GET Contact by ID

Pass a contact id and fetches the full contact information. GET /user-api/v1/contacts/:id

​
Path Parameters

​
id
string
Contact ID

​
Query Parameters

​
include
string
Related data to include: emails, phone_numbers, companies, custom_fields, tags, lists, notes

​
Endpoint Example

GET /user-api/v1/contacts/contact_12345?include=emails,phone_numbers,companies

​
Response

{
  "data": {
    "id": "contact_12345",
    "full_name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "title": "Software Engineer",
    "description": "Senior software engineer specializing in backend systems",
    "location": "San Francisco, CA",
    "image_url": "https://example.com/avatar.jpg",
    "linkedin_slug": "johndoe",
    "website_url": "https://johndoe.com",
    "x_slug": "johndoe",
    "facebook_slug": "johndoe",
    "instagram_slug": "johndoe",
    "birthday_day": 15,
    "birthday_month": 3,
    "birthday_year": 1990,
    "is_starred": false,
    "ignore_merge": false,
    "last_team_interaction": "2025-01-15T10:30:00Z",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}