Dating App API (0.11.1)

Download OpenAPI specification:

API Support: dev@terasa.cloud License: MIT

Onboarding-first API for a Laravel 12 + MariaDB backend using Sanctum tokens. All endpoints are JSON and Bearer token authenticated unless otherwise noted.

Auth

Authentication endpoints for registration, OTP verification, and login.

Register creates an unverified account and sends an OTP.
OTP endpoints resend and verify codes.
Login issues a Sanctum personal access token (Bearer).

Password & token best practices

Register (sends OTP)

Creates a user and sends an OTP to the provided email.

Request Body schema: application/json
required

email required	string <email> <= 191 characters
password required	string >= 8 characters

Responses

Request samples

Payload
curl
fetch
Guzzle

Content type

application/json

{"email": "jane@gmail.com",
"password": "Secret12345"
}

Response samples

201
422

Content type

application/json

{"message": "OTP sent to email for verification.",
"success": true,
"code": 201
}

Resend OTP

Request Body schema: application/json
required

channel required	string Default: "email" Enum: "email" "sms" "whatsapp"
destination required	string
purpose required	string Enum: "password_reset" "register"

Responses

Request samples

Payload
cURL

Content type

application/json

{"channel": "email",
"destination": "jane@gmail.com",
"purpose": "register"
}

Response samples

200
400
429

Content type

application/json

{"message": "OTP resent to jane@gmail.com",
"success": true,
"code": 201
}

Verify OTP

Request Body schema: application/json
required

channel required	string Default: "email" Enum: "email" "sms" "whatsapp"
destination required	string
code required	string^\d{4}$
device_name	string
device_os	string
os_version	string

Responses

Request samples

Payload
cURL

Content type

application/json

{"channel": "email",
"destination": "jane@gmail.com",
"code": "1234",
"device_name": "Pixel 9",
"device_os": "android | ios",
"os_version": "android 14 | ios 18"
}

Response samples

200
422

Content type

application/json

{"message": "Verification successful.",
"success": true,
"code": 200,
"results": {"token_type": "Bearer",
"token": "2|5c0f9...long_plain_text_token"
}
}

Login

Request Body schema: application/json
required

email required	string <email>
password required	string
device_name required	string
device_os	string
os_version	string

Responses

Request samples

Payload
cURL

Content type

application/json

{"email": "jane@gmail.com",
"password": "Password1234567",
"device_name": "Pixel 9",
"device_os": "android | ios",
"os_version": "android 14 | ios 18"
}

Response samples

200
401
403
422

Content type

application/json

{"message": "Login Success",
"success": true,
"code": 200,
"results": {"token_type": "Bearer",
"token": "2|5c0f9...long_plain_text_token"
}
}

Logout (revoke current token)

Authorizations:

BearerAuth

Responses

Request samples

cURL

curl -X POST "{{BASE}}/auth/logout" \
  -H "Accept: application/json" -H "Authorization: Bearer {{TOKEN}}"

Response samples

200
401

Content type

application/json

{"message": "Logged out.",
"success": true,
"code": 200
}

Reset Password OTP

Request Body schema: application/json
required

channel required	string Default: "email" Enum: "email" "sms" "whatsapp"
email required	string

Responses

Request samples

Payload
cURL

Content type

application/json

{"channel": "email",
"email": "jane@gmail.com"
}

Response samples

200
400
429

Content type

application/json

{"message": "OTP sent to email for password reset.",
"success": true,
"code": 201
}

Verify Reset Password OTP

Request Body schema: application/json
required

email required	string
code required	string^\d{4}$

Responses

Request samples

Payload
cURL

Content type

application/json

{"email": "jane@gmail.com",
"code": "1234"
}

Response samples

200
422

Content type

application/json

{"message": "OTP verified.",
"success": true,
"code": 200,
"results": {"reset_token": "01K76KN4MBPDBS97J9G9VTCW33",
"expires_in": 900
}
}

Reset Password

Request Body schema: application/json
required

email required	string
reset_token required	string
password required	string
password_confirmation required	string

