♥Dating API
Developer documentation

Build something
worth meeting.

Use the Dating API to create accounts, manage profiles, discover people, and exchange match requests. All endpoints are served from this site and accept or return JSON unless noted otherwise.

BASE URL
Authentication note — The current API has no token/session system. Authenticated requests send the account's username and password in the JSON body (or multipart form for profile images). Always use HTTPS; do not put credentials in URLs or logs. This prototype is not production-ready authentication.

Quick start

A typical integration starts by registering, then uses those credentials for profile and matching actions.

01 / CREATE

Register an account

Send a username, valid email, and password with at least 8 characters.

02 / PROFILE

Complete your profile

Set a nickname, gender, and optionally upload a profile image.

03 / CONNECT

Explore and like

Browse profiles, send a like, and check received or requested likes.

Register with cURL

Replace the origin with this API's HTTPS address. JSON property names are case-insensitive; response properties use camelCase.

curl -X POST "/Account/Register" \
  -H "Content-Type: application/json" \
  -d '{"username":"alex","email":"alex@example.com","password":"a-long-password"}'

Authentication & responses

There is no bearer token. For every endpoint marked “credentials required,” include username and password in its JSON request body.

Common HTTP responses

200 OK Successful request with a JSON body.
204 No Content Successful action with no response body.
400 Bad Request Invalid input or unsupported value.
401 Unauthorized Credentials are invalid.
404 Not Found Target profile or request was not found.
409 Conflict Registration username is already in use.

Endpoint reference

All routes are relative to the base URL above. Requests use Content-Type: application/json except image uploads.

Account

POST/Account/Register

Create an account. Username must not be blank; password must be at least 8 characters; email must be valid.

Body
{ username, email, password }
Returns
200 AccountResponse, 409 username unavailable
View request and response
{"username":"alex","email":"alex@example.com","password":"a-long-password"}
// 200 OK
{"username":"alex","email":"alex@example.com","nickname":"","gender":"","profileImage":"","viewCount":0,"deactivated":false}
POST/Account/Login

Verify credentials and return the current account profile.

Body
{ username, password }
Returns
200 AccountResponse or 401
POST/Account/Nickname

Set a nonblank account nickname of up to 150 characters; it is saved trimmed.

Body
{ username, password, nickname }
Returns
200 AccountResponse
POST/Account/Gender

Set or clear gender. Allowed values: Woman, Man, Non-binary, Other, or empty string to clear.

Body
{ username, password, gender }
Returns
200 AccountResponse
POST/Account/ProfileImage

Upload a JPEG, PNG, GIF, or WebP image up to 5 MB. Send as multipart/form-data.

Form fields
username, password, image (file)
Returns
200 AccountResponse
POST/Account/ProfileView

Record a view of another profile and return its updated view count. Each call increments the count.

Body
{ username, password, profileId }
Returns
200 { viewCount }; 404 if profile missing
POST/Account/Deactivate

Deactivate the account, hiding its profile from other users. Credentials required.

Body
{ username, password }
Returns
204 No Content
POST/Account/Activate

Reactivate a deactivated account. Credentials required.

Body
{ username, password }
Returns
200 AccountResponse
POST/Account/Delete

Delete the account. This action cannot be undone. Credentials required.

Body
{ username, password }
Returns
204 No Content

Matches

POST/Match/Explore

Get up to 100 active profiles, ordered by ID. Excludes your own profile and profiles you have already liked. Omit gender for all genders; use one of the supported gender values to filter. Use the last returned profile's ID as afterId to fetch the next page, keeping the same filter.

Body
{ username, password }
Returns
200 array of ExploreProfile
View pagination example
POST /Match/Explore?gender=Woman
{"username":"alex","password":"a-long-password"}

POST /Match/Explore?gender=Woman&afterId=LAST_PROFILE_ID
{"username":"alex","password":"a-long-password"}
POST/Match/Requested

List profiles you have liked. Deleted or deactivated profiles are hidden.

Body
{ username, password }
Returns
200 array of MatchProfile
POST/Match/Received

List profiles that liked you. A reciprocal like sets isMatch on both requests.

Body
{ username, password }
Returns
200 array of MatchProfile
POST/Match/Like

Like another profile. If they have already liked you, the requests become a match.

Body
{ username, password, matchedUserId }
Returns
204 No Content, 404 if profile unavailable
POST/Match/Delete

Remove a like/request. Set received to true to delete a request from someone who liked you; false to delete your outgoing request.

Body
{ username, password, matchedUserId, received }
Returns
204 No Content, 404 if request unavailable

