REST APIs Explained: What Every ICM Consultant Should Know

Imagine you want to ask SAP SuccessFactors Incentive Management: "Give me all active participants in the APAC region" or "Post 500 credit transactions from this month's sales" or "Get me the calculated results for Q1 so I can pass them to payroll." That's what a REST API does — it's a conversation between your code and the platform, over HTTP, using structured data (JSON).

What is REST?

REST stands for Representational State Transfer. It's an architectural style for web APIs that uses HTTP verbs and resource identifiers (URLs) to perform operations. You've used REST before without thinking about it — when your browser fetches a webpage, it's using REST.

The core idea: everything in the system is a resource (a participant, a plan, a credit transaction, a calculation result). Each resource has a unique URL (an endpoint). You perform actions on that resource using HTTP methods — GET to read, POST to create, PUT to replace, DELETE to remove, PATCH to partially update.

HTTP Methods: The Four Operations

REST uses standard HTTP verbs to define what you're doing:

Idempotent means doing it once or doing it 10 times has the same effect. GET and PUT are safe to retry; POST can create duplicates if you retry without checking.

Resources and Endpoints

A resource is a noun (participant, plan, result). An endpoint is the URL where you reach that resource:

// Reading
GET /participants                         Fetch all participants (paginated)
GET /participants/P001234                 Fetch one specific participant
GET /comp-plans                           Fetch all compensation plans
GET /results                              Fetch calculated results

// Writing
POST /credits                             Post a single credit
POST /credits/batch                       Post multiple credits at once
PUT /quotas/QUOTA-4567                    Update a quota
POST /pipeline-runs                       Trigger a calculation pipeline run

Request and Response: JSON

REST APIs use JSON (JavaScript Object Notation) for data. JSON is human-readable, language-agnostic, and easy to parse. A JSON object is a collection of key-value pairs wrapped in curly braces.

Request Format

When you POST a credit transaction to SAP SuccessFactors IM, you send:

{
  "participantId": "P001234",
  "transactionDate": "2026-03-15",
  "amount": 45000.00,
  "currencyCode": "USD",
  "periodId": "Q1-2026",
  "sourceRef": "CRM-ORDER-98765"
}

Response Format

When you GET participants, the API returns:

{
  "value": [
    {
      "id": "P001234",
      "name": "Alice Johnson",
      "position": "Senior Sales Manager",
      "managerId": "P000999",
      "status": "ACTIVE",
      "region": "APAC"
    },
    {
      "id": "P001235",
      "name": "Bob Smith",
      "position": "Sales Representative",
      "managerId": "P001234",
      "status": "ACTIVE",
      "region": "APAC"
    }
  ],
  "@odata.nextLink": "https://api.sap.com/.../participants?skip=100"
}

The response is an object with a value array (the actual records) and pagination info. More on pagination in Lesson 3.

HTTP Status Codes: What Happened?

Every HTTP response includes a status code. These codes tell you whether the request succeeded, and if not, why:

Headers: Metadata About the Request

HTTP headers are key-value pairs that travel with your request or response. They provide metadata — what kind of data you're sending, what kind you expect back, who you are, etc.

Common Request Headers for SAP SuccessFactors IM

Common Response Headers

Tools for Testing APIs

You'll test APIs in three ways: shell scripts with curl, GUI tools like Postman, and Python code. Each has its place.

curl: Quick One-Off Tests

curl is a command-line tool pre-installed on macOS and Linux (Windows 10+). Perfect for quick checks:

# Fetch a single participant by ID
curl -X GET \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  "https://api.sap.com/successfactors/im/participants/P001234"

# Pretty-print the JSON response
curl -s https://api.sap.com/successfactors/im/participants/P001234 \
  | python3 -m json.tool

Postman: Visual Request Builder

Postman (postman.com, free) is a GUI application for building and testing API requests. Click through the UI to set URL, method, headers, and body. It shows the response, gives you syntax highlighting, and lets you save requests as collections. Excellent for exploring an API you're learning.

Python: Programmatic Integration Testing

Once you know what you're doing, write Python with the requests library:

import requests
import json

url = "https://api.sap.com/successfactors/im/participants/P001234"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
}

# Make the request
resp = requests.get(url, headers=headers)

# Check status code
print(f"Status: {resp.status_code}")

# Parse JSON response
data = resp.json()
print(json.dumps(data, indent=2))

The SAP SuccessFactors IM REST API: What Can You Do?

The SAP SuccessFactors IM REST API covers the full breadth of the platform's operations. Here's what you can do:

Reading Data

• Participants: Fetch all participants, filter by status/region/manager, get hierarchy
• Plans: List all comp plans, get plan details and assignments
• Results: Extract calculated incentive amounts by participant, period, or status
• Quotas: Read quota allocations, compare actual to target
• Statements: Get statement data, check generation status
• Pipeline Runs: Query run history, check status and logs

Writing Data

• Credits: Post individual transactions or batch uploads from CRM/ERP systems
• Quota Updates: Write new quota allocations from planning tools
• Pipeline Runs: Trigger calculation runs programmatically (instead of manual UI click)

Typical Integration Scenarios

Why APIs Matter for ICM

Incentive compensation isn't an island. It's embedded in a system:

• CRM feeds sales data: Your Salesforce CRM generates orders and transactions daily. Those need to flow into IM as credits to feed the compensation calculation. The API is how that happens — no manual exports/imports.
• HR feeds participant data: When someone is hired, promoted, or leaves, that change in HR needs to update the IM participant list. The API enables automated sync.
• Payroll consumes results: After calculation completes, results need to be extracted and passed to your payroll system. The API lets you pull approved results on a schedule and feed them directly to ADP or Workday.
• BI tools need reporting data: Executives want dashboards showing compensation payouts, attach rates, plan performance. The API lets BI platforms (Tableau, SAC, Power BI) pull this data automatically.

Without APIs, all of this would be manual: export from CRM, format it, import to IM, export results, import to payroll. With APIs, it's automated, real-time, and trackable.

Next Steps

Now that you understand what REST APIs are, how they work, and what SAP SuccessFactors IM can do via API, you're ready to learn how to authenticate. Move to Lesson 2.