---
updatedAt: 2026-04-20T19:14:52.000Z
agentTools:
  projectIndex: https://developers.nutshell.com/llms.txt
---

# Get a list of contacts

Returns a number of contacts which is filterable based on their basic information.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Nutshell API",
    "description": "The most powerful API in the world",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "app.nutshell.com/rest"
    }
  ],
  "paths": {
    "/contacts": {
      "get": {
        "tags": [
          "Contacts (People)"
        ],
        "summary": "Get a list of contacts",
        "description": "Returns a number of contacts which is filterable based on their basic information.",
        "operationId": "cde301caba6b033521a71e6bed772a58",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "description": "Returns contacts with the provided email address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Returns contacts with a piece of information similar to the provided string, such as name, email, location, etc.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "What criteria to order the returned list of results. Without this parameter, contacts are ordered by given name in ascending order. For name sorting, contacts with blank names are returned last in both ascending and descending order.",
            "schema": {
              "type": "string",
              "enum": [
                "accountType",
                "-accountType",
                "accounts",
                "-accounts",
                "createdTime",
                "-createdTime",
                "email",
                "-email",
                "industry",
                "-industry",
                "lastContactedTime",
                "-lastContactedTime",
                "name",
                "-name",
                "owner",
                "-owner",
                "phone",
                "-phone",
                "postalCode",
                "-postalCode",
                "territory",
                "-territory"
              ]
            }
          },
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "style": "deepObject",
            "explode": true,
            "schema": {
              "description": "Filter the returned contacts based on various criteria. Use /rest/contacts/list/fields to get a full list of valid filter keys.",
              "type": "object",
              "additionalProperties": {
                "$ref": "#/components/schemas/FilterInput"
              }
            }
          },
          {
            "name": "page[page]",
            "in": "query",
            "description": "The page of results to return. Indexing is 0-based.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page[limit]",
            "in": "query",
            "description": "How many results to return per page",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contact",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "FilterInput": {
        "description": "The key-value pair for the filter, ex. filter[tags]=1-tags",
        "type": "string"
      },
      "ContactResponse": {
        "description": "A full response object for a contact-related endpoint.",
        "properties": {
          "links": {
            "description": "Where to get related entities.",
            "type": "object"
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FullContact"
            }
          }
        },
        "type": "object"
      },
      "FullContact": {
        "description": "An individual contact with all fields.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Contact"
          },
          {
            "$ref": "#/components/schemas/HtmlLinkable"
          },
          {
            "$ref": "#/components/schemas/Avatarable"
          },
          {
            "properties": {
              "links": {
                "description": "The entity IDs of related entities.",
                "type": "object"
              }
            },
            "type": "object"
          }
        ]
      },
      "Contact": {
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/Peep"
          },
          {
            "$ref": "#/components/schemas/Avatarable"
          },
          {
            "$ref": "#/components/schemas/HtmlLinkable"
          },
          {
            "properties": {
              "jobTitle": {
                "description": "The person's role at their company.",
                "example": "CEO"
              },
              "firstName": {
                "description": "The person's given name.",
                "example": "Andy"
              },
              "lastName": {
                "description": "The person's family name.",
                "example": "Fowler"
              },
              "href": {
                "description": "The URL to fetch this contact.",
                "type": "string",
                "example": "https://app.nutshell.com/rest/contacts/3-contacts"
              }
            },
            "type": "object"
          }
        ]
      },
      "Peep": {
        "properties": {
          "id": {
            "description": "The API ID of this entity, formatted {integer}-{entityType}",
            "type": "string",
            "example": "3-contacts"
          },
          "name": {
            "description": "The entity's full name.",
            "type": "string",
            "example": "Andy Nutshell"
          },
          "description": {
            "description": "A brief explanation of this entity which appears under their name.",
            "type": "string",
            "example": "CEO / cofounder @ Nutshell. Building growth software, wrangling beagles 🐶"
          },
          "createdTime": {
            "description": "Unix timestamp",
            "type": "integer",
            "format": "int64"
          },
          "deletedTime": {
            "description": "Unix timestamp",
            "type": "integer",
            "format": "int64"
          },
          "emails": {
            "$ref": "#/components/schemas/emails"
          },
          "addresses": {
            "$ref": "#/components/schemas/addresses"
          },
          "phones": {
            "$ref": "#/components/schemas/phones"
          },
          "urls": {
            "$ref": "#/components/schemas/urls"
          }
        },
        "type": "object"
      },
      "emails": {
        "description": "All email addresses associated with an entity.",
        "type": "array",
        "items": {
          "properties": {
            "isPrimary": {
              "description": "If entity has multiple email addresses, which should be used as the primary point of contact.",
              "type": "boolean",
              "example": true
            },
            "name": {
              "description": "A label for the email address, e.g. 'work', 'personal', 'support'.",
              "type": "string",
              "example": "personal"
            },
            "value": {
              "description": "The email address itself.",
              "type": "string",
              "example": "andy@nutshell.com"
            }
          },
          "type": "object"
        }
      },
      "addresses": {
        "description": "All addresses associated with an entity.",
        "type": "array",
        "items": {
          "properties": {
            "isPrimary": {
              "description": "Should this address be used if there are multiple",
              "type": "boolean",
              "example": true
            },
            "name": {
              "description": "A label for the address, e.g. 'work', 'home', 'shipping'.",
              "type": "string",
              "example": "address"
            },
            "value": {
              "description": "The geographic coordinates for the address.",
              "properties": {
                "location": {
                  "properties": {
                    "longitude": {
                      "type": "number",
                      "example": -83.732124
                    },
                    "latitude": {
                      "type": "number",
                      "example": 42.279594
                    }
                  },
                  "type": "object"
                }
              },
              "type": "object"
            },
            "locationAccuracy": {
              "description": "How specific the address is. 8 is an exact street address, 1 is only a country.",
              "type": "string",
              "example": "8"
            },
            "address_1": {
              "description": "Primary street address",
              "type": "string",
              "example": "206 E Huron St"
            },
            "address_2": {
              "description": "Secondary street address, such as a suite or apartment number",
              "type": "string",
              "example": "Suite 200"
            },
            "address_3": {
              "type": "string"
            },
            "city": {
              "description": "City or town",
              "type": "string",
              "example": "Ann Arbor"
            },
            "state": {
              "description": "State or province",
              "type": "string",
              "example": "MI"
            },
            "postalCode": {
              "description": "ZIP or postal code",
              "type": "string",
              "example": "48103"
            },
            "country": {
              "description": "Country code",
              "type": "string",
              "example": "US"
            },
            "timezone": {
              "type": "string"
            }
          },
          "type": "object"
        }
      },
      "phones": {
        "type": "array",
        "items": {
          "properties": {
            "isOptedOut": {
              "description": "If this number has opted out of receiving SMS messages",
              "type": "boolean",
              "example": true
            },
            "isPrimary": {
              "description": "Should this phone number be used if there are multiple",
              "type": "boolean",
              "example": true
            },
            "name": {
              "description": "A label for the phone number, e.g. 'work', 'home', 'mobile'.",
              "type": "string",
              "example": "phone"
            },
            "value": {
              "properties": {
                "countryCode": {
                  "description": "Phone number prefix for calling individuals in other countries",
                  "type": "string",
                  "example": "1"
                },
                "number": {
                  "description": "The unformatted phone number with only digits",
                  "type": "string",
                  "example": "7341234567"
                },
                "extension": {
                  "description": "An additional code to reach a specific person or department which share a number",
                  "type": "string",
                  "example": "123"
                },
                "numberFormatted": {
                  "description": "The phone number formatted for human readability",
                  "type": "string",
                  "example": "734-123-4567"
                },
                "E164": {
                  "description": "The phone number formatted for international use; a common programatic standard for working with phone numbers",
                  "type": "string",
                  "example": "+17341234567"
                },
                "countryCodeAndNumber": {
                  "description": "The phone number formatted for human readability with the country code",
                  "type": "string",
                  "example": "+1 734-123-4567"
                }
              },
              "type": "object"
            }
          },
          "type": "object"
        }
      },
      "urls": {
        "type": "array",
        "items": {
          "properties": {
            "isPrimary": {
              "description": "Should this URL be used if there are multiple",
              "type": "boolean",
              "example": true
            },
            "name": {
              "description": "A label for the URL, e.g. 'LinkedIn', 'Facebook', 'personal website'.",
              "type": "string",
              "example": "LinkedIn"
            },
            "value": {
              "description": "The URL itself",
              "type": "string",
              "example": "https://www.linkedin.com"
            }
          },
          "type": "object"
        }
      },
      "Avatarable": {
        "properties": {
          "avatarUrl": {
            "description": "The URL of the entity's avatar image.",
            "type": "string",
            "example": "https://app.nutshell.com/avatars/contacts/1006/{path}"
          },
          "initials": {
            "description": "The initials of the entity, used as a fallback for the avatar image.",
            "type": "string",
            "example": "AF"
          }
        },
        "type": "object"
      },
      "HtmlLinkable": {
        "description": "Adds an htmlUrl string attribute that represents a URL of an HTML representation of the\nresponse model.",
        "properties": {
          "htmlUrl": {
            "description": "The link to the entity within the app.",
            "type": "string",
            "example": "https://app.nutshell.com/lead/1006"
          },
          "htmlUrlPath": {
            "description": "The path to the entity within the app.",
            "type": "string",
            "example": "/lead/1006"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "tags": [
    {
      "name": "Contacts (People)",
      "description": "Contacts (People)"
    }
  ]
}
```