API Reference

Match Requests

Send, manage, and respond to listing requests and profile requests. Creation is subject-specific, while outgoing lookup, status changes, and conversations are shared.

Shared Request Surfaces

Listings use POST /v1/match-requests. Profiles use POST /v1/profile-requests. After creation, both subjects share GET /v1/match-requests/mine, PATCH /v1/match-requests/{requestId}/status, and conversations.

Shared Request Fields

{
  "id": "mr_...",
  "status": "PENDING",
  "subjectType": "PROFILE",
  "subjectTitle": "Profile request",
  "subjectHref": "/profile/usr_123",
  "listingId": null,
  "listingTitle": null,
  "profileUserId": "usr_123",
  "respondedAt": null,
  "rejectedReason": null
}

POST /v1/match-requests

Send a request to a listing owner.

Request Body

Field	Type	Required	Description
`listingId`	string	Yes	Target listing ID
`channels`	string[]	Yes	Contact channels that are `available: true` in listing detail
`message`	string	Yes	Request message, maximum 500 characters

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": ["markidy"],
    "message": "Hi, I am interested in your service."
  }'

Response (201)

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

Listing requests are rate-limited. You cannot request your own listing, request an unavailable listing, use unavailable channels, or create a duplicate request for the same listing.

POST /v1/profile-requests

Send a request to a public profile. Check profileRequestPolicy, activeChannels, and myProfileRequest from GET /v1/profiles/{userId} before creating the request.

Request Body

Field	Type	Required	Description
`profileUserId`	string	Yes	Target profile owner user ID
`channels`	string[]	Yes	Contact channels listed in the target profile's `activeChannels`
`message`	string	Yes	Request message, maximum 500 characters

Request

curl -X POST "https://api.markidy.com/v1/profile-requests" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "profileUserId": "usr_123",
    "channels": ["markidy"],
    "message": "Interested in discussing a role."
  }'

Response (201)

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

If the target profile uses verified_only, the requester must have verified level 1 or higher. The API also rejects self requests, duplicate requests, unavailable channels, and messages over 500 characters.

GET /v1/match-requests/mine

List requests you have sent across listing and profile subjects.

Query Parameters

Parameter	Type	Description
`subjectType`	string	`LISTING` or `PROFILE`
`listingId`	string	Filter by listing request subject
`profileUserId`	string	Filter by target profile owner user ID
`status`	string	`PENDING`, `ACCEPTED`, or `REJECTED`
`page`	integer	Page number. Default: `1`
`pageSize`	integer	Page size. Default: `16`, max: `50`

Profile Requests

curl "https://api.markidy.com/v1/match-requests/mine?subjectType=PROFILE&status=PENDING" \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "requests": [
    {
      "id": "mr_...",
      "status": "PENDING",
      "subjectType": "PROFILE",
      "subjectTitle": "Profile request",
      "subjectHref": "/profile/usr_123",
      "listingId": null,
      "listingTitle": null,
      "profileUserId": "usr_123",
      "channels": ["markidy"],
      "message": "Interested in discussing a role.",
      "createdAt": "2026-03-18T12:00:00.000Z",
      "respondedAt": null,
      "rejectedReason": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 16
}

Response Fields

Field	Type	Description
`id`	string	Request ID
`status`	string	`PENDING`, `ACCEPTED`, or `REJECTED`
`subjectType`	string	`LISTING` or `PROFILE`
`subjectTitle`	string	Human-readable subject label
`subjectHref`	string \| null	Public subject URL path
`listingId`	string \| null	Listing ID for listing requests
`listingTitle`	string \| null	Listing title for listing requests
`profileUserId`	string \| null	Target profile owner for profile requests
`channels`	string[]	Requested channels
`message`	string	Request message
`createdAt`	string	ISO 8601 creation timestamp
`respondedAt`	string \| null	Accepted or rejected timestamp
`rejectedReason`	string \| null	Owner-provided rejection reason

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

List incoming requests received on a listing you own.

Query Parameters

Parameter	Type	Description
`status`	string	`PENDING`, `ACCEPTED`, or `REJECTED`
`page`	integer	Page number. Default: `1`
`pageSize`	integer	Page size. Default: `16`, max: `50`

Response

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

GET /v1/profile-requests/profile/{profileUserId}

List incoming requests received on your public profile.

Query Parameters

Parameter	Type	Description
`status`	string	`PENDING`, `ACCEPTED`, or `REJECTED`
`page`	integer	Page number. Default: `1`
`pageSize`	integer	Page size. Default: `16`, max: `50`

Request

curl "https://api.markidy.com/v1/profile-requests/profile/usr_123?status=PENDING" \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "requests": [
    {
      "id": "mr_...",
      "status": "PENDING",
      "subjectType": "PROFILE",
      "profileUserId": "usr_123",
      "channels": ["markidy"],
      "message": "Interested in discussing a role.",
      "profile": {
        "displayName": "Alice",
        "description": "Founder and operator.",
        "verifiedLevel": 1,
        "country": "us",
        "socialLinks": {
          "linkedin": "https://linkedin.com/in/alice"
        }
      },
      "createdAt": "2026-03-18T12:00:00.000Z",
      "respondedAt": null,
      "rejectedReason": null
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 16
}

Response Fields

Field	Type	Description
`id`	string	Request ID
`status`	string	`PENDING`, `ACCEPTED`, or `REJECTED`
`subjectType`	string	Always `PROFILE`
`profileUserId`	string	Your profile user ID
`channels`	string[]	Requested channels
`message`	string	Request message
`profile`	object	Requester public profile summary
`createdAt`	string	ISO 8601 creation timestamp
`respondedAt`	string \| null	Accepted or rejected timestamp
`rejectedReason`	string \| null	Owner-provided rejection reason

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

Accept or reject a pending request. The owner check is subject-aware: listing requests require the listing owner, and profile requests require the target profile owner.

Request Body

Field	Type	Required	Description
`status`	string	Yes	`ACCEPTED` or `REJECTED`
`reason`	string	No	Optional rejection reason when status is `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" }'

Response

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

Accepted requests can be continued through GET /v1/conversations. Use subjectType, listingId, or profileUserId to narrow request and conversation lists.

Previous ← Listings Next Conversations →