Contact1.4
Add
Notes: New parameter phone_desc.
This API requires SSL and is restricted. If you wish to enable this feature in your app, please contact customer service.
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).
Relative Parameters:
- phone_desc : The description of phone. Required if phone is provided.
- source_uid : The user ID (MediaFire, Facebook, Twitter...) of the contact to be added.
- signature : Required only for session token version 2. Click here to learn more about building an API call signature.
Optional Parameters:
- 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.
- 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 | |
error | The numerical error code | integer | 108 |
message | The error description for error | flag | yes,no |
deprecated | Indicates this API is deprecated and should no longer be used | string | |
result | Indicates if the API call was successful | string | Success/Error |
new_key | Indicates a new call signature needs calculated. Applicable only when using Session Token v2 | flag | yes,no |
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:
Example 1 (Success with JSON - contact_type=email)HTTPS://www.mediafire.com/api/1.4/contact/add.php?session_token=&email=t103%40g.n&contact_type=email&display_name=T103&first_name=Test&last_name=103&response_format=json&signature=
{
action: contact/add,
contact_keys: jwsby92,
result: Success,
new_key: yes,
current_api_version: 1.4,
}
Example 2: Success with XML - contact_type=phone)
HTTPS://www.mediafire.com/api/1.4/contact/add.php?session_token=&phone_desc=mobile&contact_type=phone&display_name=T104&first_name=Test&last_name=104&phone=%2B1%20928%20654%203285&response_format=xml&signature=
<action>contact/add</action>
<contact_keys>jt56ywf</contact_keys>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>
Example 3: Success with JSON - updating existing contact)
HTTPS://www.mediafire.com/api/1.4/contact/add.php?session_token=&source_uid=t03%40g.n&contact_type=mediafire&contact_key=gz0vu5z&birthdate=1990-01-01&gender=male&response_format=json&signature=
{
action: contact/add,
contact_keys: gz0vu5z,
result: Success,
new_key: yes,
current_api_version: 1.3,
}
Delete
Notes: Functionality added to parameter contact_key.
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 : A comma-separated list of contact keys. all may be passed to delete all contacts.
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 - multiple contact_key arguments)
HTTPS://www.mediafire.com/api/1.4/contact/delete.php?session_token=&contact_key=3rjq59b&response_format=xml&signature=
<action>contact/delete</action>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>
Example 2: (Success with JSON - multiple contact_key arguments)
HTTPS://www.mediafire.com/api/1.4/contact/delete.php?session_token=&contact_key=jt56ywf%2Cgz0vu5z&response_format=json&signature=
{
action: contact/delete,
result: Success,
new_key: yes,
current_api_version: 1.3,
}
Example 3: (Success with XML - contact_key=all)
HTTPS://www.mediafire.com/api/1.4/contact/delete.php?session_token=&contact_key=all&response_format=xml&signature=
<action>contact/delete</action>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>
Example 4: (Failure with XML - Error 138)
HTTPS://www.mediafire.com/api/contact/delete.php?session_token=&contact_key=8928dog&response_format=xml&signature=
<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.4</current_api_version>
Fetch
Notes: New parameter contact_type.
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).
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, 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.
- contact_type : Filter contacts by type. Ignored if method=normal is not passed. mediafire, facebook, twitter, gmail, email, phone, user.
- 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_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 | |
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, phone |
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):HTTPS://www.mediafire.com/api/contact/fetch.php?session_token=&method=normal&response_format=xml&signature=
<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.4</current_api_version>
Example 2 (Success with XML - method=autocomplete):
HTTPS://www.mediafire.com/api/1.4/contact/fetch.php?session_token=&method=autocomplete&response_format=xml&signature=
<action>contact/fetch</action>
<node_count>34</node_count>
<directory>IHQxMDFlMDAzMHMzNTQzNTQzdEBAQCBnZ2cwLi4uM25ubg</directory>
<data>fFQxMDUvM2R3OWE1Ni90MTA1QGcubi9odHRwczolMkYlMkZ3d3cubWVkaWFmaXJlLmNvbSUyRmltYWdlcyUyRmljb25zJTJGbXlmaWxlcyUyRmRlZmF1bHQucG5nLzAjMTUsMTIsMTgsMzJ8VDEwNC92bmU5Ynl2Ly9odHRwczolMkYlMkZ3d3cubWVkaWFmaXJlLmNvbSUyRmltYWdlcyUyRmljb25zJTJGbXlmaWxlcyUyRmRlZmF1bHQucG5nLzUjMTYsMTMsMTh8VDEwMy9zMjdoajRyL3QxMDNAZy5uL2h0dHBzOiUyRiUyRnd3dy5tZWRpYWZpcmUuY29tJTJGaW1hZ2VzJTJGaWNvbnMlMkZteWZpbGVzJTJGZGVmYXVsdC5wbmcvOCMxNywxNCwxOCwzM3xUZXN0IDAzLzNzZmIxbXMvdDAzQGcubi9odHRwczolMkYlMkZ3d3cubWVkaWFmaXJlLmNvbSUyRmltYWdlcyUyRmljb25zJTJGbXlmaWxlcyUyRmRlZmF1bHQucG5nLzEjMzAsMTgsOCwzMQ</data>
<trie>u6qudQlVVVU</trie>
<revision>14</revision>
<epoch>1430749551</epoch>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>
Example 3 (Success with JSON - method=autocomplete and raw=yes):
HTTPS://www.mediafire.com/api/1.4/contact/fetch.php?session_token=&method=autocomplete&raw=yes&response_format=json&signature=
{
action: contact/fetch,
node_count: 34,
directory: eyJyb290Ijp7InQiOnsiMSI6eyIwIjp7IjUiOnsiZW5kIjpbMF0sIkAiOnsiZyI6eyIuIjp7Im4iOnsiZW5kIjpbMF19fX19fSwiNCI6eyJlbmQiOlsxXX0sIjMiOnsiZW5kIjpbM10sIkAiOnsiZyI6eyIuIjp7Im4iOnsiZW5kIjpbM119fX19fX19LCJlIjp7InMiOnsidCI6eyJlbmQiOlswLDEsMiwzXSwiICI6eyIwIjp7IjMiOnsiZW5kIjpbMl19fX19fX0sIjAiOnsiMyI6eyJAIjp7ImciOnsiLiI6eyJuIjp7ImVuZCI6WzJdfX19fX19fSwiMSI6eyIwIjp7IjUiOnsiZW5kIjpbMF19LCI0Ijp7ImVuZCI6WzFdfSwiMyI6eyJlbmQiOlszXX19fSwiMCI6eyIzIjp7ImVuZCI6WzJdfX19fQ==,
data: VDEwNS8zZHc5YTU2L3QxMDVAZy5uL2h0dHBzOiUyRiUyRnd3dy5tZWRpYWZpcmUuY29tJTJGaW1hZ2VzJTJGaWNvbnMlMkZteWZpbGVzJTJGZGVmYXVsdC5wbmcvMHxUMTA0L3ZuZTlieXYvL2h0dHBzOiUyRiUyRnd3dy5tZWRpYWZpcmUuY29tJTJGaW1hZ2VzJTJGaWNvbnMlMkZteWZpbGVzJTJGZGVmYXVsdC5wbmcvNXxUZXN0IDAzLzNzZmIxbXMvdDAzQGcubi9odHRwczolMkYlMkZ3d3cubWVkaWFmaXJlLmNvbSUyRmltYWdlcyUyRmljb25zJTJGbXlmaWxlcyUyRmRlZmF1bHQucG5nLzF8VDEwMy9zMjdoajRyL3QxMDNAZy5uL2h0dHBzOiUyRiUyRnd3dy5tZWRpYWZpcmUuY29tJTJGaW1hZ2VzJTJGaWNvbnMlMkZteWZpbGVzJTJGZGVmYXVsdC5wbmcvOA==,
revision: 14,
epoch: 1430749551,
result: Success,
new_key: yes,
current_api_version: 1.3,
}
Example 4 (Success with XML - method=normal and contact_type=phone):
HTTPS://www.mediafire.com/api/1.4/contact/fetch.php?session_token=&method=normal&contact_type=phone&raw=yes&response_format=xml&signature=
<response>
<action>contact/fetch</action>
<contact_groups></contact_groups>
<contacts>
<contact>
<contact_key>vne9byv</contact_key>
<display_name>T104</display_name>
<first_name>Test</first_name>
<last_name>104</last_name>
<avatar>https://www.mediafire.com/images/icons/myfiles/default.png</avatar>
<email></email>
<phone>1 928 654 2845</phone>
<source_uid>1 928 654 2845</source_uid>
<birthdate>0000-00-00</birthdate>
<location></location>
<gender>none</gender>
<website></website>
<options>0</options>
<created>2015-05-04 11:05:56</created>
<contact_type>phone</contact_type>
<created_utc>2015-05-04T16:05:56Z</created_utc>
</contact>
</contacts>
<count>1</count>
<revision>14</revision>
<epoch>1430749551</epoch>
<result>Success</result>
<new_key>yes</new_key>
<current_api_version>1.3</current_api_version>
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.
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):HTTPS://www.mediafire.com/api/contact/get_avatar.php?session_token=&contact_key=4c4mmb4&response_format=json&signature=
{
action: contact/get_avatar,
avatar: http://dev.mediafire.com/images/icons/myfiles/default.png,
result: Success,
new_key: yes,
current_api_version: 1.4,
}
HTTPS://www.mediafire.com/api/contact/get_avatar.php?session_token=&contact_key=4c4mmb5&response_format=json&signature=
<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.4</current_api_version>
Get Sources
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):
HTTPS://www.mediafire.com/api/contact/get_sources.php?response_format=json
{
action: contact/get_sources,
sources:[
User,
MediaFire,
Facebook,
Gmail,
Twitter,
Tumblr,
]
result: Success,
current_api_version: 1.4,
}
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.
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):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=
{
action: contact/set_avatar,
upload_key: l8k88whcx7,
result: Success,
new_key: yes,
current_api_version: 1.4,
}
Example 2 (Failure with JSON - Error 372):
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=
{
action: contact/set_avatar,
message: The URL specified is invalid,
error: 372,
result: Error,
new_key: yes,
current_api_version: 1.4,
}
Summary
Description : Fetch a summary of contacts by type, including direct vs. indirect.
Required Parameters:
- session_token : A type 1 or type 2 session token. (Type 2 will require a call signature).
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 | |
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 | |
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):HTTPS://www.mediafire.com/api/contact/summary.php?session_token=&response_format=xml&signature=
<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.4</current_api_version>