--- title: "Find contacts" method: GET path: "/contacts" tags: ["Contacts"] --- # Find contacts `GET /contacts` ## Request - Base URL: `https://inboxapp.com/api/v2` - URL: `https://inboxapp.com/api/v2/contacts` - Auth: HTTP bearer Finds contacts by the platform identity of one of their profiles: a `platform` with `platformId` or `username`. ## Query parameters - `platform` Platform[]: Contacts with a profile on these platforms. Defaults to every platform available to the team. `platformId` needs exactly one. Repeat the key to match any of several. - `platformId` string[]: Contacts with a profile of this platform ID. Give one of `platformId`, `username` or `q`, repeating the key for up to 100. No match is an empty page. - `username` string[]: Contacts with a profile of this username, without its display prefix. One username may match several contacts. Give one of `platformId`, `username` or `q`, repeating the key for up to 100. No match is an empty page. - `q` string: Searches contact and profile names, usernames, emails and phone numbers. Not combinable with `platformId` or `username`. Results follow `createdAt`, not relevance, and can trail changes by a few seconds. - `expand` string[]: Related resources to embed next to their ID field, one path per key, at most 4. - `limit` integer: Page size, from 1 to 100. Defaults to 50. - `cursor` string: The previous page's `nextCursor`. Opaque, and valid only with the filters it was issued for. ## Response `200` OK - ContactPage: Ordered by `createdAt`, oldest first. - `data` Contact[], required - `id` string, required - `profiles` Profile[], required: The person's profiles, oldest link first. Profiles on platforms unavailable to the team are left out. - `id` string, required - `platform` string, required: The platform. Every team can use twitter, linkedin; a team may have others enabled. - `platformId` string, required: The ID the platform gives this object. Only meaningful next to its `platform`. - `username` string, required: The platform username, without a display prefix such as `@`. - `handle` string, required: The username as the platform displays it. Show this, and look up by `username`. - `displayName` string, required - `avatarUrl` string, nullable, required - `bio` string, nullable, required - `location` string, nullable, required - `websiteUrl` string, nullable, required - `websiteDomain` string, nullable, required - `verified` boolean, required: The platform vouches for the account, such as with an X badge. Platform-specific badges are in `platformData`. - `isOrganization` boolean, required: A company or page rather than a person. - `isProtected` boolean, required: The account's posts are visible only to approved followers. - `followerCount` union, required - number - 'Infinity' | '-Infinity' | 'NaN' - `followingCount` union, required - number - 'Infinity' | '-Infinity' | 'NaN' - `postCount` union, required - number - 'Infinity' | '-Infinity' | 'NaN' - `engagementCount` union, required: On X, how many posts the user has liked. - number - 'Infinity' | '-Infinity' | 'NaN' - `listedCount` union, required: On X, how many lists include the profile. - number - 'Infinity' | '-Infinity' | 'NaN' - `accountStatus` 'active' | 'suspended' | 'notFound', required: `suspended` by the platform, or `notFound` when deleted or deactivated. - `platformCreatedAt` string, date-time, nullable, required: When the account was created on the platform. - `profileUrl` string, nullable, required - `updatedAt` string, date-time, required: When Inboxapp last stored a change to this profile. - `platformData` union, required: Fields only one platform has, tagged by `_tag`. Ignore tags you don't know. - object - `_tag` 'twitter', required - `badge` 'blue' | 'gold' | 'gray', nullable, required - `profileType` 'personal' | 'business' | 'government', required - `professionalCategory` string, nullable, required - `urlEntities` object[], required - `url` string, required - `expandedUrl` string, required - `displayUrl` string, required - `indices` unknown[], required - … - `bannerUrl` string, nullable, required - `rawData` object, nullable, required - object - `_tag` 'linkedin', required - `profileUrn` string, nullable - `kind` 'member' | 'organization', nullable - `memberBadge` 'premium' | 'verified', nullable - `bannerUrl` string, nullable - `bannerSize` object, nullable - `width` number, required - `height` number, required - `hydratedAt` string, nullable - `imageAssetId` string, nullable - `connectionsCount` number, nullable - `currentRole` string, nullable - `currentRoleStart` object, nullable - `year` number, required - `month` number, nullable, required - `currentCompanyName` string, nullable - `currentCompanyUrn` string, nullable - `topSchoolName` string, nullable - `topSchoolUrn` string, nullable - `topSchoolDegree` string, nullable - `topSchoolPeriod` string, nullable - `employeeCount` number, nullable - `employeeCountRange` object, nullable - `start` number, required - `end` number, nullable, required - `industry` string, nullable - `pageKind` 'company' | 'school' | 'showcase', nullable - `currentCompanyLogoUrl` string, nullable - `topSchoolLogoUrl` string, nullable - object: A platform the team has enabled beyond those every team can use. Its fields are not listed here. - `_tag` string, required - `relationships` Relationship[], required: One entry per team account link that has interacted with the profile. - `accountLinkId` string, required - `degree` 'self' | 'first' | 'second' | 'third' | 'outOfNetwork', nullable, required: How close the profile is to the account link on the platform's network, as last observed. `null` when never observed. - `connectionRequest` object, nullable, required: The account link's pending connection request. `null` once the profile is seen accepting it or the request is withdrawn, or when none was sent. - `sentAt` string, date-time, required - `statusId` string, nullable, required: A status: a pipeline stage on the team's board. - `tagIds` string[], required - `notes` string, nullable, required - `valuation` union, required: What the person is worth to the team, in the team's `currency`. - number - 'Infinity' | '-Infinity' | 'NaN' - `assigneeId` string, nullable, required: A member: a person on the team. - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `status` Status: A pipeline stage on the team's board. A contact has at most one status. - `id` string, required - `name` string, required: Unique within the team, ignoring case and accents. - `color` string, nullable, required: A lowercase hex color. - `createdAt` string, date-time, required - `tags` Tag[] - `id` string, required - `name` string, required: Unique within the team, ignoring case and accents. - `color` string, required: A lowercase hex color. - `assignee` Member: A person on the team, who can be assigned threads and contacts. - `id` string, required: The member ID that `assigneeId` fields take. - `name` string, nullable, required - `email` string, required - `imageUrl` string, nullable, required - `role` 'owner' | 'admin' | 'user', required: `owner` and `admin` manage the team. A `user` can't change settings, billing or members. - `createdAt` string, date-time, required - `nextCursor` string, nullable, required: Pass it back as `cursor`, with the same filters, to read the next page. Null on the last page. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `429`: Too Many Requests - `500`: Internal Server Error --- [API](https://skmtc.dev/inboxapp/apis/inboxapp-api.md) · [All operations](https://skmtc.dev/inboxapp/apis/inboxapp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inboxapp/apis/inboxapp-api/revisions/7f9bbf45e851?raw)