Tinder API Documentation - 2018

First off, I want to give a shoutout to @rtt who initially posted the Tinder API Documentation that I found most of these endpoints on. I am writing this to provide a more up-to-date resource for working with the Tinder API.

Note: This was updated in June 2018 so it might be outdated.

API Details

Host	api.gotinder.com
Protocol	SSL

Required Headers

Header	Example	Notes
X-Auth-Token	See "How to get facebook_token" below
Content-type	application/json	Shouldn't be sent to `/like/_id` nor `/pass/_id` (#63)
User-agent	Tinder/7.5.3 (iPhone; iOS 10.3.2; Scale/2.00)

Known Endpoints

Note: All endpoints are concatenated to the host url

Note: All curls must be sent with the headers as well (the only exception is that the /auth call must not have the X-Auth-Token header)

Endpoint	Purpose	Data?	Method
/auth	For authenticating	{'facebook_token': INSERT_HERE, 'facebook_id': INSERT_HERE}	POST
/v2/auth/sms/send?auth_type=sms	Part 1 of SMS authentication (two-factor)	{'phone_number': string}	POST
/v2/auth/sms/validate?auth_type=sms	Part 2 of SMS authentication (two-factor)	{'otp_code': string, 'phone_number': string }	POST
/v2/auth/login/sms	Part 3 of SMS authentication (two-factor)	{'refresh_token': string}	POST
/user/recs	Get match recommendations	{}	GET
/v2/matches	Get your matches	query in link should have count=1-100 e.g: /v2/matches?count=50	GET
/user/matches/_id	Send Message to that id	{"message": TEXT GOES HERE}	POST
/user/matches/match_id	Unmatch person	{}	DELETE
/user/_id	Get a user's profile data	{}	GET
/user/ping	Change your location	{"lat": lat, "lon": lon}	POST
/updates	Get all updates since the given date -- inserting "" will give you all updates since creating a Tinder account (i.e. matches, messages sent, etc.)	{"last_activity_date": ""} Input a timestamp: '2017-03-25T20:58:00.404Z' for updates since that time.	POST
/profile	Get your own profile data	{}	GET
/profile	Change your search preferences	{"age_filter_min": age_filter_min, "gender_filter": gender_filter, "gender": gender, "age_filter_max": age_filter_max, "distance_filter": distance_filter}	POST
/profile	(Tinder Plus Only) hide/show age	{"hide_age":boolean}	POST
/profile	(Tinder Plus Only) hide/show distance	{"hide_distance":boolean}	POST
/profile	(Tinder Plus Only) hide/show ads	{"hide_ads":boolean}	POST
/profile	(Tinder Plus Only) Set Tinder Blend options to "Recent Activity": Shows more recently active users	{"blend":"recency"}	POST
/profile	(Tinder Plus Only) Set Tinder Blend options to "Optimal": Scientifically proven to get you more matches	{"blend":"optimal"}	POST
/profile	(Tinder Plus Only) Set discovery settings to only people who already liked you	{"discoverable_party":"liked"}	POST
/passport/user/travel	(Tinder Plus Only) Travel to coordinate	{"lat":lat,"lon":lon}	POST
/v1/activity/feed?direction=past&eventTypes=1023	Get activity feed, including old and updated bios for comparison	{}	GET
/instagram/authorize	Auth Instagram	{}	GET
/v2/profile/spotify/	Get Spotify settings	{}	GET
/v2/profile/spotify/theme	Set Spotify song	{"id":song_id}	PUT
/profile/username	Change your webprofile username	{"username": username}	PUT
/profile/username	Reset your webprofile username	{}	DELETE
/meta	Get your own meta data (swipes left, people seen, etc..)	{}	GET
/v2/meta	Get your own meta data from V2 API (extra data like "top_picks" info)	{}	GET
/report/_id	Report someone --> There are only a few accepted causes... (see tinder_api.py for options)	{"cause": cause, "text": explanation}	POST
/like/_id	Like someone a.k.a swipe right	{}	GET
/pass/_id	Pass on someone a.k.a swipe left	{}	GET
/like/_id/super	~Super Like~ someone a.k.a swipe up	{}	POST
/matches/{match id}	Get a match from its id (thanks @jtabet )	{}	GET
/message/{message id}	Get a message from its id (thanks @jtabet )	{}	GET
/passport/user/reset	Reset your location to your real location	{}	POST
/passport/user/travel	Change your swiping location	{"lat": latitutde, "lon": longitude}	POST
/user/{user_id}/common_connections	Get common connection of a user	{}	GET
/profile/job	Set job	{"company":{"id":"17767109610","name":"University of Miami","displayed":true},"title":{"id":"106123522751852","name":"Research Assistant","displayed":true}}	PUT
/profile/job	Delete job	{}	DELETE
/profile/school	Set school(s)	{"schools":[{"id":school_id}]}	PUT
/profile/school	Reset school	{}	DELETE
/message/{message_id}/like	Like a message	{}	POST
/v2/fast-match/preview	Get the non blurred thumbnail image shown in the messages-window (the one showing the likes you received)	{}	GET
/v2/fast-match/count	Get the number of likes you received	{}	GET
/giphy/trending?limit={limit}	Get the trending gifs (tinder uses giphy) accessible in chat	{}	GET
/giphy/search?limit={limit}&query={query}	Get gifs (tinder uses giphy) based on a search accessible in chat	{}	GET

