---
title: "Search Contacts"
method: POST
path: "/contacts/search"
tags: ["Contacts"]
---

# Search Contacts

`POST /contacts/search`

## Request

- Base URL: `https://secure.fleetio.com/api`
- URL: `https://secure.fleetio.com/api/contacts/search`
- Auth: API key in header `Authorization` and API key in header `Account-Token`
- TypeScript: <https://skmtc.dev/fleetio/apis/fleetio-developer-api/docs/contacts/search/post.ts> (a function with typed inputs; its response is checked against the schema)

Returns a list of contacts excluding archived.  Matches behavior of `List` action, 
but accepts parameters including filters in request body.

## Request body

- object
  - `start_cursor` string
  - `per_page` integer
  - `filter` ContactFilters
    - `email` union
      - object
        - `like` string, required
      - object
        - `eq` string, required
    - `last_name` union
      - object
        - `like` string, required
      - object
        - `eq` string, required
    - `group_id` EqFilter
      - `eq` string, required
    - `employee_number` EqFilter
      - `eq` string, required
    - `created_at` union
      - object
        - `lt` string, required
      - object
        - `lte` string, required
      - object
        - `gt` string, required
      - object
        - `gte` string, required
    - `updated_at` union
      - object
        - `lt` string, required
      - object
        - `lte` string, required
      - object
        - `gt` string, required
      - object
        - `gte` string, required
  - `sort` ContactSorts
    - `group_id` 'asc' | 'desc'
    - `created_at` 'asc' | 'desc'
    - `updated_at` 'asc' | 'desc'
    - `id` 'asc' | 'desc'

## Response `200`

OK

