API Reference

Profiles

Search verified public profiles, inspect profile detail, and discover who can be contacted through Markidy.

GET /v1/profiles/search

Search verified public profiles. Search matches profile name, bio plain text, indexed career company/title fields, and public recruiting role, skill, and location fields. The default sort is relevance.

Query Parameters

Parameter	Type	Description
`q`	string	Free text search over name, bio, career, and public recruiting terms
`sort`	string	`relevance` (default), `trust`, `recent`, `posts`
`country`	string	Country codes, comma-separated. Example: `us,gb`
`hasCareer`	boolean	Use `true` or `1` to return only profiles with career history
`openTo`	string	`actively_looking`, `open_to_offers`, `not_looking`, `hiring_only`
`roles`	string	Desired role tags, comma-separated. Values inside this parameter are OR matches
`skills`	string	Skill tags, comma-separated. Values inside this parameter are OR matches
`seniority`	string	`intern`, `junior`, `mid`, `senior`, `lead`, `executive`
`workMode`	string	`remote`, `hybrid`, `onsite`, `flexible`
`availability`	string	`immediately`, `one_month`, `three_months`, `not_specified`
`minExperienceMonths`	integer	Minimum total career experience in months
`maxExperienceMonths`	integer	Maximum total career experience in months
`location`	string	Text match against public preferred work location name or address
`page`	integer	Page number. Default: `1`
`pageSize`	integer	Page size. Default: `18`, max: `50`

Request

curl "https://api.markidy.com/v1/profiles/search?roles=Product%20Manager&skills=nodejs&sort=relevance" \
  -H "Authorization: Bearer mk_your_api_key"

Search Behavior

Comma-separated values inside one filter are OR matches. Different filters are AND matches. Recruiting filters only apply to profiles where public recruiting info is visible.

roles and skills use the recruiting tag index. Formatting variants such as Node.js, nodejs, and node can match, but semantic aliases such as PM and Product Manager are not automatically expanded.

Response

