The following applies to User Points API version 3.x. User Points provides an application programming interface (API), which is callable and actionable by other modules. To use this API you simply need to enable the User Points module.

userpoints_userpointsapi(int OR array() )

This is the big daddy of all of the function calls. Use this function to grant points to users. Points can be positive or negative but must be integers and can not be decimal (ex. 5 not 5.2).

The call can either be an integer or an array of parameters. If a single integer is passed points are granted to the currently logged in user using all the site default settings. Pass in an array of parameters to override site settings and/or to ensure that certain settings are used. An direct API call takes precedence over module settings.

When using an array of parameters you must pass in either the points parameters or txn_id. All parameters passed will override site settings. To use the site settings do not pass in the parameter as a set parameter takes precedence (even if null). A list of possible parameters is listed below.

If txn_id is passed in points is not necessary. Passing in a txn_id will update the point record for the transaction ID similar to the use of node_save. It updates all of the point settings stored in the database except for uid or points. To add/subtract or move points from one user to the next you will need to make separate point grants in order to maintain a proper point history. use this function to update a points moderation status, description, expiration date, event, reference, tid, etc.

returns: array.
status: true/false TRUE = successful FALSE = problem

reason: If status is false reason will include a string description of the error for debugging purposes

Listing of parameters

'uid'         => (int) User ID to grant the points to
'points'      => (int) # of points to award the user (may be positive or negative)
'txn_id'      => (int) Transaction ID of a current points record. If
                         present an UPDATE occurs
'moderate'    => (boolean) TRUE or FALSE. If NULL site settings are adhered to
'description' => (string) fulltext Description presented to the user
'expirydate'  => (timestamp) timestamp the date/time when the points will
                               be expired (depends on cron)
'operation'       => (string) varchar32 descriptive identifier administrative purposes
'reference'   => (string) varchar32 indexed/searchable field on the DB
'display'     => (boolean) Whether or not to display the "Points awarded"
                             message. If null, fall back to module settings
'tid'         => (int) Taxonomy ID to place these points into; MUST BE in
                         the userpoints Vocabulary!
'parent_txn_id'   => (int) Transaction ID that shows related transaction(Prior transaction).

Examples

    //Add 5 points to the currently logged in user
    userpoints_userpointsapi(5);  

    //Also add 5 points to the currently logged in user
    $params = array (
      'uid' => $user->uid,
      'points' => 5,
    );
    userpoints_userpointsapi($params); 

hook_userpoints($op, $points, $uid, $event) (Drupal version 5.x only)

This hook is provided so that a module may sanity check points before and/or after they are accumulated and also offer module specific settings on the userpoints administrative settings page. Userpoints strives to provide a single administrative page for all core and contributed module settings. Please use this hook to provide your module's specific administrative settings.

The arguments are:

$op: The operation to be acted upon.
    'setting'
      Pass a field set and fields that would be displayed in the userpoints
      settings page. For example, this can be used for your program to ask
      the admin to set a number of points for certain actions your module
      performs. The function should return an array object conforming to
      FormsAPI structure.

    'points before'
      Calls your module, and others, before the points are processed. You can
      prevent points from being awarded by returning FALSE.

    'points after'
      Calls your module, and others, after points are processed. You can take
      certain actions if you so wish. Return value is ignored.

The rest of the arguments are the same as the userpoints_userpointsapi()
function.

hook_userpoints($op, $params) (Drupal version 6.x only)

This hook allows modules to provides sanity checks before/after points are granted as well as to provides module specific settings on the userpoints administrative page. Userpoints strives to provide a single administrative page for all core and contributed module settings. Please use this hook to provide your module's specific administrative settings.

The $op variable
$op may be equal to the following

    'setting'
      The function should return an array object conforming to FormsAPI structure. 
      A fieldset and a set of field to be display in the userpoints settings page is 
      expected. For example, this can be used to set a number of points for 
      certain actions your module performs. 

    'points before'
      When new points are granted this hook is called and contains the $params 
      array as passed to userpoints_userpointsapi. return FALSE to prevent points
      from being awarded. Although it is possible to directly manipulate the points 
      being awarded it is highly suggested to <strong>not</strong> do this and 
      instead add a second set of points to adjust the original value. This method 
      provides a cleaner audit trail. 

    'points after'
      Calls your module, and others, after points are processed. 
      Return value is ignored.

The $params array
The hook is called with the $params and is passed byref thus all settings in the array may be modified. This $params array is the same array passed into the userpoints_userpointsapi function as outlined above.

userpoints_get_current_points($uid = NULL, $tid = NULL);

Returns an integer of the sum of the user's point
If a tid is passed in that category's sum is returned otherwise
the sites default category is used; passing in 'all' for tid will
return the total points regardless of category.

userpoints_get_max_points($uid = NULL, $tid = NULL);

Returns an integer of the sum of the user's max points achieved
If a tid is passed in that category's sum is returned otherwise
the sites default category is used

userpoints_get_vid()

Returns an integer of the userpoints Vocabulary

userpoints_get_default_tid()

Returns an integer for the userpoints default Taxonomy ID
Note: this is the default when submitting points so you
DO NOT need to pass this into userpoints_userpointsapi

userpoints_get_categories()

Returns an array of the possible categories including
the special "Uncategorized" category (id=0). This is a keyed
array that works perfectly with FAPI. If you're creating a
settings page wherein a user would select the category to
place points into, this will give you exactly what you need.
See userpoints.module admin_settings function for an example.

userpoints_get_default_expiry_date()

Returns a UNIX timestamp of the site's default expiration date.
If an expiration date (or interval) it will be returned otherwise NULL