- object
  - `start_cursor` string, nullable: The current start cursor of the records returned.
  - `next_cursor` string, nullable: The next cursor to retrieve the next page of records.
  - `per_page` integer: The maximum number of records returned.
  - `estimated_remaining_count` integer: The number of remaining records including the returned records, up to a maximum of 500.
  - `filtered_by` union[]: The filters applied to the returned record set.
    - union
      - object
        - `email` union
          - object
            - `like` string, required
          - object
            - `eq` string, required
      - object
        - `last_name` union
          - object
            - `like` string, required
          - object
            - `eq` string, required
      - object
        - `group_id` EqFilter
          - `eq` string, required
      - object
        - `employee_number` EqFilter
          - `eq` string, required
      - object
        - `created_at` union
          - object
            - `lt` string, required
          - object
            - `lte` string, required
          - object
            - `gt` string, required
          - object
            - `gte` string, required
      - object
        - `updated_at` union
          - object
            - `lt` string, required
          - object
            - `lte` string, required
          - object
            - `gt` string, required
          - object
            - `gte` string, required
  - `sorted_by` union[]: The sorts applied to the returned record set.
    - union
      - object
        - `group_id` 'asc' | 'desc'
      - object
        - `created_at` 'asc' | 'desc'
      - object
        - `updated_at` 'asc' | 'desc'
      - object
        - `id` 'asc' | 'desc'
  - `records` ContactSummary[]
    - `documents_count` integer, required: The number of documents associated with this Contact.
    - `comments_count` integer, required: The number of comments associated with this Contact.
    - `id` integer
    - `created_at` string, date-time: The date and time at which this record was created.
    - `updated_at` string, date-time: The date and time at which this record was most recently updated.
    - `email` string, nullable: The Contact's email address.
    - `name` string, nullable, required: The Contact's full name.
    - `first_name` string, nullable, required: The Contact's first name.
    - `middle_name` string, nullable, required: The Contact's middle name.
    - `last_name` string, nullable, required: The Contact's last name.
    - `group_id` integer, nullable, required: If this Contact belongs to a [Group](/docs/api/groups), this will be the Fleetio ID of that `Group`.
    - `group_name` string, nullable, required: If this Contact belongs to a [Group](/docs/api/groups), this will be the `Group`'s name.
    - `group_hierarchy` string, nullable: If this Contact belongs to a [Group](/docs/api/groups), this will be a pipe delimited string representing the `Group` hierarchy. Each `Group` in the list is the parent of the `Groups` which follow.
    - `technician` boolean, nullable: Whether or not the Contact is a Technician.
    - `vehicle_operator` boolean, nullable: Whether or not the Contact is a Vehicle Operator.
    - `employee` boolean, nullable: Whether or not the Contact is an Employee.
    - `birth_date` string, date, nullable: The Contact's birth date.
    - `street_address` string, nullable: The Contact's street address.
    - `street_address_line_2` string, nullable: The Contact's street address line 2.
    - `city` string, nullable: The Contact's city.
    - `region` string, nullable: The Contact's region, state, or province.
    - `postal_code` string, nullable: The Contact's postal code, zip code, or equivalent.
    - `country` string, nullable: The Contact's country.
    - `employee_number` string, nullable: The Contact's employee number.
    - `job_title` string, nullable: The Contact's job title.
    - `license_class` string, nullable: The Contact's driver's license class.
    - `license_number` string, nullable: The Contact's driver's license number.
    - `license_state` string, nullable: The locality which issued the Contact's license.
    - `home_phone_number` string, nullable: The Contact's home phone number.
    - `mobile_phone_number` string, nullable: The Contact's mobile phone number.
    - `work_phone_number` string, nullable: The Contact's work phone number.
    - `other_phone_number` string, nullable: Any other phone number for this Contact.
    - `start_date` string, date, nullable: When the Contact started working for the company, if applicable.
    - `leave_date` string, date, nullable: When the Contact left or will leave the company, if applicable.
    - `hourly_labor_rate_cents` integer, nullable: The Contact's hourly rate in cents.
    - `attachment_permissions` AttachmentPermissions, nullable
      - `read_photos` boolean: Indicates whether the user has read permission for photos.
      - `manage_photos` boolean: Indicates whether the user has permission to manage (eg. upload, delete) photos.
      - `read_documents` boolean: Indicates whether the user has read permission for documents.
      - `manage_documents` boolean: Indicates whether the user has permission to manage (eg. upload, delete) documents.
    - `default_image_url` string, nullable, required: The URL of the Contact's default image/profile photo, if any.
    - `account_membership_id` integer, nullable
    - `last_api_request` string, date-time, nullable: The last date and time this Contact's associated User made an API request. Null if Contact is not assocated with a User.
    - `last_web_access` string, date-time, nullable: The last date and time this Contact's associated User signed into the web application. Null if Contact is not assocated with a User.
    - `last_mobile_app_access` string, date-time, nullable: The last date and time this Contact's associated User used the mobile app. Null if Contact is not assocated with a User.
    - `custom_fields` CustomFields, nullable: *Full details on working with Custom Fields [here](/docs/overview/custom-fields).
    - `images` Image2[]: A list of the images attached to this record.
      - `id` integer, required
      - `created_at` string, date-time: The date and time at which this record was created.
      - `updated_at` string, date-time: The date and time at which this record was most recently updated.
      - `imageable_id` integer
      - `imageable_type` 'ExpenseEntry' | 'WorkOrder' | 'Equipment' | 'IssueResolution' | 'ServiceEntry' | 'Vendor' | 'ServiceProgram' | 'Issue' | 'Contact' | 'Part' | 'Vehicle' | 'FuelEntry' | 'SubmittedInspectionItem'
      - `file_name` string: The name of the image file.
      - `file_mime_type` 'image/jpeg' | 'image/gif' | 'image/jif' | 'image/jfif' | 'image/jfi' | 'image/tiff' | 'image/png' | 'image/jpg' | 'image/jpe' | 'image/pdf' | 'image/webp' | 'image/tif' | 'image/psd' | 'image/raw' | 'image/arw' | 'image/cr2' | 'image/nrw' | 'image/k25' | 'image/bmp' | 'image/dip' | 'image/ai' | 'image/eps' | 'image/heif' | 'image/heic' | 'image/ind' | 'image/indd' | 'image/indt' | 'image/jp2' | 'image/j2k' | 'image/jpf' | 'image/jpx' | 'image/jpm' | 'image/mj2' | 'image/x-png'
      - `file_size` number: The size of the image file in bytes.
      - `file_url` string: The URL to access the image file.
      - `full_url` string: The full URL to access the image file, including any necessary authentication or parameters.
    - `images_count` integer, required: The number of images attached to this record.
    - `account_membership` object, nullable: The Contacts' access configurations for the current account. This field is only returned when the current API user has the `Manage Users` permission.
      - `id` integer: The id of the AccountMembership of this Contact.
      - `user_type` 'admin' | 'owner' | 'regular': The Contacts' access level within the account.
      - `regular_user_role` object, nullable
        - `id` integer: The id of the regular user role for this Contact.
        - `name` string: The name of the regular user role for this Contact.

## Other responses

- `400`: The format or parameters of the request was invalid
- `401`: Request could not be authenticated
- `500`: Something unexpected happened

## Changes

- **2026-11-06** `49558d744bd7`: 4 info
  - the `per_page` request property's min was decreased from `2.00` to `1.00`
  - added the optional property `records/items/account_membership` to the response with the `200` status
  - added the required property `records/items/comments_count` to the response with the `200` status
  - added the required property `records/items/documents_count` to the response with the `200` status
- **2026-06-16** `4098a1c81821`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fleetio/apis/fleetio-developer-api/changes/contacts/search/post.md)

---

[API](https://skmtc.dev/fleetio/apis/fleetio-developer-api.md) - [All operations](https://skmtc.dev/fleetio/apis/fleetio-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fleetio/apis/fleetio-developer-api/revisions/49558d744bd7?raw)