List contacts

List contacts

curl --request GET \
  --url https://api.contractorscloud.com/api/v1/contacts \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.contractorscloud.com/api/v1/contacts', 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://api.contractorscloud.com/api/v1/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$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://api.contractorscloud.com/api/v1/contacts"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.contractorscloud.com/api/v1/contacts")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "current_page": 1,
  "data": [
    {
      "id": 4821,
      "tenant_id": 12,
      "owned_by": 1159,
      "nick_name": null,
      "first_name": "Jane",
      "last_name": "Smith",
      "prefix": "Ms.",
      "title": "Project Manager",
      "department": "Operations",
      "email": "jane.smith@example.com",
      "email_alt": null,
      "phone_home": null,
      "phone_cell": "(555) 201-4477",
      "phone_fax": null,
      "phone_work": "(555) 201-4400",
      "phone_work_ext": "118",
      "address_street": "482 Birchwood Ave",
      "address_city": "Madison",
      "address_state": "WI",
      "address_zip": "53703",
      "status": true,
      "comment": null,
      "merge_status": 0,
      "import_name": null,
      "import_id": null,
      "created_at": "2024-11-02 14:35:09",
      "updated_at": "2025-01-08 09:12:44"
    }
  ],
  "first_page_url": "https://api.contractorscloud.com/api/v1/contacts?page[number]=1",
  "from": 1,
  "last_page": 4,
  "last_page_url": "https://api.contractorscloud.com/api/v1/contacts?page[number]=4",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "https://api.contractorscloud.com/api/v1/contacts?page[number]=1",
      "label": "1",
      "active": true
    },
    {
      "url": "https://api.contractorscloud.com/api/v1/contacts?page[number]=2",
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": "https://api.contractorscloud.com/api/v1/contacts?page[number]=2",
  "path": "https://api.contractorscloud.com/api/v1/contacts",
  "per_page": 30,
  "prev_page_url": null,
  "to": 30,
  "total": 97
}

{
  "message": "Unauthenticated."
}

GET

contacts

List contacts

curl --request GET \
  --url https://api.contractorscloud.com/api/v1/contacts \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.contractorscloud.com/api/v1/contacts', 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://api.contractorscloud.com/api/v1/contacts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$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://api.contractorscloud.com/api/v1/contacts"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.contractorscloud.com/api/v1/contacts")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "current_page": 1,
  "data": [
    {
      "id": 4821,
      "tenant_id": 12,
      "owned_by": 1159,
      "nick_name": null,
      "first_name": "Jane",
      "last_name": "Smith",
      "prefix": "Ms.",
      "title": "Project Manager",
      "department": "Operations",
      "email": "jane.smith@example.com",
      "email_alt": null,
      "phone_home": null,
      "phone_cell": "(555) 201-4477",
      "phone_fax": null,
      "phone_work": "(555) 201-4400",
      "phone_work_ext": "118",
      "address_street": "482 Birchwood Ave",
      "address_city": "Madison",
      "address_state": "WI",
      "address_zip": "53703",
      "status": true,
      "comment": null,
      "merge_status": 0,
      "import_name": null,
      "import_id": null,
      "created_at": "2024-11-02 14:35:09",
      "updated_at": "2025-01-08 09:12:44"
    }
  ],
  "first_page_url": "https://api.contractorscloud.com/api/v1/contacts?page[number]=1",
  "from": 1,
  "last_page": 4,
  "last_page_url": "https://api.contractorscloud.com/api/v1/contacts?page[number]=4",
  "links": [
    {
      "url": null,
      "label": "&laquo; Previous",
      "active": false
    },
    {
      "url": "https://api.contractorscloud.com/api/v1/contacts?page[number]=1",
      "label": "1",
      "active": true
    },
    {
      "url": "https://api.contractorscloud.com/api/v1/contacts?page[number]=2",
      "label": "Next &raquo;",
      "active": false
    }
  ],
  "next_page_url": "https://api.contractorscloud.com/api/v1/contacts?page[number]=2",
  "path": "https://api.contractorscloud.com/api/v1/contacts",
  "per_page": 30,
  "prev_page_url": null,
  "to": 30,
  "total": 97
}

{
  "message": "Unauthenticated."
}

Authorizations

Authorization

string

header

required

Authenticate with an API access token in the Authorization header: Authorization: Bearer <token>. Create a token from the API Access Tokens page in Contractors Cloud, under Integrations.

Query Parameters

page[number]

integer

default:1

The 1-indexed page number to retrieve.

Required range: x >= 1

page[size]

integer

default:30

The number of results per page (max 100).

Required range: 1 <= x <= 100

filter[id]

integer

Exact match on the contact's id.

filter[status]

boolean

Exact match on the contact's active status (1 or 0).

filter[first_name]

string

Partial match on first name.

filter[last_name]

string

Partial match on last name.

filter[email]

string

Exact match on the contact's email address or alternate email address. Comparison is case-insensitive.

filter[phone]

string

