What can be done with uFathom API?

API lets users access public information on ufathom.com programmatically. Such information has to be used in accordance with the uFathom.com terms of services and Affiliate Program description. Allowed use includes displaying open public projects, information from user profiles on the affiliate's websites with appropriate links to uFathom.com projects or profiles. This information will be useful for all Ufathom members.

Hierarchy of API calls

See more detailed explanation and examples here

• User
  • Properties
• Project
  • Properties
  • Search
    • By expertise
    • By owner
    • Featured
    • For premier members only
    • By budget
    • Order by: random, start time
• Feedback
  • Search
    • By receiver and type and status
    • By project
    • Order by: random, time

Common parameters

The following parameters are available to all calls:

apikey

API key, paramater is optional.

aff

username of affiliate. Include this parameter to the widget's code to make all URLs returned by API affiliate-friendly, meaning that every URL will include the affiliate's username. Use this parameter in your applications to refer new users to uFathom.com and earn bonus from their commissions and fees.

format

xml, json. This parameter is included in URI

count

number of items on a page

Limitations on use of API

We encourage users to use the API in a good manner, save our server resources using caching. To keep our servers available to all of our clients, we introduce limit-rate on API usage. Users can make up to 15 requests per minute. Each user is granted an API key, which should be used with each request user makes. Requests without a personal API key are limitted on IP-basis, meaning that there may be up to 15 requests from 1 IP address within 1 minute.

Generate Api Key

In case when API calls are made using client javascript scripts, it doesn't make sense to use API key, cause API calls are made from visitor's web browsers with visitor's IP. In such case it's recommended not to use API key.

API calls

Project/Properties

Description
Fetches information about a specific project

URL

2 ways to address this call:

https://www.ufathom.com/project/<ID>.(json|xml) - Using this URL, ID of the project is included in URL directly without parameters
https://www.ufathom.com/project/properties.(json|xml) - Using this URL, ID of the project should be specified in parameter id

Parameters

id

ID of project (required)

Returned results

• project
  • id - ID of the project
  • name - title of the project
  • url - URL of the project
  • start_date - date when the project was started
  • start_unixtime - time when project was started in UNIXTIME format
  • end_date - date when the project bidding period ends
  • end_unixtime - time when the project bidding period ends in UNIXTIME format
  • buyer
    • id - ID of the buyer's username
    • url - URL of the buyer's profile
    • username - username of the buyer
  • description - description of the project's requirements
  • options
    • featured - boolean value. 1 if project is featured, 0 - only normal projects
    • for_premier_members - boolean
    • fulltime - boolean
    • parttime - boolean
    • commission - boolean
  • budget
    • min - Numeric double value or empty (false) if no minimum is specified
    • max - Numeric double value or empty (false) if no maximum is specified
  • jobs
    • Array of jobs
  • bid_stats
    • count - number of bids or empty (false) if bid statistics is not available

Samples

API Call: https://www.ufathom.com/api/project/1.xml

API Call: https://www.ufathom.com/api/project/1.json

Project/Search

Description
Searches projects by different search parameters

URL

https://www.ufathom.com/api/project/search.(json|xml)

Parameters

owner

Username of ID of project owner (optional)

jobs[]

Names of job categories from the available list on Ufathom (PHP, .NET, AJAX, etc.). This parameter may be repeated more than once (optional)

featured

If 1 - only featured projects, if 0 - only NON-featured projects (optional)

premier

If 1 - only "For premier members" projects, if 0 - only NON "For premier members" projects (optional)

min_budget

Only projects with budget higher or equal to min_budget (optional)

max_budget

Only projects with budget lower or equal to max_budget (optional)

keyword

Search by keyword (optional)

order

How to order projects in the result output. See available project order criteria.

order_dir

Direction of sorting. If the parameter is equal to asc, results are ordered in ascending way, otherwise - descending (desc).

Returned results