Detailed HTTP examples

These examples show the request bodies and representative responses for every endpoint. Replace the sample credentials and IDs with your own. The lines beginning with HTTP/1.1 show responses and are not part of the request.

Conventions and validation

Send JSON as Content-Type: application/json; JSON keys are case-insensitive. Usernames, passwords and email addresses have a maximum of 150 characters. Registration requires a valid email address and a password of at least eight characters. Profile IDs are non-empty GUIDs identifying another user, not match-record IDs.

Model-validation failures normally return 400 with a validation-problem JSON body; other errors can have a plain-text message or an empty body. Do not assume every error is JSON. Invalid credentials return 401, and unsupported media types may return 415. Image requests that exceed the server request-size limit can return 413.

Image paths such as /Images/example.jpg are relative to the API origin. Profile nickname, gender, and image values can be empty or null for existing accounts. Match email is null until a mutual match.

Register and login

Registration creates the account; login verifies credentials but does not issue a token. The same account response shape is returned by registration, login, nickname, gender, image, and activation.

POST /Account/Register
Content-Type: application/json

{"username":"alex","email":"alex@example.com","password":"a-long-password"}

HTTP/1.1 200 OK
Content-Type: application/json

{"username":"alex","email":"alex@example.com","nickname":"","gender":"","profileImage":"","viewCount":0,"deactivated":false}

POST /Account/Login
Content-Type: application/json

{"username":"alex","password":"a-long-password"}

HTTP/1.1 200 OK
Content-Type: application/json

{"username":"alex","email":"alex@example.com","nickname":"","gender":"","profileImage":"","viewCount":0,"deactivated":false}

A duplicate username returns 409. Invalid credentials return 401; missing or invalid fields return 400.

Update nickname and gender

Nickname must be nonblank and no longer than 150 characters; it is saved trimmed. Gender is case-sensitive: Woman, Man, Non-binary, Other, or "" to clear.

POST /Account/Nickname
Content-Type: application/json

{"username":"alex","password":"a-long-password","nickname":"Alex"}

HTTP/1.1 200 OK
Content-Type: application/json

{"username":"alex","email":"alex@example.com","nickname":"Alex","gender":"","profileImage":"","viewCount":0,"deactivated":false}

POST /Account/Gender
Content-Type: application/json

{"username":"alex","password":"a-long-password","gender":"Non-binary"}

HTTP/1.1 200 OK
Content-Type: application/json

{"username":"alex","email":"alex@example.com","nickname":"Alex","gender":"Non-binary","profileImage":"","viewCount":0,"deactivated":false}

Upload a profile image

Use a multipart form with text fields username and password and a file field named image. The non-empty file must be at most 5 MiB (5,242,880 bytes) and have JPEG, PNG, GIF or WebP content. Replacing an image removes the previous stored image. Let your HTTP library set the multipart boundary.

curl -X POST "/Account/ProfileImage" \
  -F "username=alex" \
  -F "password=a-long-password" \
  -F "image=@profile.jpg"

HTTP/1.1 200 OK
Content-Type: application/json

{"username":"alex","email":"alex@example.com","nickname":"Alex","gender":"Non-binary","profileImage":"/Images/1234567890abcdef1234567890abcdef.jpg","viewCount":0,"deactivated":false}

The credentials in this cURL example are illustrative; avoid exposing real passwords in shell history or process arguments.

Explore and record a view

Omit gender for all profiles, or use one of the four gender values. Optional afterId is the last profile ID returned by the previous page. Keep the same filter while paging; URL-encode query values. A page contains at most 100 results: stop when it contains fewer than 100. An exactly full last page can be followed by an empty page. Profiles may change between requests; start again without afterId to refresh.

POST /Match/Explore?gender=Woman
Content-Type: application/json

{"username":"alex","password":"a-long-password"}

HTTP/1.1 200 OK
Content-Type: application/json

[{"id":"11111111-1111-1111-1111-111111111111","username":"sam","nickname":"Sam","profileImage":null}]

POST /Match/Explore?gender=Woman&afterId=11111111-1111-1111-1111-111111111111
Content-Type: application/json

{"username":"alex","password":"a-long-password"}

HTTP/1.1 200 OK
Content-Type: application/json

[]

POST /Account/ProfileView
Content-Type: application/json

{"username":"alex","password":"a-long-password","profileId":"11111111-1111-1111-1111-111111111111"}

HTTP/1.1 200 OK
Content-Type: application/json

{"viewCount":1}