Responses

Request samples

Payload
cURL

Content type

application/json

{"email": "jane@gmail.com",
"reset_token": "01K76KN4MBPDBS97J9G9VTCW33",
"password": "Jane1234567890",
"password_confirmation": "Jane1234567890"
}

Response samples

200
422

Content type

application/json

{"message": "Password updated. You can now log in.",
"success": true,
"code": 200
}

Onboarding

Profile setup endpoints used in the mobile onboarding flow: nickname, DOB, gender, relationship goals, distance preference, and interests.

Upsert onboarding profile

Authorizations:

BearerAuth

Request Body schema: application/json
required

nickname	string or null <= 50 characters
date_of_birth	string or null <date>
gender	string or null Enum: "male" "female" "other"
relationship_goal	string or null Enum: "dating" "friendship" "casual" "serious"
	object (distance-pref-input)

Responses

Request samples

Payload
cURL

Content type

application/json

{"nickname": "jane_",
"date_of_birth": "1997-07-21",
"gender": "female",
"relationship_goal": "serious",
"distance_pref": {"value": 30,
"unit": "km"
}
}

Response samples

200
422

Content type

application/json

{"message": "Profile updated.",
"success": true,
"code": 200,
"results": {"nickname": "jane_",
"date_of_birth": "1997-07-21",
"gender": "female",
"relationship_goal": "dating",
"distance_pref_meters": {"value": 30,
"unit": "km"
}
}
}

Replace user's interests (max 10)

Authorizations:

BearerAuth

Request Body schema: application/json
required

interest_ids

required

Array of strings (ulid) <= 10 items

Responses

Request samples

Payload
cURL

Content type

application/json

{"interest_ids": ["01J8Z2A0CJ6EJ2S2H4Q8GQJ0ZC",
"01J8Z2A3DGTN0Q0ZX8Q6Y7Q5MS"
]
}

Response samples

200
422

Content type

application/json

{"message": "Interests updated.",
"success": true,
"code": 200
}

Photos

Manage profile photos (max 6). Supports upload, reorder, and delete.

Upload a profile photo (max 6)

Authorizations:

BearerAuth

Request Body schema: multipart/form-data
required

photo required	string <binary>
position	integer [ 1 .. 6 ]

Responses

Request samples

cURL
fetch (FormData)

curl -X POST "{{BASE}}/onboarding/photos" \
  -H "Accept: application/json" -H "Authorization: Bearer {{TOKEN}}" \
  -F "photo=@/path/to/photo.jpg" -F "position=1"

Response samples

201
401
422

Content type

application/json

{"message": "Photo created.",
"success": true,
"code": 201,
"results": {"id": "01J8Z1TB9KVFQ0Y7ZP6F8F1K3V",
"url": "http://example.com",
"position": 1,
"width": "200,",
"height": "500,",
"mime": "jpeg"
}
}

Reorder a photo (change position)

Authorizations:

BearerAuth

path Parameters

photoId

required

string (ulid)

Example: 01J8Z1TB9KVFQ0Y7ZP6F8F1K3V

ULID identifier as string (26 chars).

Request Body schema: application/json
required

position

required

integer [ 1 .. 6 ]

Responses

Request samples

Payload
cURL

Content type

application/json

{"position": 2
}

Response samples

200
403
404

Content type

application/json

{"message": "Photo reordered successfully.",
"success": true,
"code": 200,
"results": {"id": "01J8Z1TB9KVFQ0Y7ZP6F8F1K3V",
"url": "http://example.com",
"position": 1,
"width": "200,",
"height": "500,",
"mime": "jpeg"
}
}

Delete a photo

Authorizations:

BearerAuth

path Parameters

photoId

required

string (ulid)

Example: 01J8Z1TB9KVFQ0Y7ZP6F8F1K3V

ULID identifier as string (26 chars).

Responses

Request samples

cURL

curl -X DELETE "{{BASE}}/onboarding/photos/01J8Z1TZ9MB5ZP7VQ9CQP6K0TE" \
  -H "Accept: application/json" -H "Authorization: Bearer {{TOKEN}}"

