Talent Profiles
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.
Example:
$ curl -G -X GET 'https://api.talentprotocol.com/search/advanced/profiles' \
-H 'Accept: application/json' \
-H 'X-API-KEY: c2a9...5ec8' \
--data-urlencode 'query={"score_credentials": {"scorer": "Builder Score Scorer", "credentials": [{"name": "First Transaction", "dataIssuer": "Arbitrum", "category": "activity", pointsRange: {"min": 10, "max": 1000}}]}}' \
--data-urlencode 'sort={"score": { "order": "desc", "scorer": "Builder Score Scorer" }, "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.
{
"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.
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:
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:
basenamecyberiddisplayNameemailensfarcastergithublenslinkedinmainWalletnameonchainIdprofileIdsocialtwitteruserDisplayNameusernameuserUuiduuidwalletxExample 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 score credentials AND points range. It brings all the profiles
that have all the matching credentials. Note that if a points range
is given, and min is missing, it is considered 1. max in the point range is optional.
Note that you have to specify the scorer too, because Score Credentials and points are Scorer
specific.
A credential can be specified by:
name and/ordataIssuer and/orcategory and/orpointsRangeA credential will match if it satisfies ALL the conditions.
Example:
{
"query": {
"scoreCredentials": {
"scorer": "Builder Score Scorer",
"credentials: [
{
"name": "Basecamp Attendee", "pointsRange": { "min": 10, "max": 30}
},
{
"name": "Base Learn", "pointsRange": {"min": 10, "max": 32}
}
]
}
},
"sort": {
"score": {
"order": "desc"
}
},
"page": 1,
"per_page": 25
}
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 1000 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 2. 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 2 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 Scorer"
},
"id": {
"order": "desc"
}
}
}
This endpoint returns cached data for free customers. Paying customers get up-to-date data.
Your Talent Protocol API Key
Talent ID, wallet address or account identifier
The source of the account:
farcastergithubwalletYour Talent Protocol API key