API v2 Research

How to do this

Use MITMProxy, Fiddler2, Charles Proxy or whatever, install the CA certificate on your phone (Emulator or real Android phone) and make the phone connect through the proxy. Now use Snapchat. Quit SnapChat and take a look at them nice connection logs, every POST or GET request the application has ever made.

Notes

This is not for any malicious use, I just wanted to know what SnapChat does behind the application, and if anyone else is interested then here take a look.

The application makes a lot of requests to Crittercism, it sends off almost every movement performed in the application. Snapchat also has it's own "in house" analytics system, and that posts data every now to find out when you open the app.

I'm assuming you have already read through the GSFD, a great resource for any Snapchat API user.

Request headers

User-Agent : Snapchat/8.1.1 Beta (Android SDK built for x86; Android 19; gzip)
Accept-Language : en
Accept-Local : en_US
Content-Type : application/x-www-form-urlencoded
Host : feelinsonice-hrd.appspot.com
accept-encoding : identity
Content-Length

Response headers

Content-Type : application/json; charset=UTF-8
X-Snapchat-Notice : Snapchat Private APIs - Unauthorized use is prohibited. (Don't laugh please)
Vary : accept-encoding
Date
Server : Google Frontend
Cache-Control : no-cache, no-store or private
Alternate-Protocol : 443:quic,p=0.02
Transfer-Encoding : chunked

/ph/device

Description

Honestly, no idea what it does.

Request

device_token : 162 char long string containing - _
username
type : android is hardcoded into the APK
timestamp
req_token
features_map : {}

Response :

No content.

/loq/register

Description

Used to create a new user.

Request

email
birthday : Format as YYYY-MM-DD
password
age : Bit stupid seeing that you provide your birth date. The application calculates this on it's own (Example : 22)
timestamp
req_token
features_map : {}

Response

email
should_send_text_to_verify_number : Boolean
snapchat_phone_number : +17864088365
auth_token
logged : Boolean

/loq/register_username

Description

Allows a user to associate a username with his / her newly created account.

Request

username : Don't be fooled, this is your email address
selected_username : The username you want to have
timestamp
req_token
features_map : {"all_updates_friends_response":true}

Response

If successful then the response should be the same as/loq/all_updates

/bq/phone_verify - Verification request

Description

Used to request phone verification

Request

countryCode : 2 letter ISO Country code
action : updatePhoneNumberWithCall or updatePhoneNumberWithMessage
phoneNumber
username
timestamp
req_token
features_map : {}

Response

action : confirm
message : We're calling your number now with a verification code.
param : The phone number with country code (Example : +33102030405)
logged : Boolean

/bq/phone_verify - Verification time

Description

Verification of the verification code

Request

action : verifyPhoneNumber
username
code : 6 digit verification code
timestamp
req_token
features_map : {}

Response

allowed_to_use_cash : NON_US_USER
message : Phone number updated!
param : The phone number with country code (Example : +33102030405)
logged : Boolean

/loq/all_updates

Description

This is the greatest endpoint of them all containing most of the information, long and painful to document though...

Request

username
timestamp
req_token
features_map : {"all_updates_friends_response":true}
checksums_dict : This variable can be left empty to receive all updates, or you can provide the following to only receive... the updates. Array
- updates_checksum : 32 character string (MD5)
- friends_checksum : 32 character string (MD5)
- stories_checksum : 32 character string (MD5)
- conversations_checksum : 32 character string (MD5)

Response

background_fetch_secret_key : Base64 encoded "secret key"
conversations_response : Array
- conversation_messages : Array
  - Messages : Array
    - chat_message : Array
      - body : Array
        
        text : The message text
        
        type : text
      - chat_message_id : 36 character string containing -
      - header : Array
        
        conv_id : ToUsername~FromUsername
        
        from : username
        
        to : Array of usernames
      - id : 36 character string containing -
      - seq_num : Order of display in SnapChat (Example : 5)
      - timestamp : (Example : 1419936429914)
      - type : chat_message
    - iter_token : Strange string "{\"FromUsername\":seq_num}~{}. This follows every chat message
    - snap : Array
      - id : 19 character string with 18 digits then s or r like before
      - m : Media type
      - sn : Snap sender (Applicable when the snap is for you)
      - rp : Snap receiver (Applicable when the snap is from you)
      - st : Media state
      - sts : Time sent
      - t : Time viewable in seconds
      - timer : Time viewable in seconds as a float
      - ts : Time last interacted with
  - messaging_auth : Array
    - mac : 44 character string containing _ ending with =
    - payload : 120 character string
- conversation_state : Array
  - user_chat_releases : Array
    - [Username] : Array with friend usernames as key and number of snaps received from that person as value.
  - user_sequences : Array with friend usernames as key and number of snaps received from that person as value.
  - user_snap_releases : Array
    - [Username] : Array
      - [Username] : Timestamp as value
- id : ToUsername~FromUsername
- last_chat_actions : Array
  - last_read_timestamp
  - last_reader
  - last_write_timestamp
  - last_write_type : Media type of last message (Example : text)
  - last_writer : Sender of last message
- last_interaction_ts : Timestamp of the user's last interaction
- last_snap :
  - c_id
  - id : (Example : 1r)
  - m : Media type
  - sn : Sender name (Applicable when the snap is for you)
  - rp : Recipient name (Applicable when the snap is from you)
  - st : Media state
  - sts : Time sent
  - ts : Time of last interaction
  - zipped : Boolean
- participants : Array of participants in the conversation
- pending_chats_for : Array of users who haven't opened the last message
- pending_received_snaps : Array
  - Array
    - id : Snap id
    - m : Media type
    - sn : Sender name (Applicable when the snap is for you)
    - rp : Recipient name (Applicable when the snap is for you)
    - st : Media state
    - sts : Time sent
    - t : Time viewable in seconds
    - timer : Time viewable in seconds, but a float
    - ts : Time of last interaction
conversations_response_info : Array
- is_delta : Boolean
friends_response : Array
- added_friends : Array of friends added (To be continued)
- bests : Array of best friends (To be continued)
- friends : Array
  - Array
    - add_source : ADDED_BY_USERNAME
    - can_see_custom_stories : Boolean
    - direction : OUTGOING or INCOMING
    - display : User display name
    - name : Username
    - type : Friend account privacy setting
messaging_gateway_info : Array
- gateway_auth_token : Array
  - mac : 44 character string containing - ending with =
  - payload : 72 character string ending with =
- gateway_server : Server IP and port (Example : 23.251.149.90:443)
server_info : Array
- response_checksum : Array as a string
  - updates_checksum : 32 character string (MD5)
  - friends_checksum : 32 character string (MD5)
  - stories_checksum : 32 character string (MD5)
  - conversations_checksum : 32 character string (MD5)
- response_compare_result : equal or not_equal
- response_compare_results_dict : Array as a string
  - updates_checksum : equal or not_equal
  - friends_checksum : equal or not_equal
  - stories_checksum : equal or not_equal
  - conversations_checksum : equal or not_equal
- server_latency : Ping result in ms (Example : 39)
stories_response : (This part is pretty empty, haven't tried it with friends yet, gonna leave the house and find some, brb)
- friend_stories : Array (To be continued)
- friend_stories_delta : Boolean
- mature_content_text : Array
  - message : The red exclamation mark on this Story indicates that Stories posted by this user may not be suitable for sensitive viewers. Do you wish to continue? After selecting 'Yes', you will never be prompted again.
  - no_text : No
  - yes_text : Yes
  - title : Content Warning
- my_group_stories : Array (To be continued)
- my_stories : Array (To be continued)
updates_response : Array
- added_friends_timestamp : I suppose it's the last time you added a friend. I don't have any I wouldn't know.
- allowed_to_use_cash : NON_US_USER(Need someone from the US to get us Snapcash details)
- auth_token
- birthday : Kind reminder of your birthday (YYYY-MM-DD)
- blocked_from_using_our_story : Boolean
- can_view_mature_content : Boolean
- cash_customer_id : Username
- cash_provider : SQUARE
- client_properties : Array
  - snapcash_new_tos_accepted : Boolean
  - snapcash_tos_v2_accepted : Boolean
- contacts_resync_request : (Example : 1)
- country_code : ISO 2 letter country code
- current_timestamp : A current UNIX timestamp. Thanks for that.
- device_token : Empty
- email
- enable_video_transcoding_android : Boolean
- feature_settings : Array
  - front_facing_flash : Boolean
  - power_save_mode : Boolean
  - replay_snaps : Boolean
  - smart_filters : Boolean
  - special_text : Boolean
  - swipe_cash_mode : Boolean
  - visual_filters : Boolean
- image_caption : Boolean
- is_cash_active : Boolean
- logged : Boolean
- mobile : Phone number with country code (Example : +33102030405)
- mobile_verification_key : Base64 encoded string with 4 digit code and username (Example : 1234:Username)
- notification_sound_setting : ON or OFF
- number_of_best_friends
- received : Number of received snaps
- recents : Array containing usernames of recently interacted friends
- requests : Array (To be continued)
- score : Your snapchat score
- searchable_by_phone_number : Boolean
- sent : Number of sent snaps
- should_call_to_verify_number : Boolean
- should_send_text_to_verify_number : Boolean
- snap_p : Account privacy setting
- snapchat_phone_number : (Example : +17864088362)
- store_privacy : Story privacy setting
- study_settings : Array
  - DELTA_RESPONSE : Array as a string
    - experimentId : 1
    - CONVERSATIONS_DELTA : on or off
    - FRIENDS_STORY_DELTA : on or off
  - USE_VIDEO_STABILIZATION : Array as a string
    - experimentId : 0
    - option : on or off
- user_id : 36 character string containing -
- username

/ph/upload

Description

Used to upload media to the server

Request

data : Encrypted image data
media_id : Username in capitals and a random media ID
type : Media type
username
req_token
timestamp
features_map : {}

Response

No content.

/loq/send

Description

Used to send media to users

Request

time : Snap countdown timer (Float)
recipients : Array of usernames
media_id : The media id used when uploading the media
zipped : (Example : 0)
username
req_token
timestamp
features_map : {}

Response

snap_response : Array
- snaps : Array
  - [ToUsername] : Array
    - id : The snap's ID
    - timestamp
- success : Boolean

/loq/conversations

Description

Used to check for new conversations

Request

checksum :
offset : [TimestampOfLastMessage]~~ToUsername~~FromUsername
username
req_token
timestamp
features_map : {"all_updates_friends_response":true}

Response

server_info : Array
- response_checksum : 32 character string (MD5)
- response_compare_result : equal or not_equal
- server_latency : Ping time in ms (Example : 39)

/bq/chat_typing

Description

Informs the server and recipient that the user is typing

Request

recipient_usernames : Array of usernames
username
req_token
timestamp
features_map : {}

Response

No content.

/ph/find_friends

Description

Used to find users by phone number

Request

countryCode : ISO 2 letter country code
numbers : Array with display name as key and phone number as value (The official client sends off all numbers at once. Maybe there is no limit ?)
username
req_token
timestamp

Response

logged : Boolean
results : Array
- Array
  - display : Name provided as display name in the request
  - name : Username
  - type : User's privacy setting

/ph/settings

Description

Used to change various settings

Request

action : updatePrivacy or updateEmail or updateStoryPrivacy or updateSearchableByPhoneNumber
privacySetting : Applicable for updatePrivacy or updateStoryPrivacy
searchable : 0 or 1 - Applicable for updateSearchableByPhoneNumber
email : Applicable for updateEmail
username
req_token
timestamp
features_map : {}

Response

logged : Boolean
message : User friendly success / error message
param : The new updated parameter

/bq/set_num_best_friends

Description

Sets the number of best friends to display for your username

Request

num_best_friends : Number from 3 to 7
username
req_token
timestamp
features_map : {}

Response

best_friends : Array of best friend usernames

/bq/update_feature_settings

Description

Used to change extra feature settings

Request

settings : Array
- front_facing_flash : Boolean
- replay_snaps : Boolean
- smart_filters : Boolean
- visual_filters : Boolean
username
req_token
timestamp
features_map : {}

Response

No content.

/ph/logout

Description

Used to push updates and end the user's session

Request

added_friends_timestamp : Time of the last added friend
events : You can post a whole load of events here. But I don't feel like documenting that today.
json : Array of snap updates
username
req_token
timestamp

Response

No content.

/loq/login

Description

Authenticates the user with the server

Request

username
password
access_token : a 675 character string containing . _ -
req_token
timestamp
features_map : {"all_updates_friends_response":true}

Response

Error

logged : Boolean
message : User friendly error message
status : Integer

Success

If successful then the response should be the same as/loq/all_updates

/bq/bests

Description

Gets the best friends and scores of a selection of friends

Request

friend_usernames : Array of friend usernames
username
req_token
timestamp
features_map : {}

Response

Array
- [FriendUsername] : Array
  - best_friends : Array of up to 3 of the user's best friends
  - score : User's score

/loq/conversation_auth_token

Description

Normally called just after adding a user a friend, provides encryptions keys for encrypting / decrypting conversation messages

Request

conversation_id : [YourUsername]~[OtherUsername]
username
req_token
timestamp

Response

messaging_auth
- mac : 44 character string ending with =
- payload : 112 character string

/bq/friend

Description

Used to add / remove / block / unblock / change display name for a friend

Request

action : add or remove or block or unblock or delete or display
friend : Friend's username
display : New display name - Applicable only if action = display
username
req_token
timestamp
features_map : {}

Response

logged : Boolean
message : User friendly error / success message
object : Array
- add_source : How the friend was added
- can_see_custom_stories : Boolean
- direction : INCOMING or OUTGOING
- display : User's display name
- name : Friend's username
- type : Friend account privacy setting

/loq/friend_search

Description

No idea what it does, it always returns an empty array, but it is called on the friend search page of the app.

Request

query : The user you are looking for
username
req_token
timestamp
features_map : {}

Response

result : Array

/bq/user_exists

Description

Used to find user's that aren't in your friend list

Request

request_username : The username you are looking for
username
req_token
timestamp

Response

exists : Boolean

/loq/friend_hide

#### Description Used when hiding shared stories. The kind that are forced into your story list. When you hide a shared story the application also deletes the friend by firing off a request to /bq/friend

Request

friend : Friend's username
hide : Boolean
username
req_token
timestamp

Response

can_see_custom_stories : Boolean
direction : INCOMING or OUTGOING
display : Friend's display name
dont_decay_thumbnail : Boolean
expiration : The time when the shared story should dissapear from your client
has_custom_description : Boolean
is_shared_story : Boolean
name : Friend's username
shared_story_id : Should be the same as name
type : Friend's privacy setting
venue : Location of shared story event

/shared/description

Description

Called for every shared story in the story view to provide a description to the user

Request

shared_id : The shared story's id
username
req_token
timestamp
features_map : {}

Response

Haven't seen a shared story with a description yet.

/bq/update_stories

Description

Whenever a story is viewed by the user the application notifies the server of the view, the time of viewing and the amount of screenshots taken. This endpoint can accept a whole load of different viewed snaps at once.

Request

friend_stories : Array
- Array
  - id : Story snap id
  - screenshot-count : Integer
  - timestamp : Time viewed
username
req_token
timestamp
features_map : {}

Response

No content.

/bq/retry_post_story

Description

This is used by default on the Android application when posting a new story, even though it was originally meant to be used in case of failure, it's an all in one endpoint for uploading and posting the story.

Request

my_story : Boolean
time : Number of seconds to display the snap. Float
group_ids : Array (Don't know how to get in a group yet...)
data : The snap data
media_id : [Username]~[Random 36 character string containing -]
story_timestamp : No idea, I had 245388641
zipped : 0 or 1
caption_text_display : The title to be displayed when viewing a list of your snaps.
client_id : Same as media_id for me
type : Type of media (0 for images - 1 for videos)
username
req_token
timestamp

Response

json : Array
- story : Array
  - caption_text_display
  - client_id
  - id : [Username]~[Timestamp]
  - mature_content : Boolean
  - media_id : 16 digit Media ID
  - media_iv : Base64 encoded encryption IV for the snap data
  - media_key : Base64 encoded decryption key for the snap data
  - media_type : 0 for images - 1 for videos
  - media_url : A URL to fetch the story data, generally https://feelinsonice-hrd.appspot.com/bq/story_blob?story_id=[media_id]
  - thumbnail_iv : Base64 encoded encryption IV for the thumbnail image
  - thumbnail_url : A URL to fetch the thumbnail image, generally https://feelinsonice-hrd.appspot.com/bq/story_thumbnail?story_id=[media_id]
  - time : Number of seconds to display snap. Float
  - time_left : Time left before expiration of the story in ms
  - timestamp : Time posted in ms
  - username : Username of the user who posted the story
  - zipped : Boolean

/cash/check_recipient_eligible

Description

Used to check if a recipient is eligible to use the Snapcash service. It is called in the application when viewing a conversation with a friend.

Request

recipient : Friend's username
username
req_token
timestamp

Response

status : The Snapcash status for the specified user. (Example : SERVICE_NOT_AVAILABLE_TO_RECIPIENT)

/bq/delete_story

Description

Allows a user to delete a snap from their story

#### Request

story_id : [Username]~[Timestamp]
username
req_token
timestamp

Response

No content.