iotoms Docs

Assign a person to a commission plan

POST
/api/v1/commission/plans/{planId}/assignments

Links a salesperson (userRef, their username) to the plan for an effective date range, optionally with a personal rate override on flat plans. Rejected if the person already has an overlapping active assignment.

How to use it

  1. Get the plan ID from List commission plans and the salesperson's username from List users.
  2. Send userRef, effectiveFrom, optional effectiveTo and, on FLAT plans only, an optional rateOverrideBp.
  3. Rejected if the person already has an active assignment overlapping those dates; remove that one first.
  4. The person is included in settlement runs whose period overlaps the assignment.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Path Parameters

planId*string

ID of the commission plan to assign the person to, from List commission plans.

Formatuuid

Header Parameters

X-TenantID*string

Your merchant's tenant code — the value typed in the Domain field on the iotoms login screen. See Concepts.

Request Body

application/json
  1. body
userRef*string

Username of the salesperson to assign, as shown by List users. Required.

rateOverrideBp?|

Optional personal rate in basis points, 0 to 10000 (250 = 2.50%). Only allowed on FLAT plans.

Formatint32
effectiveFrom*string

First date the assignment applies (YYYY-MM-DD).

Formatdate
effectiveTo?|

Optional last date (YYYY-MM-DD), not before effectiveFrom. Omit for open-ended.

Formatdate

Response Body

OK

*/*
  1. response
status*string

Outcome of the request: SUCCESS when it worked; errors return an error status with the reason in message.

message*string

Short human-readable message describing the outcome.

data?

The plan assignment as it now stands.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/commission/plans/497f6eca-6276-4993-bfeb-53cbbbba6f08/assignments' \  -H 'X-TenantID: your-tenant-code' \  -H 'Content-Type: application/json' \  -d '{  "userRef": "string",  "effectiveFrom": "2019-08-24"}'
Example Response
{  "status": "string",  "message": "string",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "planId": "b3f60ba2-c1fd-4b3a-a23d-8e876e0ef75d",    "planName": "string",    "userRef": "string",    "rateOverrideBp": 0,    "effectiveRateBp": 0,    "effectiveFrom": "2019-08-24",    "effectiveTo": "2019-08-24",    "active": true  }}