The second Explore request illustrates the cursor syntax; in practice only request another page after a full page. Fetching profiles does not count as a view. Call ProfileView when displaying a profile; every call increments the count. Viewing yourself returns 400; an unavailable profile returns 404.

Like, list and remove requests

Use the other user's profile ID from Explore, Requested or Received. A like is directional; a reciprocal like marks both requests as a match. Both lists include matched and unmatched requests, hiding deleted or deactivated profiles.

POST /Match/Like
Content-Type: application/json

{"username":"alex","password":"a-long-password","matchedUserId":"11111111-1111-1111-1111-111111111111"}

HTTP/1.1 204 No Content

POST /Match/Requested
Content-Type: application/json

{"username":"alex","password":"a-long-password"}

HTTP/1.1 200 OK
Content-Type: application/json

[{"id":"11111111-1111-1111-1111-111111111111","nickname":"Sam","profileImage":null,"email":null,"isMatch":false}]

POST /Match/Received
Content-Type: application/json

{"username":"alex","password":"a-long-password"}

HTTP/1.1 200 OK
Content-Type: application/json

[{"id":"22222222-2222-2222-2222-222222222222","nickname":"Riley","profileImage":"/Images/example.jpg","email":"riley@example.com","isMatch":true}]

POST /Match/Delete
Content-Type: application/json

{"username":"alex","password":"a-long-password","matchedUserId":"11111111-1111-1111-1111-111111111111","received":false}

HTTP/1.1 204 No Content

For Match/Delete, received: false removes your outgoing request; true removes the other person's incoming request. Removing one side of a mutual match clears the match status and shared email on the remaining request. A missing request or unavailable profile returns 404; using your own ID returns 400.

Deactivate, activate and delete

Deactivation hides the profile but does not prevent login or automatically reactivate it. Activation restores a deactivated account. Deletion is irreversible: deleted accounts cannot sign in or be reactivated.

POST /Account/Deactivate
Content-Type: application/json

{"username":"alex","password":"a-long-password"}

HTTP/1.1 204 No Content

POST /Account/Activate
Content-Type: application/json

{"username":"alex","password":"a-long-password"}

HTTP/1.1 200 OK
Content-Type: application/json

{"username":"alex","email":"alex@example.com","nickname":"Alex","gender":"Non-binary","profileImage":"/Images/1234567890abcdef1234567890abcdef.jpg","viewCount":0,"deactivated":false}

POST /Account/Delete
Content-Type: application/json

{"username":"alex","password":"a-long-password"}

HTTP/1.1 204 No Content

Complete C# client example

This .NET console application uses HttpClient and System.Net.Http.Json, with no extra packages. Each invocation performs only the named operation. It prints the actual response body and fails on non-success HTTP status codes.

1. Create a console project

dotnet new console -n DatingApiExample
cd DatingApiExample

