Matches API — Mutual Likes, Feed, and Date Coordination

A match in Debuta is created when two users have each liked the other. The Matches API covers the full lifecycle: sending likes and dislikes from the swipe feed, fetching the list of mutual matches for the chat inbox, and coordinating in-app date suggestions at a partner restaurant. Date suggestions themselves are triggered automatically by the server after 5 messages — not by a REST call — but this API lets users respond to them.

Endpoints

GET /api/matches

List all mutual matches with last message and unread count.

POST /api/matches/like/:targetId

Like a user. Returns match status immediately.

POST /api/matches/dislike/:targetId

Dislike a user. Removes them from future discover results.

POST /api/matches/:id/accept-date

Accept the active restaurant date suggestion.

POST /api/matches/:id/reject-date

Reject the active date suggestion.

POST /api/matches/:id/suggest-new-place

Request a different restaurant for the date.

All endpoints require authentication via Authorization: Bearer <access_token>.

GET /api/matches

Returns every mutual match for the authenticated user, sorted by most recent match date. Each item includes the matched user’s profile, the last message in the conversation, and an unread message count.

Response `200 OK`

{
  "matches": [
    {
      "id": "64f1a2b3c4d5e6f7a8b9c0d2",
      "matched_user": {
        "id": "64f1a2b3c4d5e6f7a8b9c0d1",
        "first_name": "Valentina",
        "last_name": "Ríos",
        "username": "valerios",
        "profile_picture": {
          "url": "https://res.cloudinary.com/debuta/image/upload/v1/profiles/val.jpg",
          "public_id": "profiles/val"
        },
        "is_verified": true,
        "birth_date": "1998-04-12T00:00:00.000Z"
      },
      "last_message": {
        "id": "64f9aa11b2c3d4e5f6a7b8c9",
        "sender_id": "64f1a2b3c4d5e6f7a8b9c0d1",
        "receiver_id": "64f0000000000000000000aa",
        "content": "¡Hola! ¿Cómo estás?",
        "is_read": true,
        "created_at": "2024-07-15T21:05:33.000Z"
      },
      "unread_count": 0,
      "total_mensajes": 4,
      "created_at": "2024-07-14T18:22:11.000Z",
      "recomendacion": null
    }
  ]
}

matches

Match[]

Array of mutual match objects.

string

Match document ID.

matched_user

object

Profile of the other user in this match.

last_message

object | null

Most recent message in this conversation, or null if none yet.

unread_count

number

Number of unread messages sent by the matched user to the current user.

total_mensajes

number

Total messages exchanged in this match (used to determine date suggestion eligibility).

created_at

string

ISO 8601 timestamp of when the mutual match was created.

recomendacion

object | null

Active date suggestion object if one has been generated, otherwise null. See date suggestion fields below.

Example

curl -X GET https://api.debuta.app/api/matches \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

POST /api/matches/like/:targetId

Sends a like from the current user to targetId. If targetId has already liked the current user, a mutual match is created and both users receive a match:nuevo Socket.io event. If no mutual like exists yet, the target user receives a like:recibido Socket.io event instead.

Path parameters

targetId

string

required

The MongoDB _id of the user to like.

Response `200 OK`

{
  "esMatch": true,
  "matchId": "64f1a2b3c4d5e6f7a8b9c0d2",
  "recomendacion": null,
  "message": "🎉 ¡Es un match!"
}

When no mutual like exists yet:

{
  "esMatch": false,
  "matchId": "64f1a2b3c4d5e6f7a8b9c0d2",
  "recomendacion": null,
  "message": "Like enviado"
}

esMatch

boolean

true if this like created a mutual match.

matchId

string

The ID of the Match document (new or pre-existing).

recomendacion

object | null

Any active date recommendation on this match document.

Error responses

Status	Body	Description
`400`	`{ "message": "No puedes darte like a ti mismo" }`	`targetId` equals the current user’s ID
`400`	`{ "message": "Ya le diste like a este usuario" }`	Duplicate like attempted

Example

curl -X POST https://api.debuta.app/api/matches/like/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

POST /api/matches/dislike/:targetId

Records a dislike against targetId. The target user will no longer appear in the current user’s discovery feed. No Socket.io event is emitted for dislikes.

Path parameters

targetId

string

required

The MongoDB _id of the user to dislike.

Response `200 OK`

{ "message": "Dislike registrado" }

Error responses

Status	Description
`400`	Already interacted with this user
`400`	Cannot dislike yourself

Example

curl -X POST https://api.debuta.app/api/matches/dislike/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

POST /api/matches/:id/accept-date

Accepts the active restaurant date suggestion on a match. The server records which user accepted via user1Acepta / user2Acepta flags. When both users have accepted, recomendacion.estado changes to "aceptada" and a cita:confirmada Socket.io event is emitted to the restaurant’s associated partner account. The other user also receives a cita:estado-actualizado event immediately.

Path parameters

string

required

The Match document ID (returned in GET /api/matches as id).

Response `200 OK`