Response samples

200
403
404

Content type

application/json

{"message": "Photo removed.",
"status": true,
"code": 200
}

Me

Endpoints for the currently authenticated user, returning a consolidated snapshot: user, profile, interests, and photos.

Get current user with profile, interests, and photos

Authorizations:

BearerAuth

Responses

Request samples

cURL

curl "{{BASE}}/me" -H "Accept: application/json" -H "Authorization: Bearer {{TOKEN}}"

Response samples

200
401

Content type

application/json

{"user": {"id": 123,
"f_name": "string",
"l_name": "string",
"email": "user@example.com",
"email_verified": true
},
"profile": {"message": "Profile updated.",
"success": true,
"code": 200,
"results": {"nickname": "jane_",
"date_of_birth": "1997-07-21",
"gender": "female",
"relationship_goal": "dating",
"distance_pref_meters": {"value": 30,
"unit": "km"
}
}
},
"interests": [{"message": "Interest List.",
"success": true,
"code": 200,
"results": {"id": "01J8Z1TB9KVFQ0Y7ZP6F8F1K3V",
"category": "Aktivitas Sosial",
"sub_category": "Suka Berkumpul dengan Teman",
"name": "Hangout",
"slug": "suka-berkumpul-dengan-teman-hangout",
"status": "Active"
}
}
],
"photos": [{"id": "01J8Z1TB9KVFQ0Y7ZP6F8F1K3V",
"url": "http://example.com",
"position": 1,
"width": 0,
"height": 0,
"mime": "string"
}
]
}

Get user matched data with profile, interests, and photos

Authorizations:

BearerAuth

path Parameters

userId

required

integer (id)

Example: 123

UserId of the user you matched

Responses

Request samples

cURL

curl "{{BASE}}/me/01J8Z1TZ9MB5ZP7VQ9CQP6K0TE" -H "Accept: application/json" -H "Authorization: Bearer {{TOKEN}}"

Response samples

200
401

Content type

application/json

{"user": {"id": 123,
"f_name": "string",
"l_name": "string",
"email": "user@example.com",
"email_verified": true
},
"profile": {"message": "Profile updated.",
"success": true,
"code": 200,
"results": {"nickname": "jane_",
"date_of_birth": "1997-07-21",
"gender": "female",
"relationship_goal": "dating",
"distance_pref_meters": {"value": 30,
"unit": "km"
}
}
},
"interests": [{"message": "Interest List.",
"success": true,
"code": 200,
"results": {"id": "01J8Z1TB9KVFQ0Y7ZP6F8F1K3V",
"category": "Aktivitas Sosial",
"sub_category": "Suka Berkumpul dengan Teman",
"name": "Hangout",
"slug": "suka-berkumpul-dengan-teman-hangout",
"status": "Active"
}
}
],
"photos": [{"id": "01J8Z1TB9KVFQ0Y7ZP6F8F1K3V",
"url": "http://example.com",
"position": 1,
"width": 0,
"height": 0,
"mime": "string"
}
]
}

Update current user's location

Saves or updates the authenticated user's location for discovery. Requires Bearer token (Sanctum).

Authorizations:

BearerAuth

Request Body schema: application/json
required

lat required	number [ -90 .. 90 ]
lng required	number [ -180 .. 180 ]
city	string or null <= 120 characters
country	string or null <= 120 characters

Responses

Request samples

Payload
curl
fetch
Guzzle

Content type

application/json

{"lat": -6.2,
"lng": 106.8167,
"city": "Jakarta",
"country": "ID"
}

Response samples

200
401
422

Content type

application/json

{"message": "Location updated.",
"location": {"lat": -6.2,
"lng": 106.8167,
"city": "Jakarta",
"country": "ID",
"updated_at": "2025-08-29T08:15:30Z"
}
}

Discover

Candidate discovery, reactions (like/pass), and match creation/listing. Powers the swipe deck and “It's a match!” flow.

Get discovery preferences

Authorizations:

BearerAuth

Responses

Request samples

