--- title: "Search people" method: GET path: "/people" tags: ["People"] --- # Search people `GET /people` ## Request - Base URL: `https://inboxapp.com/api/v2` - URL: `https://inboxapp.com/api/v2/people` - Auth: HTTP bearer Searches people on each platform as one of the team's account links, like the platform's own search box. Needs the Advanced API add-on, and `directory:typeahead` on each account link. Each account link can search 20 times per minute, 300 per hour and 1500 per day, so the platform doesn't flag its session; past a limit, it is listed in `failures` with `peopleSearchRateLimited`. Use the result's `target` to reach that person on endpoints like `Send message` or `Send connection request`. ## Query parameters - `platform` Platform[]: Searches these platforms. Defaults to every available platform. With `accountLinkId`, keeps only the account links on these platforms. Repeat the key to match any of several. - `accountLinkId` Cuid2[]: Searches from these account links. Each platform is searched once, from the oldest account link given on it; IDs that match no account link are ignored. Without it, each platform is searched from its oldest active account link that can search. Repeat the key to match any of several. - `q` string, required: A name or username, as typed into the platform's own people search. - `reach` 'contacts' | 'network': `contacts`, the default, searches people each account already messages. `network` also searches beyond them, where the platform separates the two. - `enrich` boolean: `true` fetches and stores every result Inboxapp hasn't stored yet, so each comes back as a full profile. A result that can't be fetched or stored is left out. Slower. Defaults to `false`. ## Response `200` OK - PersonList: Every searched account link's results in one list: closest name or username match first, then people the account already talks to or is connected with, then verified, then each platform's own order. Not paginated. - `data` Person[], required - `accountLinkId` string, required: The account link that found this person. `threadId`, `canMessage`, `degree`, `closeness` and `target` are its view. - `profile` union, required - Profile: One person's account on one platform. Profile data is shared across teams; the team's own data about the person is on their contact. - `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 - … - `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 - … - `hydratedAt` string, nullable - `imageAssetId` string, nullable - `connectionsCount` number, nullable - `currentRole` string, nullable - `currentRoleStart` object, nullable - … - `currentCompanyName` string, nullable - `currentCompanyUrn` string, nullable - `topSchoolName` string, nullable - `topSchoolUrn` string, nullable - `topSchoolDegree` string, nullable - `topSchoolPeriod` string, nullable - `employeeCount` number, nullable - `employeeCountRange` object, nullable - … - `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 - ProfileHit: A profile the platform's search returned that Inboxapp hasn't stored, with only what identifies it. - `id` unknown, 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, nullable, 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 - `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. - `profileUrl` string, nullable, required - `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 - … - `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 - … - `hydratedAt` string, nullable - `imageAssetId` string, nullable - `connectionsCount` number, nullable - `currentRole` string, nullable - `currentRoleStart` object, nullable - … - `currentCompanyName` string, nullable - `currentCompanyUrn` string, nullable - `topSchoolName` string, nullable - `topSchoolUrn` string, nullable - `topSchoolDegree` string, nullable - `topSchoolPeriod` string, nullable - `employeeCount` number, nullable - `employeeCountRange` object, nullable - … - `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 - `contactId` string, nullable, required: The team's contact holding this profile, if any. - `threadId` string, nullable, required: The account link's latest thread with this profile, if any. - `canMessage` boolean, nullable, required: The platform's hint that the account link can message this person, `null` when the platform doesn't say. A send can still fail with `recipientUnavailable`. - `degree` 'self' | 'first' | 'second' | 'third' | 'outOfNetwork', nullable, required: How close the person is to the account link on the platform's network, as the search states it. `null` when it states none. - `closeness` 'connected' | 'near' | 'none', required: `connected` for a direct tie such as a follow or 1st-degree connection, `near` for a shared one such as mutuals or 2nd degree. - `target` union, required: Pass as is as the `target` of Send message or Send connection request to reach this person from the account link. - object - `type` 'profile', required - `accountLinkId` string, required - `platform` string, required: The platform. Every team can use twitter, linkedin; a team may have others enabled. - `platformId` string, required: The person's ID on the platform. Reaching someone Inboxapp hasn't stored needs the account link's `profile:resolve:id`. - object - `type` 'profile', required - `accountLinkId` string, required - `platform` string, required: The platform. Every team can use twitter, linkedin; a team may have others enabled. - `username` string, required: The person's username on the platform, without a display prefix such as `@`. On LinkedIn, what follows `/in/` in their profile URL: the vanity name or the `ACoA…` profile ID. Reaching someone Inboxapp hasn't stored needs the account link's `profile:resolve:username`. - `failures` PeopleSearchFailure[], required: The searched account links that returned nothing. When every one fails, the request fails with the first one's error instead. - `accountLinkId` string, required - `code` 'accountLinkNotFound' | 'accountLinkDisconnected' | 'integrationSetupRequired' | 'capabilityNotSupported' | 'platformRateLimited' | 'peopleSearchRateLimited' | 'platformError' | 'platformUnavailable', required: The error code searching from this account link alone returns. - `message` string, required ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `422`: Unprocessable Entity - `429`: Too Many Requests - `500`: Internal Server Error - `502`: Bad Gateway - `503`: Service Unavailable --- [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)