{
  "message": "Cita aceptada",
  "recomendacion": {
    "restauranteId": "64f9000000000000000000bb",
    "asociadoId": "64f9000000000000000000cc",
    "estado": "pendiente",
    "user1Acepta": true,
    "user2Acepta": false,
    "fechaSugerida": "Sábado 8:00 PM",
    "sugeridaEn": "2024-07-15T21:10:00.000Z"
  }
}

Error responses

Status	Description
`400`	No active date suggestion on this match
`403`	Current user is not part of this match
`404`	Match not found

Example

curl -X POST https://api.debuta.app/api/matches/64f1a2b3c4d5e6f7a8b9c0d2/accept-date \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

POST /api/matches/:id/reject-date

Marks the current date suggestion as "rechazada". Neither user can act on the suggestion after rejection until a new one is proposed.

Path parameters

string

required

The Match document ID.

Response `200 OK`

{
  "message": "Cita rechazada",
  "recomendacion": {
    "estado": "rechazada",
    "user1Acepta": false,
    "user2Acepta": false,
    "fechaSugerida": "Viernes 7:30 PM"
  }
}

Example

curl -X POST https://api.debuta.app/api/matches/64f1a2b3c4d5e6f7a8b9c0d2/reject-date \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

POST /api/matches/:id/suggest-new-place

Replaces the current date suggestion with a randomly selected active restaurant that is different from the current one. Both users receive a cita:nueva-sugerencia Socket.io event with the full new restaurant payload.

Path parameters

string

required

The Match document ID.

Response `200 OK`

{
  "message": "Nuevo lugar sugerido",
  "restaurante": {
    "_id": "64f9000000000000000000dd",
    "nombre": "Cielo Rojo",
    "descripcion": "Cocina de autor con vista panorámica.",
    "categoria": "fusión",
    "ambiente": "romántico",
    "direccion": "Cra. 43A #18-17, Medellín",
    "precio_promedio": "$$$",
    "horario": "Lunes a Domingo 12pm – 11pm",
    "foto_portada": {
      "url": "https://res.cloudinary.com/debuta/image/upload/v1/restaurants/cielorojo.jpg",
      "public_id": "restaurants/cielorojo"
    }
  },
  "recomendacion": {
    "restauranteId": "64f9000000000000000000dd",
    "estado": "pendiente",
    "user1Acepta": false,
    "user2Acepta": false,
    "fechaSugerida": "Domingo 9:00 PM",
    "sugeridaEn": "2024-07-15T22:00:00.000Z"
  }
}

Error responses

Status	Description
`403`	Current user is not part of this match
`404`	Match not found, or no other restaurants available

Example

curl -X POST https://api.debuta.app/api/matches/64f1a2b3c4d5e6f7a8b9c0d2/suggest-new-place \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Date suggestion object

The recomendacion field appears on match objects whenever a date has been suggested.

recomendacion

object | null

restauranteId

string

ID of the suggested restaurant.

asociadoId

string

ID of the restaurant’s partner (associated user account).

estado

string

Current status: "pendiente", "aceptada", or "rechazada".

user1Acepta

boolean

Whether the first user in the match has accepted.

user2Acepta

boolean

Whether the second user in the match has accepted.

fechaSugerida

string

Human-readable suggested date/time, e.g. "Sábado 8:00 PM".

sugeridaEn

string

ISO 8601 timestamp of when the suggestion was generated.

Date suggestions are not triggered via REST. The server automatically generates a cita:sugerencia Socket.io event and saves a recomendacion to the match document when the total message count in the conversation reaches 5. Use this REST API only to respond to a suggestion (accept, reject, or swap venue) after it has been created.

Authentication

Users & Profiles

Discovery & Matching

Chat & Calls

Content & Safety

Partners & Support

Documentation Index

​Endpoints

GET /api/matches

POST /api/matches/like/:targetId

POST /api/matches/dislike/:targetId

POST /api/matches/:id/accept-date

POST /api/matches/:id/reject-date

POST /api/matches/:id/suggest-new-place

​GET /api/matches

​Response 200 OK

​Example

​POST /api/matches/like/:targetId

​Path parameters

​Response 200 OK

​Error responses

​Example

​POST /api/matches/dislike/:targetId

​Path parameters

​Response 200 OK

​Error responses

​Example

​POST /api/matches/:id/accept-date

​Path parameters

​Response 200 OK

​Error responses

​Example

​POST /api/matches/:id/reject-date

​Path parameters

​Response 200 OK

​Example

​POST /api/matches/:id/suggest-new-place

​Path parameters

​Response 200 OK

​Error responses

​Example

​Date suggestion object

Build docs developers (and LLMs) love

Endpoints

GET /api/matches

Response `200 OK`

Example

POST /api/matches/like/:targetId

Path parameters

Response `200 OK`

Error responses

Example

POST /api/matches/dislike/:targetId

Path parameters

Response `200 OK`

Error responses

Example

POST /api/matches/:id/accept-date

Path parameters

Response `200 OK`

Error responses

Example

POST /api/matches/:id/reject-date

Path parameters

Response `200 OK`

Example

POST /api/matches/:id/suggest-new-place

Path parameters

Response `200 OK`

Error responses

Example

Date suggestion object