cURL

curl -s "{{BASE}}/me/preferences" \
  -H "Accept: application/json" -H "Authorization: Bearer {{TOKEN}}"

Response samples

200
401

Content type

application/json

{"gender_pref": "female",
"age_min": 21,
"age_max": 35,
"max_distance_meters": 30000,
"discoverable": true
}

Update discovery preferences

Partial update. Any omitted field keeps its current value. Server enforces age_max >= age_min and bounds.

Authorizations:

BearerAuth

Request Body schema: application/json
required

gender_pref	string or null Enum: "male" "female" "other" "everyone" null
age_min	integer [ 18 .. 100 ]
age_max	integer [ 18 .. 100 ]
max_distance_meters	integer [ 1000 .. 200000 ]
discoverable	boolean

Responses

Request samples

Payload
cURL
fetch
Guzzle

Content type

application/json

{"age_min": 19,
"age_max": 45,
"max_distance_meters": 60000
}

Response samples

200
401
422

Content type

application/json

{"gender_pref": "female",
"age_min": 21,
"age_max": 35,
"max_distance_meters": 30000,
"discoverable": true
}

Discover nearby candidates

Returns a paginated list of candidates filtered by the user's preferences and location. Requires the user to have a saved location.

Authorizations:

BearerAuth

query Parameters

limit	integer [ 1 .. 50 ] Default: 20 Page size (max 50).
page	integer >= 1 Default: 1 Page number.

Responses

Request samples

cURL
fetch
Guzzle

curl -s "{{BASE}}/discover?limit=20" \
  -H "Accept: application/json" -H "Authorization: Bearer {{TOKEN}}"

Response samples

200
401
422

Content type

application/json

{"data": [{"id": "01...",
"nickname": "Jane",
"age": 28,
"shared_interests_count": 2,
"photos": [ ],
"interests": [ ]
}
],
"next_page": 2
}

Like or pass a user

Authorizations:

BearerAuth

path Parameters

userId

required

integer (id)

Example: 123

UserId of the user you react to

Request Body schema: application/json
required

action

required

string

Enum: "like" "pass"

Responses

Request samples

Payload
like
pass

Content type

application/json

{"action": "like"
}

Response samples

200
401
403
404
422

Content type

application/json

{"message": "Recorded.",
"liked": true,
"matched": true,
"match_id": "01J8Z9M4D4C9V5E4K4P5C9S3NQ"
}

List your matches

Authorizations:

BearerAuth

Responses

Request samples

cURL

curl -s "{{BASE}}/matches" \
  -H "Accept: application/json" -H "Authorization: Bearer {{TOKEN}}"

Response samples

200
401

Content type

application/json

[{"match_id": "01J8Z9M4D4C9V5E4K4P5C9S3NQ",
"matched_at": "2025-08-29T08:30:00Z",
"partner": {"id": 123,
"name": "Jane Doe",
"nickname": "Jane",
"gender": "female",
"photos": [{"id": "01...",
"url": "https://cdn/p1.jpg",
"position": 1
}
]
}
}
]

Messaging

1:1 conversations automatically created when two users match.

List conversations ordered by last_message_at.
List messages in ascending order and mark partner messages as read.
Send message (max 2000 chars).

List conversations

Returns conversations for the current user ordered by last_message_at (desc), with partner info, last message, and unread_count.

Authorizations:

BearerAuth

query Parameters

limit	integer [ 1 .. 50 ] Default: 20 Page size (max 50).
page	integer >= 1 Default: 1 Page number.

Responses

Request samples

cURL
fetch
Guzzle

curl -s "{{BASE}}/conversations?limit=20" \
  -H "Accept: application/json" -H "Authorization: Bearer {{TOKEN}}"

Response samples

200
401

Content type

application/json