{
  "profiles": [
    {
      "userId": "usr_123",
      "name": "Bennett Cross",
      "avatar": null,
      "country": "us",
      "verifiedLevel": 1,
      "memberSince": "2026-04-01T00:00:00.000Z",
      "bioSnippet": "Founder building AI workflows for operators.",
      "topCareer": {
        "title": "Founder",
        "company": "Team daco",
        "startDate": "2025-02",
        "endDate": null,
        "isCurrent": true
      },
      "visibleListingCount": 3,
      "desiredRoles": ["Product Manager"],
      "recruitingSummary": {
        "openTo": "actively_looking",
        "desiredRoles": ["Product Manager"],
        "skills": ["Node.js"],
        "seniority": "senior",
        "workMode": "remote",
        "availability": "immediately",
        "preferredLocations": [
          { "name": "London", "address": "London, UK" }
        ],
        "careerTotalMonths": 84,
        "contactPolicy": "verified_only"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 18,
  "hasMore": false
}

Response Fields

Field	Type	Description
`profiles[].userId`	string	Profile owner user ID
`profiles[].name`	string	Public display name
`profiles[].avatar`	string \| null	Avatar URL when configured
`profiles[].country`	string	Profile country code
`profiles[].verifiedLevel`	integer	Verification level for trust ranking
`profiles[].memberSince`	string	ISO 8601 user creation timestamp
`profiles[].bioSnippet`	string	Plain-text bio excerpt
`profiles[].topCareer`	object \| null	Most relevant current or recent career item
`profiles[].visibleListingCount`	integer	Number of active or paused public listings
`profiles[].desiredRoles`	string[]	Public desired role tags used by profile cards
`profiles[].recruitingSummary`	object \| null	Public recruiting summary when visible, otherwise `null`
`total`	integer	Total matching profiles
`page`	integer	Current page number
`pageSize`	integer	Returned page size
`hasMore`	boolean	Whether another page is available

Recruiting Summary Fields

Field	Type	Description
`openTo`	string \| null	Current recruiting status
`desiredRoles`	string[]	Role tags shown exactly as the profile owner entered them
`skills`	string[]	Skill tags shown exactly as the profile owner entered them
`seniority`	string \| null	Preferred seniority level
`workMode`	string \| null	Preferred work mode
`availability`	string \| null	Availability to start or consider a role
`preferredLocations`	object[]	Public preferred work locations with `name` and `address`
`careerTotalMonths`	integer \| null	Total calculated career experience in months
`contactPolicy`	string \| null	`all_recruiters` or `verified_only`

GET /v1/profiles/{userId}

Get public profile detail including socials, careers, active contact channels, public recruiting preferences, trust links, and your existing request state for that profile.

Request

curl https://api.markidy.com/v1/profiles/usr_123 \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "profile": {
    "userId": "usr_123",
    "name": "Bennett Cross",
    "avatar": null,
    "bio": "Founder building AI workflows for operators.",
    "country": "us",
    "careerTotalMonths": 84,
    "verifiedLevel": 1,
    "memberSince": "2026-04-01T00:00:00.000Z",
    "socials": {
      "github": "https://github.com/example",
      "linkedin": "https://linkedin.com/in/example"
    },
    "activeChannels": ["markidy"],
    "recruitingPreferences": {
      "openTo": "actively_looking",
      "targetRoles": ["Product Manager"],
      "skills": ["Node.js"],
      "seniority": "senior",
      "workMode": "remote",
      "preferredLocations": [
        {
          "name": "London",
          "address": "London, UK",
          "lat": 51.5072,
          "lng": -0.1276,
          "placeId": "..."
        }
      ],
      "timezone": "Europe/London",
      "availability": "immediately",
      "compensation": "$120k+",
      "contactPolicy": "verified_only",
      "careerTotalMonths": 84
    },
    "trustLinks": [
      {
        "title": "Resume",
        "url": "https://example.com/resume"
      },
      {
        "title": "Research paper",
        "url": "https://example.com/research/agent-workflows"
      },
      {
        "title": "Portfolio case study",
        "url": "https://example.com/portfolio/agent-workflows"
      }
    ],
    "profileRequestPolicy": {
      "contactPolicy": "verified_only",
      "requiredVerifiedLevel": 1,
      "canRequest": true,
      "reason": null
    },
    "myProfileRequest": null,
    "careers": [
      {
        "company": "Team daco",
        "title": "Founder",
        "startDate": "2025-02",
        "endDate": null,
        "isCurrent": true,
        "description": "Building Markidy."
      }
    ]
  }
}

Response Fields

Field	Type	Description
`profile.userId`	string	Profile owner user ID
`profile.name`	string	Public display name
`profile.avatar`	string \| null	Avatar URL when configured
`profile.bio`	string	Plain-text public bio
`profile.country`	string	Profile country code
`profile.careerTotalMonths`	integer \| null	Total calculated career experience in months
`profile.verifiedLevel`	integer	Verification level
`profile.memberSince`	string	ISO 8601 user creation timestamp
`profile.socials`	object	Public social account URLs when configured
`profile.activeChannels`	string[]	Profile request channels that can currently receive requests
`profile.recruitingPreferences`	object \| null	Public recruiting preferences when visible, otherwise `null`
`profile.trustLinks`	object[]	Public recruiting evidence links with `title` and `url`. Empty when recruiting info is hidden.
`profile.profileRequestPolicy`	object	Whether the current viewer can send a profile request
`profile.myProfileRequest`	object \| null	Your existing profile request to this user, if any
`profile.careers`	object[]	Public career history

Recruiting Preference Fields

Field	Type	Description
`openTo`	string \| null	Current recruiting status
`targetRoles`	string[]	Desired role tags
`skills`	string[]	Recruiting skill tags
`seniority`	string \| null	Preferred seniority level
`workMode`	string \| null	Preferred work mode
`preferredLocations`	object[]	Google Places-style location objects with `name`, `address`, `lat`, `lng`, and `placeId`
`timezone`	string \| null	IANA timezone when provided
`availability`	string \| null	Availability to start or consider a role
`compensation`	string \| null	Free-text compensation expectation
`contactPolicy`	string \| null	`all_recruiters` or `verified_only`
`careerTotalMonths`	integer \| null	Total calculated career experience in months

Profile Request Policy

Field	Type	Description
`contactPolicy`	string \| null	Recruiting contact rule configured by the profile owner
`requiredVerifiedLevel`	integer \| null	Required viewer verification level, or `null` when no extra level is required
`canRequest`	boolean	Whether the current API key user can send a profile request
`reason`	string \| null	Human-readable reason when the viewer cannot send a request

recruitingPreferences is null when the profile owner disabled public recruiting info. trustLinks is empty in the same case. profileRequestPolicy is still returned so clients can explain whether the viewer can send a request. Use Match Requests for profile request creation, status updates, and conversation flow.

Previous ← Account Next Categories →