• project
  • count
  • items
    • Array of item
      • id - ID of a project
      • name - title of the project
      • url - URL of the project
      • start_unixtime - time when the project was started in UNIXTIME format
      • start_date - time when the project was started
      • end_unixtime - time when the project bidding period ends in UNIXTIME format
      • end_date - time when the project bidding period ends in RFC 2822 format
      • buyer
        • id - ID of the buyer's username
        • url - URL of the buyer's profile
        • username - username of the buyer
      • description - description of the project's requirements
      • options
        • featured - boolean value. 1 if project is featured, 0 - only normal projects
        • for_premier_members - boolean
        • fulltime - boolean
        • parttime - boolean
        • commission - boolean
      • budget
        • min - Numeric double value or empty (false) if no minimum is specified
        • max - Numeric double value or empty (false) if no maximum is specified
      • jobs
        • Array of jobs
      • bid_stats
        • count - number of bids or empty (false) if bid statistics is not available

Samples

API Call: https://www.ufathom.com/api/project/Search.xml

API Call: https://www.ufathom.com/api/project/Search.json?jobs[]=php&jobs[]=html

Project order criteria

• id - order by project ID
• submitdate - order by date when project was added (default)
• bid_enddate - order by bidding end time
• buyer - order by buyer's username
• budget - order by budget
• bid_count - order by number of bids
• rand - order randomly

User/Properties

Description
Fetches information about a specific user

URL

2 ways to address this call:

https://www.ufathom.com/api/user/<ID>.(json|xml) - Using this URL, ID of the project is included in URL directly without parameters
https://www.ufathom.com/api/user/Properties.(json|xml) - Using this URL, ID of the project should be specified in parameter id

Parameters

id

username of user (required)

Returned results

• profile
  • url - url of the user
  • id - ID of the user
  • username - Username
  • logo_url - URL of logo
  • reg_unixtime - time when the user was registered in UNIXTIME format
  • reg_date - date when the user was registered
  • company - company name or false if company is not specified
  • premier - 1 if the user is a premier member currently, 0 - a non-premier member
  • address
    • country - User's country
    • city - User's city
  • hourlyrate - Hourly rate in USD
  • rating
    • avg - average value of user overral rating, double value from 1 to 10 (i.e. up to 2 digits after the decimal point). 0 - if user hasn't got any rating yet
    • count - number of feedbacks received by user
  • provider_rating
    • avg - average value of provider rating, double value from 1 to 10. 0 - if user hasn't got any rating yet
    • count - number of provider feedbacks received by user
  • buyer_rating
    • avg - average value of buyer rating, double value from 1 to 10. 0 - if user hasn't got any rating yet
    • count - number of buyer feedbacks received by user
  • jobs
    • Array of jobs

Samples

API Call: https://www.ufathom.com/api/User/Properties.xml?id=avijit

API Call: https://www.ufathom.com/api/User/Properties.json?id=avijit

Feedback/Search

Description
Searches feedbacks by different search parameters

URL

https://www.ufathom.com/api/feedback/Search.(json|xml)

Parameters

user

username of a feedback receiver (required)

project_id

ID of project for which the feedback was made (optional)

order

How to order feedbacks in result output. See available feedback order criteria.

order_dir

Direction of sorting. If the parameter is equal to asc, results are ordered in ascending way, otherwise - descending ('desc').

Returned results

• feedbacks
  • count
  • items
    • Array of item
      • project
        • id - ID of a project
        • name - title of a project
        • url - URL of a project
      • from_user
        • url - URL of a user's profile
        • id - ID of a user, who left a feedback
        • username - user, who left a feedback
      • active_unixtime - time when feedback was published in UNIXTIME format
      • active_date - time when feedback was published in RFC 2822 format
      • rating - value of rating from 1 to 10.
      • descr - text of a feedback
      • comment - comment on a feedback left by a feedback receiver
      • bid - provider's offer and price
        • amount - price for doing the project from a project winner bid
        • period - delivery of project in days according to the winning bid
  • user
    • url - URL of user profile
    • id - ID of a user who received feedbacks
    • username - username of feedbacks receiver
  • url - URL of feedback page

Samples

API Call: https://www.ufathom.com/api/feedback/Search.xml?user=manas

API Call: https://www.ufathom.com/api/feedback/Search.json?user=manas&project_id=7

feedback order criteria

• active_date - order by date when feedback was activated
• rand - order randomly