[{"id": "01M0SG6J6N9Z6DJ6Z4JHH6X8H5",
"last_message_at": "2025-08-29T09:57:00Z",
"unread_count": 2,
"partner": {"id": 123,
"name": "Jane Doe",
"nickname": "Jane",
"photos": [{"id": "01...",
"url": "https://cdn/p1.jpg",
"position": 1
}
]
},
"last_message": {"id": "01M0SG6J7…",
"body": "hi there 👋",
"sender_id": "01J8Z1TB9KVFQ0Y7ZP6F8F1K3V",
"mine": false,
"created_at": "2025-08-29T09:57:00Z",
"read_at": null
}
}
]

List messages in a conversation

Returns messages in ascending order. Partner messages are marked as read when fetched.

Authorizations:

BearerAuth

path Parameters

conversationId

required

string (ulid)

Example: 01J8Z1TB9KVFQ0Y7ZP6F8F1K3V

ULID identifier as string (26 chars).

query Parameters

limit	integer [ 1 .. 100 ] Default: 30 Page size (max 100).
page	integer >= 1 Default: 1 Page number.

Responses

Request samples

cURL

curl -s "{{BASE}}/conversations/01M0SG6J6N9Z6DJ6Z4JHH6X8H5/messages?limit=30" \
  -H "Accept: application/json" -H "Authorization: Bearer {{TOKEN}}"

Response samples

200
401
403

Content type

application/json

[{"id": "01M0SG6J6N9Z6DJ6Z4JHH6X8H5",
"body": "hi there 👋",
"sender_id": 123,
"mine": true,
"created_at": "2025-08-29T09:57:00Z",
"read_at": null
}
]

Send a message

Authorizations:

BearerAuth

path Parameters

conversationId

required

string (ulid)

Example: 01J8Z1TB9KVFQ0Y7ZP6F8F1K3V

ULID identifier as string (26 chars).

Request Body schema: application/json
required

body

required

string [ 1 .. 2000 ] characters

Responses

Request samples

Payload
cURL
fetch
Guzzle

Content type

application/json

{"body": "hi there 👋"
}

Response samples

201
401
403
422

Content type

application/json

{"id": "01M0SG6J6N9Z6DJ6Z4JHH6X8H5",
"body": "hi there 👋",
"sender_id": 123,
"mine": true,
"created_at": "2025-08-29T09:57:00Z",
"read_at": null
}

Mark conversation as read

Marks partner messages as read. If up_to_message_id is provided, marks reads up to and including that message.

Authorizations:

BearerAuth

path Parameters

conversationId

required

string (ulid)

Example: 01J8Z1TB9KVFQ0Y7ZP6F8F1K3V

ULID identifier as string (26 chars).

Request Body schema: application/json
optional

up_to_message_id

string (ulid)

ULID of the last message to mark as read.

Responses

Request samples

Payload
mark all
mark up to a message
fetch
Guzzle

Content type

application/json

Example

Mark everything read

{ }

Response samples

200
401
403
422

Content type

application/json

{"message": "Read state updated."
}

List interests

Responses

Request samples

cURL

curl "{{BASE}}/meta/interests" -H "Accept: application/json"

Response samples

200
400

Content type

application/json

{"message": "Interest List.",
"success": true,
"code": 200,
"results": {"id": "01J8Z1TB9KVFQ0Y7ZP6F8F1K3V",
"category": "Aktivitas Sosial",
"sub_category": "Suka Berkumpul dengan Teman",
"name": "Hangout",
"slug": "suka-berkumpul-dengan-teman-hangout",
"status": "Active"
}
}

Dating App API (0.11.1)

Auth

Register (sends OTP)

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Resend OTP

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Verify OTP

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Login

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Logout (revoke current token)

Authorizations:

Responses

Request samples

Response samples

Reset Password OTP

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Verify Reset Password OTP

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Reset Password

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Onboarding

Upsert onboarding profile

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Replace user's interests (max 10)

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Photos

Upload a profile photo (max 6)

Authorizations:

Request Body schema: multipart/form-datarequired

Responses

Request samples

Response samples

Reorder a photo (change position)

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete a photo

Authorizations:

path Parameters

Responses

Request samples

Response samples

Me

Get current user with profile, interests, and photos

Authorizations:

Responses

Request samples

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: multipart/form-data
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
optional