Replace Program.cs with the complete code below. Start the API using a trusted HTTPS certificate. Set DATING_API_URL to your HTTPS API URL (for example https://localhost:7208); set DATING_USERNAME and DATING_PASSWORD in your process environment. Set DATING_EMAIL only when registering. Use a fresh username for registration; later commands use the same credentials. Never commit credentials or disable certificate validation.

2. Program.cs

using System.Net.Http.Json;

if (args.Length == 0)
	throw new ArgumentException("Supply a command; see the commands below.");

string RequiredEnvironment(string name) =>
	Environment.GetEnvironmentVariable(name) is { Length: > 0 } value
		? value : throw new InvalidOperationException($"Set {name} first.");

string Argument(int index, string description) =>
	args.Length > index && !string.IsNullOrWhiteSpace(args[index])
		? args[index] : throw new ArgumentException($"Provide {description}.");

Guid ProfileId(int index) => Guid.TryParse(Argument(index, "a profile GUID"), out var id) && id != Guid.Empty
	? id : throw new ArgumentException("Provide a non-empty profile GUID.");

var baseUrl = new Uri(RequiredEnvironment("DATING_API_URL").TrimEnd('/') + "/");
if (baseUrl.Scheme != Uri.UriSchemeHttps)
	throw new InvalidOperationException("The API URL must use HTTPS.");
var username = RequiredEnvironment("DATING_USERNAME");
var password = RequiredEnvironment("DATING_PASSWORD");
using var client = new HttpClient { BaseAddress = baseUrl };
var credentials = new { username, password };

HttpResponseMessage response;
switch (args[0].ToLowerInvariant())
{
	case "register":
		response = await client.PostAsJsonAsync("Account/Register", new {
			username, password, email = RequiredEnvironment("DATING_EMAIL") });
		break;
	case "login":
		response = await client.PostAsJsonAsync("Account/Login", credentials);
		break;
	case "nickname":
		response = await client.PostAsJsonAsync("Account/Nickname", new {
			username, password, nickname = Argument(1, "a nickname") });
		break;
	case "gender":
		// Pass 'clear' to send an empty gender.
		var gender = Argument(1, "a gender or clear");
		response = await client.PostAsJsonAsync("Account/Gender", new {
			username, password, gender = gender == "clear" ? "" : gender });
		break;
	case "image":
		using (var form = new MultipartFormDataContent())
		{
			form.Add(new StringContent(username), "username");
			form.Add(new StringContent(password), "password");
			var path = Argument(1, "an image file path");
			form.Add(new StreamContent(File.OpenRead(path)), "image", Path.GetFileName(path));
			response = await client.PostAsync("Account/ProfileImage", form);
		}
		break;
	case "view":
		response = await client.PostAsJsonAsync("Account/ProfileView", new {
			username, password, profileId = ProfileId(1) });
		break;
	case "deactivate":
		response = await client.PostAsJsonAsync("Account/Deactivate", credentials);
		break;
	case "activate":
		response = await client.PostAsJsonAsync("Account/Activate", credentials);
		break;
	case "delete-account":
		response = await client.PostAsJsonAsync("Account/Delete", credentials);
		break;
	case "explore":
		// Optional arguments: gender (or 'all'), then the previous page's last ID.
		var query = new List<string>();
		if (args.Length > 1 && args[1] != "all")
			query.Add("gender=" + Uri.EscapeDataString(Argument(1, "a gender")));
		if (args.Length > 2)
			query.Add("afterId=" + ProfileId(2));
		var route = "Match/Explore" + (query.Count == 0 ? "" : "?" + string.Join("&", query));
		response = await client.PostAsJsonAsync(route, credentials);
		break;
	case "requested":
		response = await client.PostAsJsonAsync("Match/Requested", credentials);
		break;
	case "received":
		response = await client.PostAsJsonAsync("Match/Received", credentials);
		break;
	case "like":
		response = await client.PostAsJsonAsync("Match/Like", new {
			username, password, matchedUserId = ProfileId(1) });
		break;
	case "delete-match":
		var direction = Argument(2, "outgoing or received");
		if (direction != "outgoing" && direction != "received")
			throw new ArgumentException("Direction must be outgoing or received.");
		response = await client.PostAsJsonAsync("Match/Delete", new {
			username, password, matchedUserId = ProfileId(1), received = direction == "received" });
		break;
	default:
		throw new ArgumentException("Unknown command; see the commands below.");
}

using (response)
{
	Console.WriteLine($"HTTP {(int)response.StatusCode} {response.ReasonPhrase}");
	var body = await response.Content.ReadAsStringAsync();
	if (!string.IsNullOrEmpty(body)) Console.WriteLine(body);
	response.EnsureSuccessStatusCode();
}

3. Run individual operations

The environment variables must be available to each process. Use a real profile ID returned by Explore or a match list; the GUID below is a placeholder. Quoted arguments preserve spaces in gender names and file paths.

dotnet run -- register
dotnet run -- login
dotnet run -- nickname "Alex"
dotnet run -- gender "Non-binary"
dotnet run -- gender clear
dotnet run -- image "C:\Images\profile.jpg"
dotnet run -- explore
dotnet run -- explore "Woman"
dotnet run -- explore "Woman" 11111111-1111-1111-1111-111111111111
dotnet run -- view 11111111-1111-1111-1111-111111111111
dotnet run -- like 11111111-1111-1111-1111-111111111111
dotnet run -- requested
dotnet run -- received
dotnet run -- delete-match 11111111-1111-1111-1111-111111111111 outgoing
dotnet run -- delete-match 11111111-1111-1111-1111-111111111111 received
dotnet run -- deactivate
dotnet run -- activate
dotnet run -- delete-account

Warning: Like, view, delete-match, deactivate, activate, and delete-account change server data. Run only the operations you intend; deleting the account is irreversible. For pagination, the third Explore argument is the last ID of a full previous page; use all in place of a gender to page without a filter.

Data models

The API returns these public profile fields; it never includes a password.

AccountResponse

username string
email string
nickname string or null
gender string or null
profileImage string or null (image path)
viewCount integer
deactivated boolean

ExploreProfile / MatchProfile

ExploreProfile: id, username, nickname, profileImage. MatchProfile: id, nickname, profileImage, email (available for mutual matches), isMatch.