Search
Endpoints to fetch Talent Profiles (formerly known as "Talent Passports")
Last updated
Was this helpful?
Endpoints to fetch Talent Profiles (formerly known as "Talent Passports")
Last updated
Was this helpful?
This endpoint /search/advanced/profiles allows you to fetch Profiles that
match specific criteria.
Some of the search use cases above, support exact match search. You will find relevant information in each individual search case below.
Example:
$ curl -G -X GET 'https://api.talentprotocol.com/search/advanced/profiles' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ey...WA' \
-H 'X-API-KEY: c2a...ec8' \
--data-urlencode 'query={"score": {"max": 12345, "min": 100}, "humanCheckmark": true, "credentials": [{"name": "Primary Basename", "pointsRange": {"min": 1}}]}' \
--data-urlencode 'sort={"score": { "order": "desc"}, "id": { "order": "desc" } }' \
--data-urlencode 'page=1' \
--data-urlencode 'per_page=3'
{
"profiles": [
{
"calculating_score": false,
"created_at": ...
},
...
],
"pagination": {
"current_page": 1,
"last_page": 400,
"total": 10000,
"total_for_page": 25,
"point_in_time_id": null,
"search_after": null
}
}
Above, you can see how we sort and how we paginate.
Note: The query parameters need to be URL encoded.
Important: The pagination technique using page parameter is adequate for UI-kind clients that do not need to browse
all the pages with absolute accuracy. There is also the point_in_time_id technique which is
more adequate if one wants to go from one page to the next with consistent results from page to page. See the section Pagination
{
"query": {
"profileIds":["ab0bbf06...profile uuid...3a83c8e14", "34ec610...profile uuid...38482bfb1"]
},
"sort": {
"id": {
"order": "asc"
}
},
"page": 1,
"per_page": 25
}
The profile uuids given can be partial. All the Profiles whose uuid includes the given terms will be returned.
Note that in sorting, when we refer to id we refer to an internal id that our database uses
to identify Profiles. However, the profileIds refers to the public identifiers of profiles which are
uuids.
Searching by profile ids supports exact match searching. This means that you can pass: "exactMatch": true as
part of the "query" property object. In that case, only the profiles that have uuid equal to any of the given
terms will be return. Exact match is case insensitive.
{
"query": {
"walletAddresses":["0x324e9e13d...wallet address...7e94462", "0xec4a...wallet address...eae7ca"]
},
"sort": {
"id": {
"order": "asc"
}
},
"page": 1,
"per_page": 25
}
The wallet addresses given can be partial. Any Profile with wallet address that include the terms given will be returned.
Searching by wallet addresses supports exact match searching. This means that you can pass: "exactMatch": true as
part of the "query" property object. In that case, only the profiles that have a wallet address equal to any of the given
terms will be return. Exact match is case insensitive.
This will bring the Profiles with all the tags in the query.
{
"query": {
"tags":["tag 1", "tag 2", "tag 3"]
},
"sort": {
"id": {
"order": "desc"
}
},
"page": 1,
"per_page": 25
}
We want to be able to search by identity.
{
"query": {
"identity":"an identity"
},
"sort": {
"id": {
"order": "desc"
}
},
"page": 1,
"per_page": 25
}
This will return any Profile that has an identity containing the given term.
With identity we generalize the following properties of the Profile:
Searching by identity supports exact match searching. This means that you can pass: "exactMatch": true as
part of the "query" property object. In that case, only the profiles that have an identity equal to the given term will be return. Exact match is case insensitive.
This is also true for the scope limited identity search.
One might want to limit the scope of identity search to a specific data source. In that case, the data source should be used as a prefix to the search term.
For example:
ens:panos
The supported scope prefixes are:
basenamecyberiddisplayNameemailensfarcastergithublenslinkedinmainWalletnameprofileIdsocialtalentProtocoltwitteruserDisplayNameusernameuserUuiduuidwalletxExample query:
{
"query": {
"identity": "ens: panagiotismatsinopoulos.eth"
}
}
Note that any Profile that includes the term given on their ENS identifier (for this example), will be returned. We are not doing exact match.
This is an example to search for credentials AND value range. It brings all the profiles
that have all the matching credentials. Note that if a value range
is given, and min is missing, it is considered 1. max in the value range is optional.
A credential can be specified by:
dataIssuer This is mandatory. Exact match is performed. The list of dataIssuers is given below.name. This is mandatory. Exact match is performed. Note that names are unique within the dataIssuer scope. The list of names per data issuer is given below.category Optional. If present Exact match is performedvalueRange
min Optional. If not given, it is assumed 1max. Optional. If not given, it is assumed 2^256 - 1, i.e. 115792089237316195423570985008687907853269984665640564039457584007913129639935readableValue Optional. If present search does contains comparison to match all the given
data points that include the given value in their readableValue value.A credential will match if it satisfies ALL the conditions. And if there are many credentials in the query, then ALL of them should match.
Example:
{
"query": {
"credentials: [
{
"dataIssuer": "Base", "name": "Basecamp Attendee", "valueRange": { "min": 10, "max": 30}
},
{
"dataIssuer": "Arbitrum", "name": "Outgoing Transactions", "valueRange": {"min": 10, "max": 32}
}
]
},
"sort": {
"score": {
"order": "desc"
}
},
"page": 1,
"per_page": 25
}
| Data Issuer | Credential Name |
|---|---|
| Arbitrum | ETH Balance |
| Arbitrum | First Transaction |
| Arbitrum | Outgoing Transactions |
| Base | Base Active Smart Contracts |
| Base | Base Around The World Participant |
| Base | Base Around The World Winner |
| Base | /base-builds ETH Earnings |
| Base | Basecamp Attendee |
| Base | Base Learn |
| Base | Contracts Deployed (Mainnet) |
| Base | Contracts Deployed (Testnet) |
| Base | ETH Balance |
| Base | First Transaction |
| Base | Onchain Summer Buildathon Participant |
| Base | Onchain Summer Buildathon Winner |
| Base | Outgoing Transactions |
| Base | Primary Basename |
| Binance | Binance Account Bound Token |
| BNB Chain | BNB Balance |
| BNB Chain | First Transaction |
| BNB Chain | Outgoing Transactions |
| Bonsai | Bonsai Airdrop 1 |
| Bountycaster | Bounties Completed |
| BUILD | $BUILD Contribution |
| Celo | Celo Active Smart Contracts |
| Celo | Contracts Deployed (Mainnet) |
| Celo | Contracts Deployed (Testnet) |
| Coinbase | Country Verification |
| Coinbase | Identity Verification |
| Crypto Nomads | CNC Member |
| DAOBase | DAO Badge Score |
| Degen | Degen Allowance |
| Developer | DAO D_D Member |
| Developer | DAO D_D OG |
| ENS | ENS Account Age |
| ENS | Primary ENS Domain |
| Ethereum | ETH Balance |
| Ethereum | First Transaction |
| Ethereum | Outgoing Transactions |
| ETHGlobal | ETHGlobal Builder |
| ETHGlobal | ETHGlobal Hacker |
| ETHGlobal | ETHGlobal OG |
| ETHGlobal | ETHGlobal Partner |
| ETHGlobal | ETHGlobal Pioneer |
| ETHGlobal | ETHGlobal Supporter |
| Farcaster | Farcaster Account Age |
| Farcaster | Farcaster Account ID |
| Farcaster | Frame Builder Rewards |
| Farcaster | Warpcast Rewards Average Score |
| Farcaster | Warpcast Spam Label |
| Farcaster | Warpcast USDC Rewards |
| FWB | FWB Member |
| Galxe | Galxe Passport |
| GitHub | GitHub Account |
| GitHub | GitHub Account Age |
| GitHub | GitHub Crypto Repositories Commits |
| GitHub | GitHub Crypto Repositories Contributed |
| GitHub | GitHub Followers |
| GitHub | GitHub Forks |
| GitHub | GitHub Repositories |
| GitHub | GitHub Stars |
| GitHub | GitHub Total Contributions |
| Human.tech | Identity Verification |
| Jumper | Jumper Pass Level |
| Lens | Lens Account |
| Lens | Lens Account Age |
| LinkedIn Account | |
| Onchain Activity | Active Smart Contracts |
| Onchain Activity | Contracts Deployed (Mainnet) |
| Onchain Activity | Contracts Deployed (Testnet) |
| Onchain Activity | ETH Balance |
| Onchain Activity | First Transaction |
| Onchain Activity | Outgoing Transactions |
| Optimism | Contracts Deployed (Mainnet) |
| Optimism | Contracts Deployed (Testnet) |
| Optimism | ETH Balance |
| Optimism | First Transaction |
| Optimism | OP Active Smart Contracts |
| Optimism | Outgoing Transactions |
| Safe | Safe Signer |
| Scroll | Contracts Deployed (Mainnet) |
| Scroll | Contracts Deployed (Testnet) |
| Scroll | ETH Balance |
| Scroll | First Transaction |
| Scroll | Outgoing Transactions |
| Scroll | Scroll Active Smart Contracts |
| Self.xyz | Identity Verification |
| Self.xyz | Nationality Verification |
| Serotonin | Platform Member |
| Stack | Stack Score |
| Taikai | Hackathon Participant (after Nov 2024) |
| Taikai | Hackathon Participant (until Nov 2024) |
| Talent Protocol | Builder+ Member |
| Talent Protocol | Human Checkmark |
| Talent Protocol | Talent Account Age |
| Talent Protocol | $TALENT Vault |
| World | Proof of personhood |
| X/Twitter | X Account |
| X/Twitter | X Account Age |
This is an example to search for builders that have a Human Checkmark. It brings all the profiles that have human checkmark true.
{
"query": {
"humanCheckmark": true
},
"sort": {
"score": {
"order": "desc"
}
},
"page": 1,
"per_page": 25
}
'
If you want to get profiles that do not have the human checkmark, you should give the value
false.
If you don't specify the humanCheckmark, the query returns both with true and false.
fetch on BrowserThe search endpoints are GET endpoints that can accept the params either in the body
of the request or URL encoded. The latter case is useful when using fetch() requests from a browser.
Example:
const data = {
query: {
score: {
min: 10,
max: 60
}
},
sort: {
score: {
order: "desc"
}
},
page: 1,
per_page: 25
};
const queryString = Object.keys(data)
.map(key => `${key}=${encodeURIComponent(JSON.stringify(data[key]))}`)
.join("&");
const response = await fetch(
`${ENV_VARS.API_BASE_URL}/search/advanced/profiles?${queryString}`,
{
method: "GET",
headers: {
Accept: "application/json",
"X-API-Key": ENV_VARS.TALENT_PROTOCOL_API_KEY
}
}
);
const jsonResponse = await response.json();
console.debug("jsonResponse", jsonResponse);
Pagination requires sorting. So, we suggest that you always use the sort key in your request
and consistently send the same sort conditions when moving from one page to the next. This
is true regardless of the pagination mode you use (i.e. page-based or point-in-time-based pagination)
per_pageThis is an integer which defines how many results (Profiles) a response can have. If page pagination is used.
This cannot be more than 25 for free customers and no more than 250 for paying customers.
page optionThe default pagination with the page param may not yield consistent results when going from one page to the next. This is because new documents might be indexed or deleted in-between.
For consistent travel from one page to the next, we suggest the Point in Time technique.
Point In Time option is only available to paying customers.
It works as follows:
Each search from page to page is characterized by a point_in_time_id.
Visiting the first page:
page parameter.keep_alive_minutes parameter, which is an integer that can't be more than 60. It represents how much time a result set stays alive in between searches for the same point_in_time_id.point_in_time_id. You pass it only from the second page and beyond.search_after. You pass it only from the second page and beyond.The search for the first page returns some meta-data that you have to use on your search for the next page:
point_in_time_idsearch_afterOn search for the next page, you have to pass these extra parameters with the values that you got from the result of the previous page.
Important: This is designed to be used by clients, such as scripts, that need to browse from page to page the whole search index. The backend consumes a lot of resources in supporting this feature.
Important: The keep_alive_minutes can't be more than 60 minutes. This should be enough
for the client script to process the results of one page before going to fetch the next page.
If this number seems to be small to you, then please contact tech@talentprotocol.com.
The sort parameter allows to sort results by the score and by id. We are suggesting
that you use both, because two Profiles might have the same score.
This is a useful example:
{
"sort": {
"score": {
"order": "desc",
"scorer": "Builder Score"
},
"id": {
"order": "desc"
}
}
}
This endpoint returns cached data for free customers. Paying customers get up-to-date data.
Your Talent Protocol API Key
Optional: The JWT to identify a calling User
Talent ID, wallet address or account identifier
The source of the account:
farcastergithubwalletYour Talent Protocol API key
Get profile using github handle