Exact match on any of the contact's phone numbers (home, work, cell, fax). Accepts any common format — digits are compared after stripping everything else, so +13334445555, (333) 444-5555, 333.444.5555, and 3334445555 are all equivalent.

filter[search]

string

Fuzzy search across first name, last name, and email.

filter[has_email]

boolean

Limit to contacts that have (1) or lack (0) an email address.

filter[extended_property]

object

Filters by an extended property's key and value, using the syntax filter[extended_property][<key>]=<value>. Matches contacts with an extended property whose key equals <key> and whose value exactly equals <value> (comma-separate multiple values to match any of them).

Hide child attributes

filter[extended_property].{key}]

string

include

string

Comma-separated related resources to embed. Allowed: owner, extended_properties.

sort

string

Field to sort by. Prefix with - for descending. Allowed: first_name, last_name, email, address_street, address_city, address_state, phone_home, phone_work, phone_cell, status, created_at, updated_at.

Response

A paginated list of contacts.

data

object[]

Hide child attributes

data.id

integer

The contact's unique identifier.

Example:

4821

data.tenant_id

integer

The id of your organization's account.

Example:

12

data.owned_by

integer | null

The id of the user in your organization who owns this contact. Null if the contact has no assigned owner.

Example:

1159

data.nick_name

string | null

The contact's nickname or preferred name. Null if not set.

data.first_name

string

The contact's first name.

Example:

"Jane"

data.last_name

string

The contact's last name.

Example:

"Smith"

data.prefix

string | null

A name prefix or salutation (for example Ms. or Dr.). Null if not set.

Example:

"Ms."

data.title

string | null

The contact's job title. Null if not set.

Example:

"Project Manager"

data.department

string | null

The department the contact belongs to at their organization. Null if not set.

Example:

"Operations"

data.email

string | null

The contact's primary email address. Null if not provided.

Example:

"jane.smith@example.com"

data.email_alt

string | null

An alternate email address for the contact. Null if not provided.

data.phone_home

string | null

The contact's home phone number. Null if not provided.

data.phone_cell

string | null

The contact's cell phone number. Null if not provided.

Example:

"(555) 201-4477"

data.phone_fax

string | null

The contact's fax number. Null if not provided.

data.phone_work

string | null

The contact's work phone number. Null if not provided.

Example:

"(555) 201-4400"

data.phone_work_ext

string | null

Extension for the contact's work phone number. Null if not applicable.

Example:

"118"

data.address_street

string | null

The street portion of the contact's address. Null if not provided.

Example:

"482 Birchwood Ave"

data.address_city

string | null

The city portion of the contact's address. Null if not provided.

Example:

"Madison"

data.address_state

string | null

The two-letter state or province code for the contact's address. Null if not provided.

Example:

"WI"

data.address_zip

string | null

The postal code for the contact's address. Null if not provided.

Example:

"53703"

data.status

boolean

Whether the contact is active. Deleting a contact that has other contacts linked to it deactivates it (sets this to false) instead of permanently removing it.

Example:

true

data.comment

string | null

Free-form notes about the contact. Null if not set.

data.merge_status

enum<integer>

The contact's merge designation, used when deduplicating contacts. 0 = no designation, 1 = marked as the contact to keep in a pending merge, 2 = marked to be merged away and removed. Most integrations can ignore it.

Available options:

0,

1,

2

Example:

0

data.import_name

string | null

The name of the bulk import batch that created this contact, if it was created via import. Null otherwise.

data.import_id

integer | null

The id of the bulk import batch that created this contact, if it was created via import. Null otherwise.

data.created_at

string | null

Timestamp when the contact was created, formatted as YYYY-MM-DD HH:MM:SS. Can be null for contacts created before timestamps were tracked.

Example:

"2024-11-02 14:35:09"

data.updated_at

string | null

Timestamp when the contact was last updated, formatted as YYYY-MM-DD HH:MM:SS. Can be null if the contact has never been updated.

Example:

"2025-01-08 09:12:44"

current_page

integer

The 1-indexed page number of the current response.

Example:

1

first_page_url

string

The URL of the first page of results.

from

integer | null

The 1-indexed position of the first record in data for this page. Null when the page is empty.

Example:

1

last_page

integer

The number of the final page in the result set.

Example:

4

last_page_url

string

The URL of the last page of results.

links

object[]

Rendered pagination links (previous, numbered pages, next).

Hide child attributes

links.url

string | null

The target URL for this link, or null if the link isn't clickable (for example, the current page).

links.label

string

Display label for the link, such as a page number or Next ».

links.active

boolean

Whether this link represents the current page.

next_page_url

string | null

The URL of the next page, or null if this is the last page.

path

string

The endpoint URL without query parameters.

per_page

integer

The number of records requested per page.

Example:

30

prev_page_url

string | null

The URL of the previous page, or null if this is the first page.

integer | null

The 1-indexed position of the last record in data for this page. Null when the page is empty.

Example:

30

total

integer

The total number of records across all pages.

Example:

97

Getting Started

Reference

Authorizations

Query Parameters

Response