API Reference

Match Requests

Send, manage, and respond to match requests between seekers and listing owners.

POST /v1/match-requests

Send a match request to a listing owner.

Request Body

Field	Type	Required	Description
`listingId`	string	✅	Target listing ID
`channels`	string[]	✅	Contact channels (must be `available: true` in listing detail)
`message`	string	✅	Request message (max 500 chars)

Request

curl -X POST https://api.markidy.com/v1/match-requests \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "listingId": "clx...",
    "channels": ["telegram", "discord"],
    "message": "Hi, I am interested in your service."
  }'

Response (201)

{
  "id": "mr_...",
  "status": "PENDING",
  "createdAt": "2026-03-18T12:00:00Z"
}

Rate-limited to 10 per hour. You cannot request your own listing or send duplicate requests.

GET /v1/match-requests/mine

List match requests you have sent.

Query Parameters

Parameter	Type	Description
`listingId`	string	Filter by specific listing
`status`	string	`PENDING`, `ACCEPTED`, `REJECTED`
`page`	integer	Page number (default: 1)
`pageSize`	integer	Page size (default: 16)

Response

{
  "requests": [
    {
      "id": "mr_...",
      "status": "ACCEPTED",
      "listingId": "clx...",
      "listingTitle": "AI Agent Developer...",
      "channels": ["telegram"],
      "message": "I'm interested...",
      "createdAt": "2026-03-18T12:00:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "pageSize": 16
}

Response Fields

Field	Type	Description
`id`	string	Request ID
`status`	string	`PENDING`, `ACCEPTED`, `REJECTED`
`listingId`	string	Target listing ID
`listingTitle`	string	Listing title (derived from meta)
`channels`	string[]	Channels used for this request
`message`	string	Request message
`createdAt`	string	ISO 8601 timestamp

GET /v1/match-requests/listing/{listingId}

List requests received for your listing. Includes requester profile information.

Query Parameters

Parameter	Type	Description
`status`	string	`PENDING`, `ACCEPTED`, `REJECTED`
`page`	integer	Page number (default: 1)
`pageSize`	integer	Page size (default: 16)

Response

{
  "requests": [
    {
      "id": "mr_...",
      "status": "PENDING",
      "profile": {
        "displayName": "Alice",
        "description": "Looking for AI solutions",
        "verifiedLevel": 1,
        "country": "us",
        "socialLinks": {
          "github": "https://github.com/alice",
          "x": "https://x.com/alice"
        }
      },
      "channels": ["telegram"],
      "message": "I'm interested...",
      "createdAt": "2026-03-18T12:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "pageSize": 16
}

Response Fields

Field	Type	Description
`id`	string	Request ID
`status`	string	`PENDING`, `ACCEPTED`, `REJECTED`
`profile.displayName`	string	Requester's display name
`profile.description`	string	Self-introduction
`profile.verifiedLevel`	integer	Verification level (0–2)
`profile.country`	string	Country code
`profile.socialLinks`	object	Social media links (key-value pairs)
`channels`	string[]	Channels requested
`message`	string	Request message
`createdAt`	string	ISO 8601 timestamp

PATCH /v1/match-requests/{requestId}/status

Accept or reject a pending match request. Only the listing owner can perform this action.

Path Parameters

Parameter	Type	Description
`requestId`	string	Match request ID (e.g., `mr_...`), returned from `POST /v1/match-requests` or webhook `match_request.received`

Request Body

Field	Type	Required	Description
`status`	string	✅	`ACCEPTED` or `REJECTED`
`reason`	string		Rejection reason (only for `REJECTED`)

curl -X PATCH https://api.markidy.com/v1/match-requests/mr_def456/status \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "ACCEPTED" }'

Reject

curl -X PATCH https://api.markidy.com/v1/match-requests/mr_def456/status \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "REJECTED", "reason": "Not a good fit" }'

Response

{
  "id": "mr_...",
  "status": "ACCEPTED",
  "updatedAt": "2026-03-18T13:00:00Z"
}

Previous ← Listings Next Conversations →