Search

Endpoints to fetch Talent Profiles (formerly known as "Talent Passports")

get

Search For Profiles

This endpoint /search/advanced/profiles allows you to fetch Profiles that match specific criteria.

The Search Criteria:

1. tags (all tags should exist in the matching Profiles)

2. score range for a Scorer

3. credentials

4. identity (free text search on any of the Profile properties that constitute an identity)

5. profile ids

6. wallet addresses

7. human checkmark

8. main role

9. open to

Exact Match

Some of the search use cases above, support exact match search. You will find relevant information in each individual search case below.

The endpoint

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'

Example response

{
  "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

Search Cases

Search by profile ids:

{
  "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.

Exact Match

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.

Search by wallet addresses:

{
  "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.

Exact Match

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.

Search by tags:

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
}

Search by main role:

This will bring the Profiles with any of the main roles in the query.

{
  "query": {
    "mainRole":["community", "engineering", "design"]
  },
  "sort": {
    "id": {
      "order": "desc"
    }
  },
  "page": 1,
  "per_page": 25
}

Main role can be one of:

• community

• creator

• data_research

• design

• engineering

• founder_ceo

• growth_sales

• investor

• operations

• other

• product

• unknown

Note: Each profile can have only one main role.

Search by open to:

This will bring the Profiles with any of the main roles in the query.

{
  "query": {
    "openTo":["co_founders_collaborators", "full_time_roles"]
  },
  "sort": {
    "id": {
      "order": "desc"
    }
  },
  "page": 1,
  "per_page": 25
}

OpenTo can be one of:

• full_time_roles

• freelance_contract_work

• co_founders_collaborators

• investment_funding

• not_open_to

Note: Each profile can have only one main role.

Search by identity

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:

Top Level Fields

• Display Name

• Email

• ENS

• Main Wallet

• Name

• Talent Protocol ID

• User Display Name (if Profile is associated to a User)

• Username (if Profile is associated to a User)

• User UUID (if Profile is associated to a User)

• UUID

Nested Fields

• Identifier of any Account associated with the Profile

• Username of any Account associated with the Profile

• Name of any Social Account associated with the Profile

• Display Name of any Social Account associated with the Profile

• External ID of any Social Account associated with the Profile

• Identifiers for any onchain entity, like Basename, or ENS name or CyberID e.t.c.

Exact Match

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.

Search by Identity - Scope Limited 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:

• basename

• cyberid

• displayName

• email

• ens

• farcaster

• github

• lens

• linkedin

• mainWallet

• name

• profileId

• social

• talentProtocol

• twitter

• userDisplayName

• username

• userUuid

• uuid

• wallet

• x

Example 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.

Search by Credentials

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 performed

• valueRange

  • min Optional. If not given, it is assumed 1

  • max. Optional. If not given, it is assumed 2^256 - 1, i.e. 115792089237316195423570985008687907853269984665640564039457584007913129639935

• readableValue 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
}

List of Credentials by Data Issuer

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	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

Search by Human Checkmark

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 valuefalse.

If you don't specify the humanCheckmark, the query returns both with true and false.

Using fetch on Browser

The 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

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_page

This 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 option

The 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.

Point In Time option

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:

• You don't pass the page parameter.

• You pass the 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.

• You don't pass a point_in_time_id. You pass it only from the second page and beyond.

• You don't pass a 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_id

• search_after

On 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 [e-mail].

Sorting

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"
    }
  }
}

Caching

This endpoint returns cached data for free customers. Paying customers get up-to-date data.

Authorizations

Query parameters

Header parameters

X-API-KEYstringOptional

Your Talent Protocol API Key

AuthorizationstringOptional

Optional: The JWT to identify a calling User

Responses

200

get profiles matching input query and sorted by sort specification

application/json

400

bad request

application/json

401

unauthorized request with wrong api key

application/json

get

HTTPcURLJavaScriptPython

GET /search/advanced/profiles HTTP/1.1
Host: api.talentprotocol.com
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "profiles": [
    {
      "id": "text",
      "bio": null,
      "created_at": "2025-05-09T06:53:21.870Z",
      "display_name": null,
      "human_checkmark": true,
      "image_url": null,
      "location": null,
      "name": null,
      "calculating_score": true,
      "tags": [
        "text"
      ],
      "verified_nationality": true,
      "builder_score": {
        "points": 1,
        "last_calculated_at": "2025-05-09T06:53:21.870Z"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 1,
    "total": 1,
    "total_for_page": 1,
    "point_in_time_id": null,
    "search_after": [
      1
    ]
  }
}

Get a profile using wallet, talent id or account identifier

get

Query parameters

idstringOptional

Talent ID, wallet address or account identifier

account_sourcestringOptional

The source of the account:

• farcaster
• github
• wallet

Header parameters

X-API-KEYstringOptional

Your Talent Protocol API key

Responses

200

Get profile using github handle

application/json

get

HTTPcURLJavaScriptPython

GET /profile HTTP/1.1
Host: api.talentprotocol.com
Accept: */*

200

Get profile using github handle

{
  "profile": {
    "id": "text",
    "bio": "text",
    "display_name": "text",
    "image_url": "text",
    "location": "text",
    "name": "text",
    "human_checkmark": true,
    "onchain_since": "2025-05-09T06:53:21.870Z",
    "ens": "text",
    "tags": [
      "text"
    ]
  }
}