Process Action

RapidMule allows you to create and customize actions specific to your application. All actions generated by your player's interactions will be consumed by this method for processing.

This method plays a crucial role in tracking and rewarding player actions, helping to create engaging and motivating experiences within your application.

Endpoint

POST /v1/action/process

Request Body

Parameter	Type	Required	Description
name	string	Yes	The name of the action being performed
referenceId	string	Yes	A unique identifier for the action reference in source system
timestamp	long	No	Unix timestamp in milliseconds indicating when the action occurred. Defaults to current date time
playerId	string	Yes	Unique identifier for the player performing the action. Must be a valid UUID
multiplier	decimal	No	A factor to multiply the impact or score of the action. Defaults to 1 if not specified
details	array	No	Container for Action Objects

Example Requests

Login Action

{
  "name": "login",
  "referenceId": "login-f4a7c1b9-3e5d",
  "playerId": "{{playerID}}",
  "details": [
    {
      "name": "day_of_week",
      "value": "3"
    }
  ]
}

Purchase Action

{
  "name": "purchase",
  "referenceId": "order-f4a7c1b9-3e5d",
  "playerId": "{{playerID}}",
  "details": [
    {
      "name": "amount",
      "value": "59.99"
    },
    {
      "name": "currency",
      "value": "USD"
    },
    {
      "name": "category",
      "value": "apparel"
    }
  ]
}

Deposit Action

{
  "name": "deposit",
  "referenceId": "deposit-f4a7c1b9-3e5d",
  "playerId": "{{playerID}}",
  "details": [
    {
      "name": "amount",
      "value": "100.00"
    },
    {
      "name": "currency",
      "value": "USD"
    },
    {
      "name": "payment_provider",
      "value": "stripe"
    }
  ]
}

Response

Success Response

{
"code": 200,
"data": {
  "playerId": "4f9c9e5569524cb18e77d5b804b1e35a",
  "referenceId": "1758712078000",
  "badges": null,
  "triggers": null,
  "achievedLevel": null,
  "earnedPoints": 0,
  "deliverables": [
    {
      "amount": 1,
      "label": "Basketball Banners",
      "type": 2,
      "imageName": "https://rapidmulestorage.blob.core.windows.net/images/e2a7a559-44f4-47e7-9eeb-e9ba613419ed_1000_F_494590444_O9S3i2PGbFcFmBcqzaK4vEF4mtCi1nnM.jpg",

Response arrays

badges, triggers, achievedLevel, deliverables, and completedChallenges are only populated when the processed action actually earns them — otherwise they are null. completedChallenges lists any daily/weekly challenges the player finished as a result of this action, each with the reward deliverables it granted (see Challenges).

Request Example

curl -X POST https://api.rapidmule.com/v1/action/process \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "login",
    "referenceId": "login-f4a7c1b9-3e5d",
    "playerId": "{{playerID}}",
    "details": [
      {
        "name": "day_of_week",
        "value": "3"
      }
    ]
  }'

Best Practices

1. Idempotency

Always include a unique referenceId to prevent duplicate processing. This ensures that if the same action is sent multiple times, it will only be processed once.

2. Action Objects

Include relevant context in the details array to enable more sophisticated condition matching and filtering.

3. Error Handling

Implement proper error handling for duplicate actions and invalid requests.

4. Rate Limiting

Be mindful of rate limits when sending actions. See Rate Limiting for details.

Error Codes

Code	Description	Resolution
1001	Payload is null	Check request body
1002	Invalid Player	Verify playerId exists
2601	Duplicate Action	Check referenceId uniqueness
4001	Invalid AuthKey	Verify API key
5003	PlayerId does not exist	Use valid playerId

Learn More

For a deeper understanding of Actions, see Core Concepts - Actions.