Status Codes

Status Code	Explanation
200	Everything went okay, and returned a result (if any).
301	The server is redirecting you to a different endpoint. This can happen when a company switches domain names, or an endpoint's name has changed.
400	The server thinks you made a bad request. This can happen when you don't send the information the API requires to process your request, among other things.
401	The server thinks you're not authenticated. This happens when you don't send the right credentials to access an API
404	The server didn't find the resource you tried to access.
503	Back-end server is at capacity.

Config File

facebook_access_token and fb_user_id

Simply input your facebook username/email and password in your config file. Then, the fb_auth_token.py module will programmatically retrieve your facebook_access_token and fb_user_id. These are then used to generate your tinder_auth_token in tinder_api.py which grants you access to your data! Happy Swiping!

SMS Authentication (implemented by @Tagge)

SMS authentication is even easier. Just run phone_auth_token.py . You'll be asked your phone number at runtime, you'll then have to type in the code you received by SMS, and it will return your token. We didn't directly implement it in the tinder_api.py because, as opposed to Facebook auth, there's a rate limit to the number of SMS you can receive in an hour (actually 60). It's therefore better to get your token once and use it within its lifetime (24 hours) rather than asking for a new one everytime.
With your token ready, add it to tinder_config_ex.py (value for tinder_token). You're now ready to roll !

Note: With the help of philliperemy , I have included a programatic way to acquire your facebook_token. Now, in your config.py just input your facebook username and password.

Note: With the help of gloriamacia , we added now a jupyter notebook to make the usage even simpler.

Key Features

Match_Info:

Creates a local dictionary containing the following keys on each of your matches

{
	  123456: {
	    'messages': [

	    ],
	    'age': 20,
	    'match_id': '123456789123456789',
	    'name': 'Joakim',
	    'photos': [
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg'
	    ],
	    'message_count': 0,
	    'last_activity_date': '15 days, 16 hrs 46 min 57 sec',
	    'ping_time': '2017-03-11T04:58:56.433Z',
	    'gender': 1,
	    'bio': 'New York Knicks Center',
	    'avg_successRate': 0
	  },
	  56789: {
	    ...
	  }
}

Sorting:

Sorting matches by "age", "message_count", and "gender"

[
	  ('123456789123456789',
	  {
	    'messages': [

	    ],
	    'age': 19,
	    'match_id': '123456789123456789abcdefghi',
	    'name': 'Carmelo',
	    'photos': [
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg',
	      'http://images.gotinder.com/123456789123456789.jpg'
	    ],
	    'message_count': 0,
	    'last_activity_date': '0 days, 22 hrs 23 min 45 sec',
	    'ping_time': '2017-03-25T23:22:08.954Z',
	    'gender': 1,
	    'bio': 'I do not like to win sometimes', 'avg_successRate': 0.7837966008217391
	    }
	    )
]

The following is no longer available due to Tinder setting their ping_time to a constant date in 2014 and/or the removal of Tinder Social.

```

Friends' Pingtimes:

friends_pingtimes() will return the following for each facebook friend of yours who has a Tinder friend_pingtime_by_name("Joakim Noah") will return the pingtime for only that particular friend. The following is a sample result for friends_pingtimes():

"Joakim Noah -----> 15 days, 16 hrs 46 min 57 sec" "Carmelo Anthony ------> 0 days, 22 hrs 23 min 45 sec" ...

Facebook Friends:

Given a name, it returns some profile information and their id. Once you have the ID, then you can call api.get_person(id) to get more in-depth information on your friends.

{
	  'Martin Shkreli': {
	    'photo': [
	      {
	        'processedFiles': [
	          {
	            'url': 'https://graph.facebook.com/123456789/picture?height=84&width=84',
	            'height': 84,
	            'width': 84
	          },
	          {
	            'url': 'https://graph.facebook.com/123456789/picture?height=172&width=172',
	            'height': 172,
	            'width': 172
	          },
	          {
	            'url': 'https://graph.facebook.com/123456789/picture?height=320&width=320',
	            'height': 320,
	            'width': 320
	          },
	          {
	            'url': 'https://graph.facebook.com/123456789/picture?height=640&width=640',
	            'height': 640,
	            'width': 640
	          }
	        ]
	      }
	    ],
	    'in_squad': True,
	    'name': 'Martin Shkreli',
	    'user_id': '582bf320452u3yy1217f8'
	  }
}