Searching contacts

This recipe finds contacts matching a search term, orders the results by last name, limits the page size, and embeds each contact’s owner — building up one request to the contacts list endpoint step by step.

Search by term

Start with a search filter, which matches fuzzily across first name, last name, and email:

curl "https://api.contractorscloud.com/api/v1/contacts?filter[search]=miller" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Add sorting and pagination

Order the matches by last name and cap the page at 10 results:

curl "https://api.contractorscloud.com/api/v1/contacts?filter[search]=miller&sort=last_name&page[size]=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Embed the owner

Add include=owner so each contact carries the user who owns it, avoiding a second request:

curl "https://api.contractorscloud.com/api/v1/contacts?filter[search]=miller&sort=last_name&page[size]=10&include=owner" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": 5104,
      "first_name": "Rachel",
      "last_name": "Miller",
      "email": "rachel.miller@example.com",
      "owner": {
        "id": 1159,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@example.com"
      }
    },
    {
      "id": 5107,
      "first_name": "Thomas",
      "last_name": "Miller",
      "email": "thomas.miller@example.com",
      "owner": {
        "id": 1159,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane.doe@example.com"
      }
    }
  ],
  "current_page": 1,
  "per_page": 10,
  "total": 2
}

Look up an exact match

If you already know the exact phone number or email address, skip the fuzzy search filter and use filter[phone] or filter[email] instead:

curl "https://api.contractorscloud.com/api/v1/contacts?filter[phone]=(555)%20201-4477" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

filter[phone] accepts any common format — digits are compared after stripping everything else, so 5552014477, (555) 201-4477, and +15552014477 all match the same contact, against any of its phone numbers (home, work, cell, fax). filter[email] requires the full address rather than a partial one, and matches case-insensitively against either the contact’s email or alternate email.

Next steps

Filtering and sorting — the full filter and sort syntax shared across list endpoints.
Pagination — page parameters and the complete response envelope.
Relationships — include and append syntax for embedding related data.
List contacts — the full reference for this endpoint, including every allowed filter, sort, and include.
Extended properties — attach and search custom metadata on contacts.

Concepts

Domains

Examples

Search by term

Embed the owner

Response

Look up an exact match

Next steps

​Search by term

​Add sorting and pagination

​Embed the owner

​Response

​Look up an exact match

​Next steps

Search by term

Add sorting and pagination

Embed the owner

Response

Look up an exact match

Next steps