DPA Products Segmentation API

This API allows managing DPA (Deferred Payment Agreement) product segmentations in the system. It provides endpoints to create, read, update, and delete DPA product segmentations, as well as perform specific operations such as changing the segmentation status.

The CMS Base URL is used (see introduction).

The Segmentation Item Object

The Segmentation Item object represents a credit product segmentation in the system.

{
  "segmentationId": "7c7d970a-dfc3-49e9-979c-5bc693a0ebd0",
  "name": "Segmentation for premium users",
  "description": "Segmentation description",
  "productId": "7c7d970a-dfc3-49e9-979c-5bc693a0ebd0",
  "ruleSet": {
    "name": "Rule set for low risk customers",
    "ruleGroups": [
      {
        "operator": "AND",
        "ruleGroup": [
          {
            "operator": "AND",
            "rules": [
              {
                "dataType": "string",
                "values": ["A", "B"],
                "operator": "in",
                "field": "borrower.riskRating"
              },
              {
                "dataType": "string",
                "values": ["PREMIUM"],
                "operator": "eq",
                "field": "customer_type"
              }
            ]
          }
        ]
      }
    ]
  },
  "status": "enabled",
  "partnerId": "6457c3ce-3887-45d6-92ca-299219ea96db",
  "tenant": "altscore",
  "createdAt": "2023-01-01T00:00:00Z"
}

Attributes

Attribute	Description	Type
`segmentationId`	Unique identifier of the segmentation	String (UUID)
`name`	Name of the segmentation	String
`description`	Description of the segmentation	String
`productId`	Identifier of the associated product	String (UUID)
`ruleSet`	Rule set of the segmentation	Object
`status`	Status of the segmentation	String
`partnerId`	Identifier of the partner	String (UUID)
`tenant`	Tenant (account) to which the segmentation belongs	String
`createdAt`	Creation date of the segmentation	String (ISO 8601)

The Rule Group Object

The Rule Group Object is a set of rules that are applied together to define the segmentation. Each group can contain multiple rules and can be combined with logical operators.

{
  "operator": "AND",
  "rules": [
    {
      "dataType": "string",
      "field": "borrower.riskRating",
      "operator": "eq",
      "values": [
          "A"
      ]
    }
  ]
}

Attribute

Attribute	Description	Type
`operator`	Operator type for the group	String (`AND`, `OR`)
`rules`	Set of compasisons	Array of Segmentation Rule

The Segmentation Rule Object

The Segmentation Rule Object defines a specific condition that must be met for a record to be included in the segmentation. Each rule has a data type, a field to compare, an operator, and values to compare against.

{
  "dataType": "string",
  "field": "borrower.riskRating",
  "operator": "eq",
  "values": [
    "A"
  ]
}

Attribute

