Contact1.3

Add


GET http://www.mediafire.com/api/1.3/contact/add.php
POST http://www.mediafire.com/api/1.3/contact/add.php

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:


Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • response_format : 'xml' or 'json' (default 'xml')
  • 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. **IMPORTANT NOTE** 'source_uid' MUST BE SUPPLIED IF USING A CONTACTKEY.
  • 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')

Response Properties

Name Description Type Values
contact_keys The contact key(s) of the added (or updated) contact(s) comma-delimited list
result Indicates if the API call was successful: 'Success' or 'Error' string
new_key For session token version 2, indicates whether the secret key has changed on the back end. 'no' (default) or 'yes'. Returned only to indicate a key change. yes/no flag
current_api_version The latest stable API version number string

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:

Request
http://www.mediafire.com/api/1.3/contact/add.php?session_token=749e4610d9e719620a1e9347ca9aabe5f86ac58d67c8bdd85f0eb4e043624ac70ec1a3f88dd49bb8126ad4c38a7686665ec66d727207ac1a99e9dc6c5cdf0772da405c3464c2d2af&contact_type=mediafire&display_name=TEST4&email=test4@gmail.com
                        
Response
<response>
  <action>contact/add</action>
  <result>Success</result>
  <current_api_version>1.3</current_api_version>
</response>
JSON Example
Request
http://www.mediafire.com/api/contact/add.php?contact_type=mediafire&display_name=TEST4&email=test4@gmail.com&session_token=749e4610d9e719620a1e9347ca9aabe5f86ac58d67c8bdd85f0eb4e043624ac70ec1a3f88dd49bb8126ad4c38a7686665ec66d727207ac1a99e9dc6c5cdf0772da405c3464c2d2af&response_format=json

                        
Response
{
  "response": {
    "action": "contact/add",
    "result": "Success",
    "current_api_version": "1.3"
  }
}

Delete


GET http://www.mediafire.com/api/1.3/contact/fetch.php
POST http://www.mediafire.com/api/1.3/contact/fetch.php

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

Required Parameters:


Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • response_format : 'xml' or 'json' (default 'xml')

Response Properties

Name Description Type Values
deprecated Indicates this API is deprecated and should no longer be used. string yes
error The numerical error code integer 128, 138
message The description of the error string
result Indicates if the API call was successful: 'Success' or 'Error' string Success, Error
current_api_version The latest stable API version number string
new_key Indicates a new call signature needs to be calculated. Applicable only when using Session Token v2 string yes

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples


Example 1: (Success with JSON)
Request
HTTPS://www.mediafire.com/api/contact/delete.php?session_token=&contact_key=8928dog&response_format=json&signature=
                            
                        
Response
{
   action: contact/delete,
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}
Example 2: (Failure with XML - Error 138)
Request
HTTPS://www.mediafire.com/api/contact/delete.php?session_token=&contact_key=8928dog&response_format=xml&signature=
Response
<action>contact/delete</action>
<message>This contact does not exist</message>
<error>138</error>
<result>Error</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>

Fetch


GET http://www.mediafire.com/api/1.3/contact/fetch.php
POST http://www.mediafire.com/api/1.3/contact/fetch.php

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:


Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • 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 return. If not passed or limit=0, all contacts are returned beyond start. Ignored if method is passed.
  • 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')


Response Properties

Name Description Type Values
contact_groups [DEPRECATED] list
contact_key The identifier for the contact string
display_name The contact's display name string
first_name The contact's first name string
last_name The contact's last name string
avatar The contact's URL location of their avatar string
email The contact's email address string
phone The contact's phone number string
source_uid The contact's ID in the service the contact information was obtained from string
birthdate The contact's birth date string
location The contact's location string
gender A list containing information for each contact list of objects
website The contact's website string
options NOT IN USE bitmask
created The date and time the contact was created string timestamp
contact_type The contact's type string MediaFire, Facebook, Gmail, Twitter, Tumblr
gender The contact's gender list of objects
count The amount of contacts in the user's account integer
node_count
data
directory
trie
revision The revision number of the contact list integer
deprecated Indicates this API is deprecated and should no longer be used. string yes
error The numerical error code integer
message The description of the error string
result Indicates if the API call was successful: 'Success' or 'Error' string Success, Error
current_api_version The latest stable API version number string
new_key Indicates a new call signature needs to be calculated. Applicable only when using Session Token v2 string yes

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:

Example 1 (Success with XML - method=normal):
Request
HTTPS://www.mediafire.com/api/contact/fetch.php?session_token=&method=normal&response_format=xml&signature=
                        
Response
<action>contact/fetch</action>
<contact_groups></contact_groups>
<contacts>
   <contact>
      <contact_key>kz8j1r3</contact_key>
      <display_name>Bill Holden</display_name>
      <first_name>Bill</first_name>
      <last_name>Holden</last_name>
      <avatar>https://dev.mediafire.com/images/icons/myfiles/default.png</avatar>
      <email>billh@test.com</email>
      <phone>123-456-7890</phone>
      <source_uid></source_uid>
      <birthdate>1990-01-01</birthdate>
      <location>Somewhere, UT, US</location>
      <gender>male</gender>
      <website></website>
      <options>0</options>
      <created>2015-01-29 17:46:45</created>
      <contact_type>user</contact_type>
   </contact>
   <contact>
      <contact_key>4c4mmb4</contact_key>
      <display_name>Test 02</display_name>
      <first_name>Test</first_name>
      <last_name>02</last_name>
      <avatar>http://www.mediafire.com/images/icons/myfiles/default.png</avatar>
      <email>t02@g.n</email>
      <phone></phone>
      <source_uid>t02@g.n</source_uid>
      <birthdate>0000-00-00</birthdate>
      <location></location>
      <gender>none</gender>
      <website></website>
      <options>1</options>
      <created>2014-10-16 18:23:33</created>
      <contact_type>mediafire</contact_type>
   </contact>
</contacts>
<count>2</count>
<revision>3</revision>
<epoch>1422545796</epoch>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>
                        

Get Avatar


GET http://www.mediafire.com/api/1.3/contact/get_avatar.php
POST http://www.mediafire.com/api/1.3/contact/get_avatar.php

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

Required Parameters:


Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • response_format : 'xml' or 'json' (default 'xml')


Response Properties

Name Description Type Values
avatar Indicates the URL of the avatar string
deprecated Indicates this API is deprecated and should no longer be used. string yes
error The numerical error code integer 230
message The description of the error string
result Indicates if the API call was successful: 'Success' or 'Error' string Success, Error
current_api_version The latest stable API version number string
new_key Indicates a new call signature needs to be calculated. Applicable only when using Session Token v2 string yes

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:

Example 1 (Success with JSON):
Request
HTTPS://www.mediafire.com/api/contact/get_avatar.php?session_token=&contact_key=4c4mmb4&response_format=json&signature=
                
Response
{
   action: contact/get_avatar,
   avatar: http://dev.mediafire.com/images/icons/myfiles/default.png,
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}                    
Example 2 (Failure with XML - Error 230):
Request
HTTPS://www.mediafire.com/api/contact/get_avatar.php?session_token=&contact_key=4c4mmb5&response_format=json&signature=
                
Response
<action>contact/get_avatar</action>
<message>This user has no associated avatar image</message>
<error>230</error>
<result>Error</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>

Get Sources


GET https://www.mediafire.com/api/1.3/contact/get_sources.php
POST https://www.mediafire.com/api/1.3/contact/get_sources.php

Description: Get contact sources in descending order of precedence.

Required Parameters:

  • none

Relative Parameters:

  • none

Optional Parameters:

  • response_format : 'xml' or 'json' (default 'xml')

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Response Properties

Name Description Type Values
sources A collection of services used to obtain contact information. object array
deprecated Indicates this API is deprecated and should no longer be used. string yes
error The numerical error code integer
message The description of the error string
result Indicates if the API call was successful: 'Success' or 'Error' string Success, Error
current_api_version The latest stable API version number string
new_key Indicates a new call signature needs to be calculated. Applicable only when using Session Token v2 string yes

