Contact1.0

Add

Description : Adds a new contact, updates an existing contact, or imports/syncs a third-party contact to the current session user's contact list.

Required Parameters

• session_token : A type 1 or type 2 session token. (Type 2 will require a call signature).

• signature : This is the call signature that is required to authenticate a type 2 session token transaction.
• contact_type : Indicates the contact type to be added ("mediafire", "facebook", "gmail", "twitter"...). If not set, then it will be left blank.
• contact_key : Specifies an existing contact. If provided, the specified contact details will be added to this contact. If unset, then a new contact will be created.
• display_name : The display name of the contact to be added.
• first_name : The first name of the contact to be added.
• last_name : The last name of the contact to be added.
• avatar : The URL to the picture/icon of the contact.
• source_uid : The user ID (MediaFire, Facebook, Twitter...) of the contact to be added.
• email : The email address of the contact to be added.
• phone : The phone number (xxx-xxx-xxxx) of the contact to be added.
• birthdate : The date of birth (yyyy-mm-dd) of the contact to be added.
• location : The location (city, state, country) of the contact to be added.
• gender : The gender of the contact to be added. 1 = female, 2 = male.
• website : The URL of the contact's website.
• response_format : 'xml' or 'json' (default 'xml')

Example:

http://www.mediafire.com/api/1.0/contact/add.php?session_token=749e4610d9e719620a1e9347ca9aabe5f86ac58d67c8bdd85f0eb4e043624ac70ec1a3f88dd49bb8126ad4c38a7686665ec66d727207ac1a99e9dc6c5cdf0772da405c3464c2d2af&contact_type=mediafire&display_name=TEST4&email=test4@gmail.com
                        

<response>
  <action>contact/add</action>
  <result>Success</result>
  <current_api_version>1.0</current_api_version>
</response>
    

Delete

Description : Delete a contact from the current session user's contact list.

Required Parameters

• session_token : A type 1 or type 2 session token. (Type 2 will require a call signature).
• contact_key : The key of the contact to be added.

• signature : This is the call signature that is required to authenticate a type 2 session token transaction.
• response_format : 'xml' or 'json' (default 'xml')

Example:

http://dev.mediafire.com/api/1.0/contact/delete.php?session_token=749e4610d9e719620a1e9347ca9aabe5f86ac58d67c8bdd85f0eb4e043624ac70ec1a3f88dd49bb8126ad4c38a7686665ec66d727207ac1a99e9dc6c5cdf0772da405c3464c2d2af&contact_id=605
                            
                        

<response>
  <action>contact/delete</action>
  <result>Success</result>
  <current_api_version>1.0</current_api_version>
</response>

Fetch

Description : Returns the contact list (contactkey, display name, first name, last name, avatar, email, phone, means_of_contact, birthdate, location, gender, website, created date, & contact type), revision, and count of the current session user. If method = "autocomplete", the contact list is returned as a trie (radix tree) structure. It is faster to traverse the trie branches using contact names and emails to find contacts. The trie is saved can be returned "raw" or in a "succinct" format. The response will contain the trie (base-64 encoded), the directory (base-64 encoded), and the number of nodes.

Required Parameters

• session_token : A type 1 or type 2 session token. (Type 2 will require a call signature).

• signature : This is the call signature that is required to authenticate a type 2 session token transaction.
• method : The method of getting the contact list. "normal" or "autocomplete" (default "normal"). If this is passed, group_contacts, start, and limit are ignored. "autocomplete" will return a succinct trie by default.
• contact_key : A single contact key or a comma-separated list. When the 'method' is 'normal', only data for these contacts will be returned.
• group_contacts : Specifies whether to return contacts separated into their contact groups. "yes" or "no" (default = "no").
• start : The number of contacts to skip (default = 0).
• limit : The maximum number of contacts to be returned (default = "all").
• If limit = 0: or is not provided, it will return all contacts beyond start.
• Otherwise, it will return at most the number of contacts specified.
• raw : Specifies whether the trie data should be returned in its original (non-succinct) form. "yes" or "no" (default = "no").
• response_format : 'xml' or 'json' (default 'xml')

