Start: swipe app
For an app where a person opens one profile, likes or skips it, and continues through the deck. A site with filters and pages of profiles is a different start: search site.
The API key lives only on your server. The app talks to your server, and the server talks to https://api.pereval.dating.
What to store
| Field | Why |
|---|---|
network_id |
returned by PUT /v1/members/{your id} |
match_id |
a conversation with someone from the network, from match.created |
next_after |
if you pull events yourself instead of using a webhook |
external_id in requests is your user’s id, a string.
Consent and profile
A “Show me in the Pereval network” toggle, off by default, with a link to pereval.dating beside it. Consent texts are in Members and consent. Turned on or the profile changed — PUT /v1/members/{your id}. Turned off — the same PUT with consent.network: false. Erased from the network or the account deleted — DELETE /v1/members/{your id}.
Do not request the network feed until the person has turned participation on.
The deck
curl "https://api.pereval.dating/v1/members/user-123/feed?limit=20" \
-H "Authorization: Bearer $PEREVAL_API_KEY"Mark the profile as coming from the Pereval network. If bio_translated is set, add an “AI-translated” label and the original from bio_original. If the card has videos, play url and show poster until then. Clips start silent; one switch turns sound on for all of them, not a control on each clip. An app that does not play video shows poster as another photo.
A skip without a like is a dislike. The profile stays hidden for 30 days:
curl -X POST https://api.pereval.dating/v1/dislikes \
-H "Authorization: Bearer $PEREVAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from": "user-123", "to": "<network_id>"}'The next feed request without a cursor returns the same people who have not been liked or disliked yet. To take the next batch without marking a skip, pass cursor from next_cursor. For a swipe deck the usual path is a dislike on skip.
One person sees at most 200 new people from the network a day. The remainder is remaining_today. Showing the same profiles again does not decrease it.
Like and chat
POST /v1/likes with from set to your id and to set to network_id. A response of matched: true includes match_id immediately. Otherwise the match arrives as match.created when the other person likes back.
A message is POST /v1/matches/{match_id}/messages. Events (like.received, match.created, message.created) arrive by webhook, or you pull them with GET /v1/events. Signature and duplicates are in Events and webhooks.
There is no message without a mutual like.
Done when
- The key is only on the server, and participation is off by default.
- The profile is sent when participation is turned on and when it is edited, hidden when it is turned off, and erased when it is deleted.
- The deck contains people from other apps, and the card says where they are from.
- A skip is a dislike, a like is
POST /v1/likes, and a match opens a chat. - Events are not applied twice: the webhook checks the signature over the raw body, or you store
next_after. - A translated bio is labeled, and the original can be opened.
Optional after that: super like, Worldwide, photo verification. Those are in feed and matches and members. Before the live key, use the test environment.