Steps API

This API allows managing steps in a borrower's process within the system. It provides endpoints to create, list, update, and delete steps, as well as to obtain summaries and step counts.

The Step Object

The Step object represents a step in a borrower's process.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "principalId": "456e4567-e89b-12d3-a456-426614174222",
  "order": 1,
  "key": "application",
  "label": "Application",
  "createdAt": "2023-04-01T12:00:00Z"
}

Attributes

Attribute	Description	Type
`id`	Unique identifier of the step	String
`borrowerId`	Associated borrower ID	String
`principalId`	ID of the principal who created the step (optional)	String
`order`	Order of the step in the process	Integer
`key`	Unique key identifying the type of step	String
`label`	Descriptive label of the step	String
`createdAt`	Date and time of step creation	String (ISO 8601)

Available Operations

Create a New Step

Creates a new step for a borrower.

POST /v1/steps

Input Parameters

Parameter	Description	Type	Required
`borrowerId`	Borrower ID	String	Yes
`key`	Step key	String	Yes

Example Request

{
  "borrowerId": "789e4567-e89b-12d3-a456-426614174111",
  "key": "application"
}

Successful Response

Status code 204 (No Content) if the step was successfully created.

List Steps

Retrieves a paginated list of steps with filtering and sorting options.

GET /v1/steps

Query Parameters

Parameter	Description	Type
`borrower-id`	Filter by borrower ID	String
`key`	Filter by step key	String
`order`	Filter by step order	Integer
`page`	Page number (default: 1)	Integer
`per-page`	Items per page (default: 10)	Integer
`sort-by`	Field to sort by	String
`sort-direction`	Sorting direction (asc or desc)	String

Successful Response

The response will be a paginated list of Step objects.

Delete a Step

Deletes a specific step.

DELETE /v1/steps/:step_id

Path Parameters

Parameter	Description
`step_id`	ID of the step to delete

Successful Response

Status code 204 (No Content) if the step was successfully deleted.

Get Steps Summary

Retrieves a summary of the borrowers' steps.

GET /v1/steps/summary

Query Parameters

Parameter	Description	Type
`dateToAnalyze`	Date to analyze (optional)	String

Successful Response

The response will be a StepSummary object with information about the steps and conversion funnel.

Get Steps Summary by Borrower

Retrieves a summary of the current steps of all borrowers.

GET /v1/steps/borrower-summary

Successful Response

The response will be a list of BorrowerStepSummary objects with information about the current steps of the borrowers.

Get Steps Count

Retrieves a count of steps by period.

GET /v1/steps/count

Query Parameters

Parameter	Description	Type
`dateFrom`	Start date for the count (optional)	String
`dateTo`	End date for the count (optional)	String
`periodicity`	Count periodicity (daily, weekly, monthly)	String

Successful Response

The response will be a StepCount object with information about the count of steps by period.

Other Relevant Objects

The StepSummary Object

The StepSummary object provides a summary of the conversion funnel of the steps on a specific date.

{
  "date": "2023-04-01T12:00:00Z",
  "steps": [
    {
      "order": 1,
      "step": "application",
      "count": 100,
      "funnelCount": 300,
      "label": "Application"
    },
    {
      "order": 2,
      "step": "approval",
      "count": 75,
      "funnelCount": 200,
      "label": "Approval"
    },
    {
      "order": 3,
      "step": "disbursement",
      "count": 50,
      "funnelCount": 125,
      "label": "Disbursement"
    }
  ]
}

Attributes

Attribute	Description	Type
`date`	Summary date	String (ISO 8601)
`steps`	List of StepData objects	Array

The StepData Object

Attribute	Description	Type
`order`	Order of the step in the process	Integer
`step`	Step key	String
`count`	Number of borrowers in this step	Integer
`funnelCount`	Cumulative number of borrowers up to this step	Integer
`label`	Descriptive label of the step	String

The BorrowerStepSummary Object

The BorrowerStepSummary object provides a summary of the current steps of all borrowers.

[
  {
    "order": 1,
    "step": "application",
    "count": 50,
    "label": "Application"
  },
  {
    "order": 2,
    "step": "approval",
    "count": 30,
    "label": "Approval"
  },
  {
    "order": 3,
    "step": "disbursement",
    "count": 20,
    "label": "Disbursement"
  }
]

Attributes

Attribute	Description	Type
`order`	Order of the step in the process	Integer
`step`	Step key	String
`count`	Number of borrowers currently in this step	Integer
`label`	Descriptive label of the step	String

The StepCount Object

The StepCount object provides a count of steps by period.

{
  "data": [
    {
      "date": "2023-04-01",
      "stages": [
        {
          "key": "application",
          "count": 10,
          "label": "Application",
          "order": 1
        },
        {
          "key": "approval",
          "count": 5,
          "label": "Approval",
          "order": 2
        },
        {
          "key": "disbursement",
          "count": 3,
          "label": "Disbursement",
          "order": 3
        }
      ]
    },
    {
      "date": "2023-04-02",
      "stages": [
        {
          "key": "application",
          "count": 15,
          "label": "Application",
          "order": 1
        },
        {
          "key": "approval",
          "count": 8,
          "label": "Approval",
          "order": 2
        },
        {
          "key": "disbursement",
          "count": 4,
          "label": "Disbursement",
          "order": 3
        }
      ]
    }
  ]
}

Attributes

Attribute	Description	Type
`data`	List of PeriodData objects	Array

The PeriodData Object

Attribute	Description	Type
`date`	Period date	String
`stages`	List of StageDetail objects	Array

The StageDetail Object

Attribute	Description	Type
`key`	Step key	String
`count`	Number of borrowers in this step	Integer
`label`	Descriptive label of the step	String
`order`	Order of the step in the process	Integer

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