Example 1:

http://www.mediafire.com/api/1.0/contact/fetch.php?session_token=749e4610d9e719620a1e9347ca9aabe5f86ac58d67c8bdd85f0eb4e043624ac70ec1a3f88dd49bb8126ad4c38a7686665ec66d727207ac1a99e9dc6c5cdf0772da405c3464c2d2af
                        

<response>
  <action>contact/fetch</action>
  <contacts>
  <contact>
    <contact_key>gytu8fz</contact_key>
    <display_name>Cliff Jones</display_name>
    <first_name>Cliff</first_name>
    <last_name>Jones</last_name>
    <avatar></avatar>
    <email>cliffjones@example.com</email>
    <phone></phone>
    <means_of_contact>cliffjones@example.com</means_of_contact>
    <birthdate>1982-11-20</birthdate>
    <location>Houston, Texas</location>
    <gender>2</gender>
    <website></website>
    <created>2013-08-15 10:54:17</created>
    <contact_type>mediafire</contact_type>
  </contact>
  <contact>
    <contact_key>3iprdm5</contact_key>
    <display_name>TEST 2</display_name>
    <first_name></first_name>
    <last_name></last_name>
    <avatar>https://secure.gravatar.com/avatar/00000000?s=27&d=mm&f=y</avatar>
    <email>test2@mailinator.com</email>
    <phone></phone>
    <means_of_contact>cliffjones@example.com</means_of_contact>
    <birthdate></birthdate>
    <location></location>
    <gender>1</gender>
    <website></website>
    <created>2013-08-20 13:55:11</created>
        <contact_type>user</contact_type>
  </contact>
  <contact>
    <contact_key>wdpiatu</contact_key>
    <display_name>TEST 3</display_name>
    <first_name></first_name>
    <last_name></last_name>
    <avatar>http://i.imgur.com/4WG0oev.jpg</avatar>
    <email>test3@mailinator.com</email>
    <phone></phone>
    <means_of_contact>test3@mailinator.com</means_of_contact>
    <birthdate></birthdate>
    <location></location>
    <gender>2</gender>
    <website></website>
    <created>2013-08-20 13:51:10</created>
    <contact_type>user</contact_type>
  </contact>
  </contacts>
  <count>16</count>
  <revision>1</revision>
  <epoch>1377029721</epoch>
  <result>Success</result>
  <current_api_version>1.0</current_api_version>
</response>
                        

Example 2 (Succinct auto-complete trie):

http://www.mediafire.com/api/1.0/contact/fetch.php?session_token=0a7ae1b77061da54796078b3906b7a7bab9747dc6e7848876674eca0055821c85196e164f1fa1d17cfcf9b2dea8268b42b920b3b7948f4de4cbab9c716bcb827267e3f3a6341dc60&method=autocomplete
                        

<response>
  <action>contact/fetch</action>
  <contact_trie>
  <node_count>32</node_count>
  <nodes>IGpzb21oaW50QHNobW1laS50Y2hvQG1nbWFpbC5jb20=</nodes>
  <directory>Sm9obiBTbWl0aC8xODQvMSM3LDExfEpvaG4gU21pdGgvMTg0LzIjNywxMXxqb2huQG1lLmNvbS8xODQvMSMyMnxqb2huc21pdGhAZ21haWwuY29tLzE4NC8yIzMx</directory>
  <trie>tVVqlVVUqqo</trie>
  </contact_trie>
  <result>Success</result>
  <current_api_version>1.0</current_api_version>
</response>
                        

To decode and use the above trie, follow these steps:

• Convert the trie into a binary string. The above Trie "tVVqlVVUqqo" would be converted to "101101010101010101101010100101010101010101010100101010101010101000". The string should always have as many 1s as the number of nodes and as many 0s as the number of nodes + 1.
• Based on the binary string, we build the tree from top to bottom and from left to right and we number the nodes starting from 0 to 31. Those numbers would be the indexes. Each bit value of 1 indicates that there is a child, and the bit value of 0 indicates the end of the children list for the node. See the graph below.
• Decode the directory string to get the list of characters corresponding to the nodes. The above string "IGpzb21oaW50QHNobW1laS50Y2hvQG1nbWFpbC5jb20=" decodes to "jsomhint@shmmei.tcho@mgmail.com". That means node 0 has no letter, node 1 has the letter "j", node 2 has the letter "s", and so no. See the graph below.
• Next, decode the data. Contacts are separated by a pipe ("|"), and each contact is composed of two strings separated by a hash ("#"). The first string is itself a list of details separated by slashes ("/"): the contact name/email, the contact ID, a handle to display, the URL of an avatar, and the contact type. The second string is a comma-separated list of node indexes for that contact. The above directory value "Sm9obiBTbWl0aC8xODQvSm9obi9odHRwOiUyRiUyRmkuaW1ndXIuY29tJTJGNFdHMG9ldi5qcGcvMSM3...YWlsLmNvbS8xODQvSm9obi9odHRwOiUyRiUyRmkuaW1ndXIuY29tJTJGNFdHMG9ldi5qcGcvMiMzMQ==" becomes: "John Smith/184/John/http:%2F%2Fi.imgur.com%2F4WG0oev.jpg/1#7,11|John Smith/184/john@example.com/https:%2F%2Fdev.mediafire.com%2Fimages%2Ficons%2Fmyfiles%2Fdefault.png/2#7,11|john@me.com/184/John/http:%2F%2Fi.imgur.com%2F4WG0oev.jpg/1#22|johnsmith@gmail.com/184/John/http:%2F%2Fi.imgur.com%2F4WG0oev.jpg/2#31". The first contact "John Smith" has an ID of "184", "John" as a handle, an avatar URL of "http://i.imgur.com/4WG0oev.jpg" (with slashes restored), and a contact type of 1, which indicates a MediaFire contact. This contact is under the leaf nodes with indexes 7 and 11.

Example 3 (Another succinct auto-complete trie):

http://www.mediafire.com/api/1.0/contact/fetch.php?session_token=0a7ae1b77061da54796078b3906b7a7bab9747dc6e7848876674eca0055821c85196e164f1fa1d17cfcf9b2dea8268b42b920b3b7948f4de4cbab9c716bcb827267e3f3a6341dc60&method=autocomplete
                        

<response>
   <action>contact/fetch</action>
   <node_count>33</node_count>
   <directory>IG1zb3RtZUB2ZWV4QGFlbXhwYWxtZXAubGNlby5tY29t</directory>
   <data>bW9tQGV4YW1wbGUuY29tL2h6emwxaXEvbW9tQGV4YW1wbGUuY29tL2h0dHBzOiUyRiUyRmRldi5tZWRpYWZpcmUuY29tJTJGaW1hZ2VzJTJGaWNvbnMlMkZteWZpbGVzJTJGZGVmYXVsdC5wbmcvMCMyOXxzdGV2ZUBleGFtcGxlLmNvbS9mODczZzV6L3N0ZXZlQGV4YW1wbGUuY29tL2h0dHBzOiUyRiUyRmRldi5tZWRpYWZpcmUuY29tJTJGaW1hZ2VzJTJGaWNvbnMlMkZteWZpbGVzJTJGZGVmYXVsdC5wbmcvMCMzMg==</data>
   <trie>tVVVVVVVVVK</trie>
   <revision>3</revision>
   <epoch>1394066927</epoch>
   <result>Success</result>
   <current_api_version>1.0</current_api_version>
</response>
                        

Example 4 (The same trie in raw form):

http://www.mediafire.com/api/1.0/contact/fetch.php?session_token=0a7ae1b77061da54796078b3906b7a7bab9747dc6e7848876674eca0055821c85196e164f1fa1d17cfcf9b2dea8268b42b920b3b7948f4de4cbab9c716bcb827267e3f3a6341dc60&method=autocomplete&raw=yes
                        