Attribute	Description	Type
`dataType`	Type of field	String (`string`, `number`, `boolean`, `datetime`)
`field`	Name of field to compare	String
`operator`	Operator type	String (`eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `in`, `between`, `notin`, `exists`, `notexists`)
`values`	Values to compare	Array String

Combination of Operators and Data Types

This table shows the compatibility of operators with different field types:

	string	number	boolean	datetime
eq	✅	✅	✅	✅
neq	✅	✅	✅	✅
gt	❌	✅	❌	✅
lt	❌	✅	❌	✅
gte	❌	✅	❌	✅
lte	❌	✅	❌	✅
between	✅	❌	❌	✅
in	✅	✅	❌	✅
notin	✅	✅	❌	✅
exists	✅	✅	✅	✅
notexists	✅	✅	✅	✅

Available Operations

List Credit Product Segmentations

Retrieves a list of credit product segmentations.

GET /v2/partners/:partner-id/segmentations/dpa

Parameter	Description
`partner-id`	Partner ID

Query Parameters

Parameter	Description	Type	Required
`product-id`	Filter by product ID	Array of String	No
`status`	Filter by segmentation status	String	No
`page`	Page number	Integer	No
`per-page`	Items per page	Integer	No
`sort-direction`	Sorting direction	String	No
`sort-by`	Field to sort by	String	No

Successful Response

The response will be an array of Segmentation Item objects.

Create a Credit Product Segmentation

Creates a new credit product segmentation in the system.

POST /v2/partners/:partner-id/segmentations/dpa

Input Parameters

Parameter	Description	Type	Required
`name`	Name of the segmentation	String	Yes
`description`	Description of the segmentation	String	No
`productId`	ID of the associated product	String (UUID)	Yes
`ruleSet`	Rule set of the segmentation	Object	Yes

Request Example

{
  "name": "Segmentation for client low risk",
  "description": "This Segmentation rule only is applied for client with low risk and customer type premium",
  "productId": "7c7d970a-dfc3-49e9-979c-5bc693a0ebd0",
  "ruleSet": {
    "name": "rule set for low risk customers",
    "ruleGroups": [
      {
        "operator": "AND",
        "ruleGroup": [
          {
            "operator": "AND",
            "rules": [
              {
                "dataType": "string",
                "values": ["A", "B"],
                "operator": "in",
                "field": "borrower.risk"
              },
              {
                "dataType": "string",
                "values": ["PREMIUM"],
                "operator": "eq",
                "field": "customer_type"
              }
            ]
          }
        ]
      }
    ]
  }
}

Successful Response

{
  "segmentationId": "f5452db8-6d6e-4a78-8cb9-e4a8e3d0e7bf"
}

Get a Credit Product Segmentation

Retrieves information about a specific credit product segmentation.

GET /v2/partners/:partner-id/segmentations/dpa/:segmentation-id

Path Parameters

Parameter	Description
`partner-id`	Partner ID
`segmentation-id`	Credit product segmentation ID

Successful Response

The response will be a complete Segmentation Item object.

Update a Credit Product Segmentation

Updates information of an existing credit product segmentation.

PATCH /v2/partners/:partner-id/segmentations/dpa/:segmentation-id

Path Parameters

Parameter	Description
`partner-id`	Partner ID
`segmentation-id`	Credit product segmentation ID

Input Parameters

Same as in segmentation creation, all optional.

Request Example

{
  "name": "Updated Segmentation for low risk clients",
  "description": "Updated segmentation rule for low risk clients",
  "ruleSet": {
    "name": "Updated rule set for low risk customers",
    "ruleGroups": [
      {
        "operator": "AND",
        "ruleGroup": [
          {
            "operator": "AND",
            "rules": [
              {
                "dataType": "string",
                "values": ["A", "B", "C"],
                "operator": "in",
                "field": "borrower.risk"
              },
              {
                "dataType": "string",
                "values": ["PREMIUM", "GOLD"],
                "operator": "in",
                "field": "customer_type"
              }
            ]
          }
        ]
      }
    ]
  }
}

Successful Response

The response will be the updated Segmentation Item object.

Delete a Credit Product Segmentation

Deletes a credit product segmentation from the system.

DELETE /v2/partners/:partner-id/segmentations/dpa/:segmentation-id

Path Parameters

Parameter	Description
`partner-id`	Partner ID
`segmentation-id`	Credit product segmentation ID

Successful Response

Status code 204 (No Content) if the deletion was successful.

Change the Status of a Credit Product Segmentation

Updates the status of a credit product segmentation.

PUT /v2/partners/:partner-id/segmentations/dpa/:segmentation-id/status

Path Parameters

Parameter	Description
`partner-id`	Partner ID
`segmentation-id`	Credit product segmentation ID

Input Parameters

Parameter	Description	Type	Required
`status`	New status of the segmentation	String ("enabled" or "disabled")	Yes

Request Example

{
  "status": "disabled"
}

Successful Response

Status code 204 (No Content) if the update was successful.

Error Handling

The API may return the following error codes:

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
500	Internal Server Error

Errors will include a descriptive message in the response body.

On this page