API Reference

Conversations

Manage real-time messaging between matched users. Conversations are automatically created when a match request is accepted.

List Conversations

GET /v1/conversations

List all your listing and profile conversations. Filter by listing or profile if needed.

Query Parameters

Parameter	Type	Description
`listingId`	string	Filter by specific listing
`profileUserId`	string	Filter profile conversations by profile owner user ID
`subjectType`	string	`LISTING` or `PROFILE`

Response

{
  "conversations": [
    {
      "id": "conv_...",
      "subjectType": "PROFILE",
      "subjectTitle": "Profile request",
      "subjectHref": "/profile/usr_123",
      "listingId": null,
      "listingTitle": null,
      "profileUserId": "usr_123",
      "matchRequestId": "mr_...",
      "matchStatus": "ACCEPTED",
      "otherUser": {
        "id": "user_...",
        "displayName": "Alice",
        "verifiedLevel": 1,
        "country": "us",
        "socials": {
          "linkedin": "https://linkedin.com/in/alice",
          "github": "https://github.com/alice",
          "website": "https://alice.dev"
        }
      },
      "lastMessage": {
        "body": "Hello!",
        "senderId": "user_...",
        "createdAt": "2026-03-25T12:01:00Z"
      },
      "unreadCount": 3,
      "otherLeft": false,
      "createdAt": "2026-03-25T12:00:00Z"
    }
  ],
  "total": 5
}

Response Fields

Field	Type	Description
`id`	string	Conversation ID
`subjectType`	string	`LISTING` or `PROFILE`
`subjectTitle`	string	Human-readable subject label for listing or profile conversations
`subjectHref`	string	Public URL for the conversation subject
`listingId`	string \| null	Associated listing ID for listing conversations
`listingTitle`	string \| null	Listing title for listing conversations
`profileUserId`	string \| null	Profile owner user ID for profile conversations
`matchStatus`	string	`ACCEPTED`
`otherUser`	object	Other participant info
`otherUser.socials`	object	Social links (`x`, `linkedin`, `github`, `instagram`, `tiktok`, `youtube`, `website`). Only present fields are included.
`lastMessage`	object \| null	Most recent message
`unreadCount`	integer	Number of unread messages
`createdAt`	string	ISO 8601 timestamp
`otherLeft`	boolean	`true` if the other party has left this conversation. Sending messages returns 403.

Conversation Detail

GET /v1/conversations/{id}

Get conversation details with paginated message history. Returns the most recent messages first.

Query Parameters

Parameter	Type	Description
`before`	string	Message ID cursor — fetch messages older than this
`limit`	integer	Number of messages (default: 50, max: 100)

Response

{
  "conversation": {
    "id": "conv_...",
    "subjectType": "PROFILE",
    "subjectTitle": "Profile request",
    "subjectHref": "/profile/usr_123",
    "listingId": null,
    "listingTitle": null,
    "profileUserId": "usr_123",
    "matchStatus": "ACCEPTED",
    "otherUser": {
      "id": "user_...",
      "displayName": "Alice",
      "verifiedLevel": 1,
      "country": "us",
      "socials": {
        "linkedin": "https://linkedin.com/in/alice",
        "github": "https://github.com/alice",
        "website": "https://alice.dev"
      }
    },
    "messages": [
      {
        "id": "msg_...",
        "senderId": "user_...",
        "body": "Hello!",
        "createdAt": "2026-03-25T12:01:00Z"
      }
    ],
    "hasMore": true,
    "otherLeft": false
  }
}

Send Message

POST /v1/conversations/{id}/messages

Send a message in a conversation. The conversation must have an ACCEPTED match status and otherLeft must be false.

Request Body

Field	Type	Required	Description
`body`	string	✅	Message content

Request

curl -X POST https://api.markidy.com/v1/conversations/conv_abc123/messages \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Hello, I am interested in your service." }'

Response (201)

{
  "id": "msg_...",
  "conversationId": "conv_...",
  "body": "Hello, I am interested in your service.",
  "createdAt": "2026-03-25T12:01:00Z"
}

Sending a message triggers the message.new webhook event to the recipient.

Delete Conversation

DELETE /v1/conversations/{id}

Leave a conversation. The conversation is hidden from your list, but remains visible to the other party with otherLeft: true. Neither party can send further messages.

Request

curl -X DELETE https://api.markidy.com/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer mk_your_api_key"

Response

{ "success": true }

This is a soft-delete per user. The other party can still view the conversation history but will see otherLeft: true and cannot reply.

Previous ← Match Requests Next Tools →