<response>
   <action>contact/fetch</action>
   <node_count>33</node_count>
   <directory>IG1zb3RtZUB2ZWV4QGFlbXhwYWxtZXAubGNlby5tY29t</directory>
   <data>bW9tQGV4YW1wbGUuY29tL2h6emwxaXEvbW9tQGV4YW1wbGUuY29tL2h0dHBzOiUyRiUyRmRldi5tZWRpYWZpcmUuY29tJTJGaW1hZ2VzJTJGaWNvbnMlMkZteWZpbGVzJTJGZGVmYXVsdC5wbmcvMCMyOXxzdGV2ZUBleGFtcGxlLmNvbS9mODczZzV6L3N0ZXZlQGV4YW1wbGUuY29tL2h0dHBzOiUyRiUyRmRldi5tZWRpYWZpcmUuY29tJTJGaW1hZ2VzJTJGaWNvbnMlMkZteWZpbGVzJTJGZGVmYXVsdC5wbmcvMCMzMg==</data>
   <revision>3</revision>
   <epoch>1394066927</epoch>
   <result>Success</result>
   <current_api_version>1.0</current_api_version>
</response>
                        

The above base-64 strings decode as follows:

• directory: {"root":{"m":{"o":{"m":{"@":{"e":{"x":{"a":{"m":{"p":{"l":{"e":{".":{"c":{"o":{"m":{"end":[0]}}}}}}}}}}}}}}},"s":{"t":{"e":{"v":{"e":{"@":{"e":{"x":{"a":{"m":{"p":{"l":{"e":{".":{"c":{"o":{"m":{"end":[1]}}}}}}}}}}}}}}}}}}}
• data: mom@example.com/hzzl1iq/mom@example.com/https:%2F%2Fdev.mediafire.com%2Fimages%2Ficons%2Fmyfiles%2Fdefault.png/0|steve@example.com/f873g5z/steve@example.com/https:%2F%2Fdev.mediafire.com%2Fimages%2Ficons%2Fmyfiles%2Fdefault.png/0

Get Avatar

Description: Returns the URL of a given contact's avatar image.

Required Parameters:

• session_token : A type 1 or type 2 session token. (Type 2 will require a call signature).
• contact_key : The unique key of the contact whose avatar is to be returned.

• signature : This is the call signature that is required to authenticate a type 2 session token transaction.
• response_format : 'xml' or 'json' (default 'xml')

Example

http://www.mediafire.com/api/1.0/contact/get_avatar.php?contact_key=h3qxc97&session_token=e6829fe5892012154097c19ed0635741a6269cbe5dec2a5ae600b2d70e64b45afd03e00cd15ca0d8d17c2348933894db1ef00dda21bd098d6ba1f51f5e82f7a1a28b454f1bd399ae
                

<response>
  <action>contact/get_avatar</action>
  <avatar>
        http://www.mediafire.com/convkey/f8a8/0qhafc7qbmlw4dy0g.jpg
  </avatar>
  <result>Success</result>
  <current_api_version>1.0</current_api_version>
</response>
                    

Set Avatar

Description: Save a copy of a given contact's remote avatar image for use in the operating user's list.

Required Parameters:

• session_token : A type 1 or type 2 session token. (Type 2 will require a call signature).
• contact_key : The unique key of the contact whose avatar is to be returned.
• url : The URL where this image file is located.

• signature : This is the call signature that is required to authenticate a type 2 session token transaction.
• response_format : 'xml' or 'json' (default 'xml')

Example:

http://www.mediafire.com/api/1.0/contact/set_avatar.php?contact_key=h3qxc97&url=https://si0.twimg.com/profile_images/103344356/JG-0511e2.jpg&session_token=e6829fe5892012154097c19ed0635741a6269cbe5dec2a5ae600b2d70e64b45afd03e00cd15ca0d8d17c2348933894db1ef00dda21bd098d6ba1f51f5e82f7a1a28b454f1bd399ae
                        

<response>
  <action>contact/set_avatar</action>
  <upload_key>kt2qzd93wq</upload_key>
  <result>Success</result>
  <current_api_version>1.0</current_api_version>
</response>