Integration Methods

REST API

Integrate with Markidy programmatically using our RESTful API. Search listings and profiles, send listing or profile requests, and manage conversations.

🧪 Try the API interactively in the API Playground →

Base URL

https://api.markidy.com/v1

All API requests must use HTTPS and include your API key in the Authorization header.

Request Format 
curl https://api.markidy.com/v1/listings/search?category=jobs \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json"

Response Format

All successful responses return JSON. List endpoints include pagination:

Paginated Response 
{
  "listings": [ ... ],
  "total": 45,
  "page": 1,
  "pageSize": 16
}

Error responses include a code and human-readable error:

Error Response 
{
  "code": "VALIDATION_ERROR",
  "error": "Validation failed",
  "details": [
    { "field": "channels", "issue": "telegram is not connected" }
  ]
}

Use the GET /v1/geocode endpoint to convert addresses into coordinates, then pass them as meta filters to search by proximity.

Geocode + Search 
# Step 1: Convert address to coordinates
curl "https://api.markidy.com/v1/geocode?q=San+Francisco" \
  -H "Authorization: Bearer mk_your_api_key"

# Step 2: Search with GEO filter (results sorted by distance)
curl "https://api.markidy.com/v1/listings/search?category=jobs&role=employer&meta.work-location_lat=37.77&meta.work-location_lng=-122.42" \
  -H "Authorization: Bearer mk_your_api_key"

When a GEO filter is active, results are sorted by distance (nearest first). Each listing includes a distanceKm field (null when no GEO filter is used).

Conversation Status

When a user deletes (leaves) a conversation, the other party sees otherLeft: true. Sending messages to a left conversation returns 403.

Delete (Leave) Conversation 
curl -X DELETE "https://api.markidy.com/v1/conversations/{id}" \
  -H "Authorization: Bearer mk_your_api_key"

# Response: { "success": true }
# Other party will see: "otherLeft": true

What Can You Build?

Apps & Workflows

Let apps, assistants, and workflows browse listings, send match requests, and manage matching automatically.

Webhook Automation

Receive real-time notifications for new match requests and automate your response pipeline.

Custom Tooling

Build CLI tools, bots, or dashboards that interact with Markidy.

Usage Flows

Listing Seeker Flow

1GET /v1/listings/search?q=...Search for listings
->GET /v1/categoriesBrowse categories for filters
->GET /v1/categories/{key}Get fields for meta.* filtering
->GET /v1/geocode?q=...Convert address to lat/lng for GEO fields
2GET /v1/listings/{id}Check detail + profile.userId + channels + existing request
->GET /v1/profiles/{userId}Use listing.profile.userId to inspect the owner profile
3POST /v1/match-requestsSend request (if myRequest is null)
4GET /v1/match-requests/minePoll for status updates
5GET /v1/conversationsFind conversation (after accepted)
6POST /v1/conversations/{id}/messagesSend a message

Profile Sourcing Flow

1GET /v1/profiles/searchSearch candidates with sourcing filters
2GET /v1/profiles/{userId}Inspect detail, recruiting info, and request policy
->profileRequestPolicyCheck canRequest, required verification, and reason
->activeChannelsChoose an available channel
->myProfileRequestAvoid duplicate requests
3POST /v1/profile-requestsSend a profile request
4GET /v1/match-requests/mine?subjectType=PROFILEPoll status updates
5GET /v1/conversations?subjectType=PROFILEContinue after acceptance

Creator Flow

1GET /v1/categoriesFind target category
2GET /v1/categories/{key}Check role fields, required flags, and value encoding
3GET /v1/me/channelsVerify connected channels
4GET /v1/webhooksGet webhook IDs (optional)
5POST /v1/listingsCreate listing with status PENDING
...Wait for admin approval and ACTIVE status

Management Flow

1GET /v1/listings/mineCheck my listing statuses
2GET /v1/match-requests/listing/{id}View incoming requests
3PATCH /v1/match-requests/{id}/statusAccept or reject
4GET /v1/conversationsFind conversation (after accepting)
5POST /v1/conversations/{id}/messagesReply to requester
6PATCH /v1/listings/{id}/statusPause / Resume listing
7PATCH /v1/listings/{id}Update meta and return to PENDING for re-review
8DELETE /v1/conversations/{id}Leave conversation (otherLeft for other party)
9DELETE /v1/listings/{id}Delete listing
Previous ← Talent scout Next MCP Server →