Example 1 (Success with JSON):

Request
HTTPS://www.mediafire.com/api/contact/get_sources.php?response_format=json
Response
{
   action: contact/get_sources,
   sources:[
      User,
      MediaFire,
      Facebook,
      Gmail,
      Twitter,
      Tumblr,
   ]
   result: Success,
   current_api_version: 1.3,
}

Set Avatar


GET http://www.mediafire.com/api/1.3/contact/set_avatar.php
POST http://www.mediafire.com/api/1.3/contact/set_avatar.php

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.

Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • response_format : 'xml' or 'json' (default 'xml')


Response Properties

Name Description Type Values
upload_key The uploadkey of the avatar string
deprecated Indicates this API is deprecated and should no longer be used. string yes
error The numerical error code 128, 372
message The description of the error string
result Indicates if the API call was successful: 'Success' or 'Error' string Success, Error
current_api_version The latest stable API version number string
new_key Indicates a new call signature needs to be calculated. Applicable only when using Session Token v2 string yes

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:

Example 1 (Success with JSON):
Request
HTTPS://www.mediafire.com/api/contact/set_avatar.php?session_token=&contact_key=kz8j1r3&url=https://lh5.googleusercontent.com/-ER0y8PyG7Zo/AAAAAAAAAAI/AAAAAAAAAEU/NAc8iG47xNc/photo.jpg&response_format=json&signature=
                        
Response
{
   action: contact/set_avatar,
   upload_key: l8k88whcx7,
   result: Success,
   new_key: yes,
   current_api_version: 1.3,
}                        

Example 2 (Failure with JSON - Error 372):

Request
HTTPS://www.mediafire.com/api/contact/set_avatar.php?session_token=&contact_key=kz8j1r3&url=https:/lh5.googleusercontent.com/-ER0y8PyG7Zo/NAc8iG47xNc/photo.jpg&response_format=json&signature=
                        
Response
{
   action: contact/set_avatar,
   message: The URL specified is invalid,
   error: 372,
   result: Error,
   new_key: yes,
   current_api_version: 1.3,
}

Summary


GET http://www.mediafire.com/api/1.3/contact/summary.php
POST http://www.mediafire.com/api/1.3/contact/summary.php

Description : Fetch a summary of contacts by type, including direct vs. indirect.

Required Parameters:


Relative Parameters:

  • signature : Required only for session token version 2. Click here to learn more about building an API call signature.

Optional Parameters:

  • response_format : 'xml' or 'json' (default 'xml')


Response Properties

Name Description Type Values
indirect The number of indirect(system imported) contacts the user has interger
direct The number of direct(user imported) contacts the user has interger
user The number of contacts imported from manual user entry integer
mediafire The number of contacts imported from the user's MediaFire service integer
facebook The number of contacts imported from the user's Facebook service integer
gmail The number of contacts imported from the user's Gmail service integer
twitter The number of contacts imported from the user's Twitter service integer
sms The number of contacts imported from the user's phone service integer
tumblr The number of contacts imported from the user's Tumblr service integer
deprecated Indicates this API is deprecated and should no longer be used. string yes
error The numerical error code
message The description of the error string
result Indicates if the API call was successful: 'Success' or 'Error' string Success, Error
current_api_version The latest stable API version number string
new_key Indicates a new call signature needs to be calculated. Applicable only when using Session Token v2 string yes

Error Codes

To view a list of possible error codes for this API, and their descriptions, click here.


Examples:

Example 1 (Success with XML):
Request
HTTPS://www.mediafire.com/api/contact/summary.php?session_token=&response_format=xml&signature=
Response
<action>contact/summary</action>
<direct>112</direct>
<indirect>240</indirect>
<user>2</user>
<mediafire>254</mediafire>
<facebook>88</facebook>
<gmail>8</gmail>
<twitter>0</twitter>
<sms>0</sms>
<tumblr>0</tumblr>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>