Per-transaction metrics, cost metrics, and a per-partner performance report carrying vendor success rate and cost.
Every invocation reports timing, outcome and cost. The surface serves that back as transaction metrics, cost metrics, custom report templates, and the public status view.
The per-partner report carries success rate and cost per vendor, which is the measurement a waterfall ordering is retuned from — the ordering is only as good as the evidence that a vendor is answering.
How it works
Vendor performance was reported from the beginning rather than added once someone asked. That is the difference between a waterfall as an idea and a waterfall that can be tuned: without per-vendor success and cost, the order is a guess that nobody can correct.
This service returns a list of occurred alarm events.
NOTE: Alarm events have one week retention period. Events that passed the retention period will be deleted.
Health alarms provide real-time alerts based on a given condition. If you want to be notified when an alert event has occurred, you can select a destination option. You are able to select one or more destination channels from the available options.
Condition
Health alarms are generated based on given conditions.
Destinations
Notification can be delivered after the alert event has occurred. Destinations are notification channels for alert delivery. One or more notification channels can be selected ex: Slack, and Webhook.
Slack:
Slack integration requires a slack token that belongs to Slack apps. Please create a new application by using Slack API. After application creation, go to channel configuration and add created Slack app as an integration using "Apps" section in the "Integrations" tab.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
text/html
Not found.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>404 Not found</h1></center>\r\n</body>\r\n</html>\r\n
Parameters
4
Parameter
Type
Example
Description
x-sc-trace-idrequired
stringheader
01GYYMHV78DVPV5TSHPQTJ31X9
Trace ID
x-api-keyrequired
stringheader
<redacted>
API key
x-api-keyrequired
stringheader
<redacted>
API key
alarm_idrequired
stringpath
alarm_id_1
Unique alarm ID
Request bodyapplication/json
2 fields
Field
Type
Description
conditionrequired
object
Alarm filter configuration
host_environment
string
Host environment
product_identifierrequired
string
Product identifier
product_api_identifiers
string[]
List of product api identifiers
statuses
string[]
List of status
invocation_codes
string[]
List of invocation codes
configuration_ids
string[]
List of product configuration ID
product_build_hash
string
Product build hash
elapsed_time_above
number
Filters metrics which has elapsed time above
elapsed_time_below
number
Filters metrics which has elapsed time below
slack_usergroup_id
string
Slack usergroup id. Use this to tag your team group in the slack message. This ID ALWAYS starts with S and is followed by 9 characters.Example slack_usergroup_id_1
Build a custom report using the metrics posted for any product or custom-created metric types.
Build a custom report using the metrics posted for any product or custom-created metric types. Define the fields to retrieve, the filters to apply, and the aggregation if needed.
The report data to retrieve can be defined in two ways:
Aggregated:Providing the aggregation function, aggregation_fields and group_by will allow to bring the results aggregated.
Detailed:Specify the fields and filters to retrieve detailed metrics data.
{
"message": "the custom report was successfully created"
}
application/json
Bad request error
{
"message": "Error in metric_type creation: the Report simples2 already exists"
}
text/html
Bad request error
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
application/json
Error.
{
"message": "Internal server error"
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Key
Request bodyapplication/json
7 fields
Field
Type
Description
get
string[]
Items which will be retrieved (product_name, status, transaction_id,request_collection_id,response_collection_id,operation_status,partner_name,severity,service_endpoint,created_at)
metric_type
string
The name of the metric type created or use "performance" for transaction and logging metrics posted in the Health.
aggregation
string
For aggregated reports, it will calculate the given function (count, avg, sum)
aggregation_field
string
For aggregated reports, it will calculate the aggregation function with this field. Example(transaction_id, response_collection_id)
group_by
array
For aggregated reports, it will group the data by these fields. Example(product_name, service_endpoint)
filters
object
Filters applied for the report
environment
string[]
Environment example
product_name
string[]
Product Name Example
status
string[]
Status Example
report_name
string
Name of the Report.
Response 201application/json
1 fields
Success Response
Field
Type
Description
message
string
Message
Response 400application/json
1 fields
Bad request error
Field
Type
Description
message
string
Message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 502application/json
1 fields
Error.
Field
Type
Description
message
string
Message error
GET/get-report
Retrieve Custom Report
get_custom_report
This service runs a custom report and allows to retrieve the results for the given report structure.
This service runs a custom report and allows to retrieve the results for the given report structure. The start and end date defines the report data timeframe, also the filters are applied.
See the service Update custom report to change the structure of the report.
{
"message": "Error in report retrieving: there is no report with the report_name equals: simples221"
}
text/html
Error Response
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
4
Parameter
Type
Example
Description
report_namerequired
stringquery
simples221
The name of the Report
start_daterequired
stringquery
2021-01-01
Start date
end_daterequired
stringquery
2021-06-30
End date
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Key
Response 200application/json
1 fields
Success
Field
Type
Description
Items
object[]
Items
transaction_id
string
Field name
created_at
string
Field name
host_env
string
Field name
product_name
string
Field name
status
string
Field name
Response 400application/json
1 fields
Error Response
Field
Type
Description
message
string
Message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
PUT/update-build-report
Update Custom Report
update_custom_report
This service allows updating a custom report structure.
This service allows updating a custom report structure.
{
"message": "the custom report was successfully updated"
}
application/json
400 Bad Request
{
"message": "Error in updating report: the Report report_to_create_name does not exist"
}
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
application/json
Error.
{
"message": "Internal server error"
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Key
Request bodyapplication/json
4 fields
Field
Type
Description
get
string[]
Items which will be retrieved (product_name, status, transaction_id,request_collection_id,response_collection_id,operation_status,partner_name,severity,service_endpoint,created_at)
metric_type
string
The name of the metric type created or use "performance" for transaction and logging metrics posted in the Health.
filters
object
Filters applied for the report
environment
string[]
Environment example
product_name
string[]
Product Name Example
status
string[]
Status Example
report_name
string
Name of the Report.
Response 200application/json
1 fields
Success Response
Field
Type
Description
message
string
Message
Response 400application/json
1 fields
400 Bad Request
Field
Type
Description
error
string
Error message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 502application/json
1 fields
Error.
Field
Type
Description
message
string
Message error
GET/get-report-id
Retrieve Custom Report Id
get_custom_report_id
This service runs a custom report and allows to retrieve the results for the given report structure.
This service runs a custom report and allows to retrieve the results for the given report structure. The start and end date defines the report data timeframe, also the filters are applied.
The response will be a report id which could be used to retrieve the report using the service /get-report-result
See the service Update custom report to change the structure of the report.
{
"message": "Error in report retrieving: there is no report with the report_name equals: simples221"
}
text/html
Error Response
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
4
Parameter
Type
Example
Description
report_namerequired
stringquery
simples221
The name of the Report
start_daterequired
stringquery
2021-01-01
Start date
end_daterequired
stringquery
2021-06-30
End date
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Key
Response 200application/json
2 fields
Success
Field
Type
Description
report_id
string
Field name
Items
array
Items
Response 400application/json
1 fields
Error Response
Field
Type
Description
message
string
Message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
GET/get-report-result
Retrieve Custom Report CSV
get_custom_report_results_csv
This service runs a custom report and allows to retrieve the results as a pre signed URL which contains a CSV file with the report results.
This service runs a custom report and allows to retrieve the results for the given report structure. The start and end date defines the report data timeframe, also the filters are applied.
See the service Update custom report to change the structure of the report.
{
"message": "Error in report retrieving: there is no report with the report_name equals: simples221"
}
text/html
Error Response
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
3
Parameter
Type
Example
Description
report_idrequired
stringquery
simples221
The id of the report
next_token
stringquery
000000000000
The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.)
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Key
Response 200application/json
1 fields
Success
Field
Type
Description
Items
object[]
Items
transaction_id
string
Field name
created_at
string
Field name
host_env
string
Field name
product_name
string
Field name
status
string
Field name
Response 400application/json
1 fields
Error Response
Field
Type
Description
message
string
Message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Cost Metrics
POST/cost-metric
Create a Cost Metric
create_cost_metric
Create a cost metric. These metrics are used to track customer costs.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
<redacted>
Key
Request bodyapplication/json
9 fields
Field
Type
Description
transaction_idrequired
string
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
cost_in_centsrequired
number
The Cost in cents. It must be an integer number.
pages
string
The number of pages of a document used for data extraction.
partner
string
Partner
product_namerequired
string
The system that is exposed externally to customers and performs the action. Examples Assess, Build, Employment.
document_type
string
The type of document in the data extraction. Example: W2cost: the cost price.
cost_categoryrequired
string
There are only two types of cost_category allowed (partner and customer)Example customer
request_collection_id
string (string)
A request collection in Staircase is a container for the elements that a product needs to execute. For example, an AUS collection is a digital representation of a loan application, while a Data Extraction collection is a digital representation of a document.Example 01F2MHXNNNVK02YEY63Q5EQ59T
response_collection_id
string (string)
A response collection in Staircase is a container for the elements that a product has as an output for its execution.Example 01F2MHXNNNVK02YEY63Q5EQ59T
Response 201application/json
1 fields
Success response.
Field
Type
Description
message
string
Message response
Response 400application/json
1 fields
Error Response.
Field
Type
Description
message
string
Error message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
GET/cost-metric
Retrieve a Cost Metric
get_cost_metric
Retrieve a list of cost metric. These metrics are used to track customer costs.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
11
Parameter
Type
Example
Description
transaction_id
stringquery
2345678a
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
product_name
stringquery
Health
The system that is exposed externally to customers and performs the action. Examples Assess, Build, Employment.
partner
stringquery
softworks
Partner
cost_in_cents
stringquery
95
Cost
pages
stringquery
110
The number of pages of a document used for data extraction.
cost_category
stringquery
partner
Cost category the metric belongs to.
document_type
stringquery
test-1
The type of document in the data extraction.
start_date
stringquery
2021-04-13
If provided, filters by start_date it must be used together with the end_date. Date must be in ISO8601 format: YYYY-MM-DD
end_date
stringquery
2021-04-16
If provided, filters by end_date it must be used together with the start_date. Date must be in ISO8601 format: YYYY-MM-DD
date
stringquery
2021-04-16
If provided, filters by date Date must be in ISO8601 format: YYYY-MM-DD
x-api-keyrequired
stringheader
<redacted>
API key
Response 200application/json
1 fields
Ok.
Field
Type
Description
Items
object[]
Items
transaction_id
string
Transaction Identifier
cost_in_cents
string
cost
pages
string
pages
partner
string
partner
created_at
string
Creation date in timestamp format
product_name
string
Name of the Product
document_type
string
Type of the document
Response 400application/json
1 fields
Error response example
Field
Type
Description
Error
string
Error
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Development
POST/development-products
Mark as development env for specific product
register_env
Mark this environment as development env for specific product, so failures for this product on this env will not affect Staircase status page.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
Parameters
2
Parameter
Type
Example
Description
x-sc-trace-idrequired
stringheader
01GYYMHV78DVPV5TSHPQTJ31X9
Trace ID
x-api-keyrequired
stringheader
<redacted>
API key
Request bodyapplication/json
2 fields
Field
Type
Description
product_idrequired
string
The product id that we want to mark as development env.Example ccd6b8dd-02a7-4c64-a983-7e0c108cd666
is_disabledrequired
boolean
If true, disable sending alerts for this product_id on this env.Example true
Response 201application/json
1 fields
Ok.
Field
Type
Description
message
string
The environment was configured successfully
Response 400application/json
1 fields
400 response.
Field
Type
Description
message
string
Error in storing the environment invalid host
Response 403application/json
1 fields
Forbidden
Field
Type
Description
message
string
Error message
Response 504application/json
1 fields
504 Timeout response.
Field
Type
Description
message
string
Endpoint request timed out
Performance Metrics
POST/metric/{transaction_id}
Create New Metric
create_metric
Create New Metric.
Registers a metric identified by a transaction_id or a unique identifier to track product performance, If multiple services in a product perform processing for the same transaction, the services should send their results to Create New Metric, enabling customers to see the result for one transaction between all products.
Create New Metric tracks the following metric types:
Transaction: For every service endpoint invocation, a metric of this type is posted to Health providing information about the service, error, or relevant data to track.
Show the rest
Logging: For every service endpoint invocation the logging metrics are posted to follow up the execution process in the source code and including relevant information to track an issue.
Health Metrics stores additional fields depending on the product family that allows tracking product KPIs.
Single Health Metric payload has 256 KB size limit.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
application/json
Failed Creation.
{
"message": "Internal server error"
}
Parameters
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API key
transaction_idrequired
stringpath
3cd0ffab-6e87-40a8-bc84-697155131f4c
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
Request bodyapplication/json
14 fields
Field
Type
Description
product_namerequired
string
The system that is exposed externally to customers and performs the action. Examples Assess, Build, Employment.Example employment
host_environment
string
Environment host where the product is deployed.Example documentation.staircaseapi.com
service_endpointrequired
string
The service endpoint URL that executed an operation, process, or function in the product. Endpoints with path parameters cannot be sent with real values, it must be sent as variables. Example /metric/%7Btransaction_id%7D and /metric are service endpoints of the Health product.Example /metric/%7Btransaction_id%7D
method
string
HTTP's method or verb that indicates the service endpoint operation type.DELETE GET PATCH POST PUTExample POST
metric_type
string (string)
The type of metric to create, valid options: logging | transactionloggingtransactionExample logging
logging_message
string (string)
This field is only available for logging metric_type. It is used for logging purpose.Example Get collection translation
data
object
Receives a valid JSON with data fields the product wants to log to track issues faster.
request_collection_id
string (string)
A request collection in Staircase is a container for the elements that a product needs to execute. For example, an AUS collection is a digital representation of a loan application, while a Data Extraction collection is a digital representation of a document.Example 01F2MHXNNNVK02YEY63Q5EQ59T
response_collection_id
string (string)
A response collection in Staircase is a container for the elements that a product has as an output for its execution.Example 01F2MHXNNNVK02YEY63Q5EQ59T
partner_name
string
The name of the data partner you will receive a product response from. Products that interact with partner integrations in the service endpoint operation should send this field.Example Atomic
severity
string
The type of the severity to create metric.CRITICALDEBUGERRORHIGHINFOLOWMEDIUMWARNING
operation_status
string
Every single Staircase service endpoint (such as POST /persistence/transactions or POST /aus/underwrite) is required to provide operation status updates to denote the progress of a transaction in its execution. For more information see the Health overview page with examples.ABORTEDCANCELLEDCOMPLETEDCREATEDEMAIL_CONFIRMEDERRORFAILEDIN PROGRESSIN_PROGRESSNOT_FOUNDREQUEST_MADERUNNINGSTARTEDSUCCEEDEDSUCCEEDED_WITH_WARNINGTIMED_OUTTIMEOUTUNAUTHORIZEDWAITING_FOR_RESPONSEExample COMPLETED
elapsed_time
number
The measured duration of an event. The time is expressed in seconds.Example 120.27
error
object
Receives a valid JSON with the fields to store the error or exception details that occurred during the operation execution. The metric is considered as failed when the error details are provided
statusrequired
integer
Status or error code that will be returned by the serviceExample 401
code
integer
Internal error codes.Example 42042
messagerequired
string
Message of Status Code.Example Unauthorized
more_info
string
Additional Information on ErrorExample https://api.staircase.co/docs/errors/42042
Response 201application/json
1 fields
Ok.
Field
Type
Description
message
string
Message the metric was successfully created
Response 400application/json
1 fields
Failed Creation.
Field
Type
Description
message
string
Message reason why the creation has failed
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 500application/json
1 fields
Failed Creation.
Field
Type
Description
message
string
Message error
GET/metric
Retrieve Metrics
transactions_list
The service retrieves a list of metrics given one or multiple filters. To retrieve all results, send the request with the same query parameters and next_token provided on the previous call until next_token does not appear in the response.
The parameters must use URL Encoding for Special Characters ``` e.g. Left Curly Brace (“{”) = “%7B”, Right Curly Brace (“}”) = “%7D” ``` service_endpoint=%7Btransaction_id%7D
Example: service_endpoint=/metric/%7Btransaction_id%7D, for the service "/metric/%7Btransaction_id%7D"
{
"response": {
"value": {
"message": "Filters not allowed ",
"allowed filters": [
"product_name",
"status",
"partner_name",
"metric_type",
"operation_stauts",
"product_name and severity",
"product_name and status",
"operation_stauts and partner_name",
"start_date and end_date can be combined with every filter"
]
}
}
}
text/html
Error Response.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
15
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API key
service_name
stringquery
/employment
It will be consider as product_name, If provided, filters by concrete product name.
product_name
stringquery
employment
If provided, filters by concrete product name.
criterion
stringquery
succeeded
It will be consider status. Available values: failed, succeeded
status
stringquery
succeeded
status. Available values: failed, succeeded
partner_name
stringquery
Atomic
If provided, filters by partner_name
operation_status
stringquery
STARTED
If provided, filters by operation_status
metric_type
stringquery
logging
If provided, filters by metric_type
severity
stringquery
LOW
If provided, filters by severity
start_date
stringquery
2021-04-13
If provided, filters by start_date it must be used together with the end_date. Date must be in ISO8601 format: YYYY-MM-DD
end_date
stringquery
2021-04-16
If provided, filters by end_date it must be used together with the start_date. Date must be in ISO8601 format: YYYY-MM-DD
date
stringquery
2021-04-16
If provided, filters by date Date must be in ISO8601 format: YYYY-MM-DD
next_token
stringquery
000000000000
The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.)
customer_api_key
stringquery
954913e2-db71-4f22-b71c-ef803915eb2b
It is the key required in order to use the API. Filters by customer_api_key.
elapsed_time
stringquery
120.27
The measured duration of an event. The time is expressed in seconds.
Response 200application/json
2 fields
Ok.
Field
Type
Description
next_token
string
Pagination Token
metrics
object[]
Metrics
host_environment
string
Environment host where the product is deployed.
service_endpoint
string
The service endpoint URL that executed an operation, process, or function in the product. Endpoints with path parameters cannot be sent with real values, it must be sent as variables. Example /metric/%7Btransaction_id%7D and /metric are service endpoints of the Health product.
product_name
string
The system that is exposed externally to customers and performs the action. Examples Assess, Build, Employment.
created_at
string
A collection in Staircase is a container for the elements that a product needs to execute. For example, an AUS collection is a digital representation of a loan application, while a Data Extraction collection is a digital representation of a document.
operation_status
string
The status of an operation given the nature of the actions performed by the service and the transaction result. The service endpoint operation could be successful but the transaction_id could have different status given certain conditions and other operations performed.
metric_type
string
The type of metric options allowed logging | transaction
logging_message
string
This field is only available for metric_type equals logging. It is used for logging purpose.
transaction_id
string
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
severity
string
Severity e.g. (HIGH, MEDIUM, LOW)CRITICALDEBUGERRORHIGHINFOLOWMEDIUMWARNING
customer_api_key
string
It is the key required in order to use the API. Filters by customer_api_key.
partner_name
string
The name of the data partner you will receive a product response from. Products that interact with partner integrations in the service endpoint operation should send this field.
elapsed_time
string
The measured duration of an event. The time is expressed in seconds.
Response 400application/json
1 fields
Error Response.
Field
Type
Description
message
string
Error message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 504application/json
1 fields
504 Timeout response.
Field
Type
Description
message
string
Endpoint request timed out
GET/metric/{transaction_id}
Retrieve Metrics by Transaction ID
get_metrics
Retrieve Metrics by transaction_id
Retrieve all health reports for specified transaction_id
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
application/json
Error while retrieving metrics.
{
"message": "Internal server error"
}
Parameters
8
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API key
transaction_idrequired
string (uuid)path
3cd0ffab-6e87-40a8-bc84-697155131f4c
An Identifier for a Transaction in Staircase.
next_token
stringquery
000000000000
The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.)
product_name
stringquery
Code
filters by concrete product name.
host_environment
stringquery
health.staircaseapi.com
filters by host environment.
status
stringquery
succeeded
filters by status. Available values: failed, succeeded
service_endpoint
stringquery
/transactions
filters by service endpoint
method
stringquery
GET
filters by Http Methods. Available values DELETE GET PATCH POST PUT
Response 200application/json
1 fields
Ok.
Field
Type
Description
metrics
object[]
Response Body
host_environment
string
Environment host where the product is deployed.
service_endpoint
string
The service endpoint URL that executed an operation, process, or function in the product. Endpoints with path parameters cannot be sent with real values, it must be sent as variables. Example /metric/%7Btransaction_id%7D and /metric are service endpoints of the Health product.
product_name
string
The system that is exposed externally to customers and performs the action. Examples Assess, Build, Employment.
metric_type
string
The type of metric options allowed logging | transaction
logging_message
string
This field is only available for metric_type logging. It is used for logging purpose.
created_at
string
A collection in Staircase is a container for the elements that a product needs to execute. For example, an AUS collection is a digital representation of a loan application, while a Data Extraction collection is a digital representation of a document.
operation_status
string
The status of an operation given the nature of the actions performed by the service and the transaction result. The service endpoint operation could be successful but the transaction_id could have different status given certain conditions and other operations performed.
transaction_id
string
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
severity
string
Severity e.g. (HIGH, MEDIUM, LOW)CRITICALDEBUGERRORHIGHINFOLOWMEDIUMWARNING
customer_api_key
string
It is the key required in order to use the API. Filters by customer_api_key.
partner_name
string
The name of the data partner you will receive a product response from. Products that interact with partner integrations in the service endpoint operation should send this field.
Response 400application/json
1 fields
Error Response.
Field
Type
Description
message
string
Error message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 500application/json
1 fields
Error while retrieving metrics.
Field
Type
Description
message
string
Response Body
Response 504application/json
1 fields
504 Timeout response.
Field
Type
Description
message
string
Endpoint request timed out
Health Metrics
POST/metrics
Create Health Metric
create_health_metric
Create New Health Metric.
Health Metric
Product Identifier
A product is an entity in the ontology. Product identifiers can be retrieved from Marketplace after product registration. Please visit Marketplace for product registration.
Product Api Identifier
API can be referenced by unique ID under products. Please visit Marketplace for API registration.
Transaction ID
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
Show the rest
Response Collection ID
A response collection in Staircase is a container for the elements that a product has as an output for its execution. Combination of transaction ID and response collection ID uniquely identifies an execution.
Status
Status
Description
REQUEST_MADE
Request received successful by API.
IN_PROGRESS
Invocation has not reached a final state.
SUCCEEDED
Invocation finished successfully.
FAILED
Invocation was not successful.
Elapsed Time
Amount of time that passes between the beginning of the request and the end of the invocation.
Invocation Code
The invocation code provides information for the invocation response. Codes and descriptions are given below. Please raise CR if needed invocation code is not listed here.
Invocation Code
Description
2000
OK. Invocation is successful
4000
BAD_REQUEST. The server cannot or will not process the request due to something that is perceived to be a client error.
4001
UNAUTHORIZED. The client is not authenticated to get the requested response.
4003
FORBIDDEN. The client is known but has no access rights to the content.
4004
NOT_FOUND. The server can not find the requested resource.
4009
CONFLICT. The request could not be completed due to a conflict with the current state of the target resource.
4013
PAYLOAD_TOO_LARGE. The request entity is larger than the limits defined by the server.
4022
UNPROCESSABLE_ENTITY. The request was well-formed but was unable to be followed due to semantic errors.
4029
TOO_MANY_REQUEST. The user has sent too many requests in a given amount of time.
5000
INTERNAL_SERVER_ERROR. The server has encountered a situation it does not know how to handle.
5004
TIMEOUT. This error response is given when the server cannot get a response in time.
6000
PARTNER_CALL_SUCCESS. Partner invocation returns a successful response.
PARTNER_CALL_ERROR_TIMEOUT. The partner did give the response in the given time.
6003
PARTNER_CALL_ERROR_TOO_MANY_REQUESTS. Partner called too many times in the amount of time that partner defined.
6004
PARTNER_CALL_ERROR_INVALID_PAYLOAD. Provided payload to the partner is invalid.
6005
PARTNER_CALL_ERROR_SERVICE_ERROR. Partner returns generic/unclassified service error.
6006
PARTNER_CALL_ERROR_NOT_FOUND The server cannot find the requested resource.
6007
PARTNER_CALL_ERROR_CONFLICT This response is sent when a request conflicts with the current state of the server.
7000
COLD_START. The server received the request successfully but had an initialization process before working on the client request.
7001
INTERNAL_OPERATION_THRESHOLD_EXCEEDED. The server could not finish the internal operation at the given threshold. The threshold can be duration, coverage, etc.
7002
INTERNAL_OPERATION_FAILED. The server completed transaction but had failure in the internal operation.
7003
OVERHEAD. Metric for measuring overhead on given service.
8000
SITE_SESSION_INITIATED. Metric for measuring Site Sessions.
8001
SITE_PAGE_CHANGED. Metric for measuring Site page changes.
8002
CONSOLE_APP_LOADED. Metric for measuring Console App loads.
8003
CONSOLE_APP_USED_DATA. Metric for calculating if Console App used prepopulated data.
9001
EMAIL_SEND. Email send. The send request was successful and the email provider will attempt to deliver the message to the recipient’s mail server.
9002
EMAIL_DELIVERY. Email delivery. The email provider successfully delivered the email to the recipient’s mail server.
9003
EMAIL_OPEN. Email open. The recipient received the message and opened it in their email client.
9004
EMAIL_CLICK. The recipient clicked one or more links in the email.
9400
EMAIL_DELIVERY_DELAY. The email couldn’t be delivered to the recipient’s mail server because a temporary issue occurred.
9401
EMAIL_UNSUBSCRIBE. The email was successfully delivered, but the recipient updated their subscription preferences by clicking on an unsubscribe link.
9403
EMAIL_COMPLAINT. The email was successfully delivered to the recipient’s mail server, but the recipient marked it as spam.
9500
EMAIL_REJECT. The email provider accepted the email but determined that it contained a virus and didn’t attempt to deliver it to the recipient’s mail server.
9501
EMAIL_BOUNCE. The recipient’s mail server permanently rejected the email.
9502
EMAIL_RENDERING_FAILURE. The email wasn’t sent because of a template rendering issue.
Product Build Hash
The builder generates a hash value after every product build. The hash value indicates which build version the metric comes from. Please check Builder documentation for details and how to get the build hash.
Unique product api identifierExample 548070b4-6ea7-459e-9746-5020446b3a73
transaction_idrequired
string
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.Example 3cd0ffa-6e87-40a8-bc84-697155131f4c
response_collection_idrequired
string (string)
A response collection in Staircase is a container for the elements that a product has as an output for its execution. Combination of transaction ID and response collection ID uniquely identifies a single execution.Example 01F2MHXNNNVK02YEY63Q5EQ59T
statusrequired
string
Indicates status of the process.FAILEDIN_PROGRESSREQUEST_MADESUCCEEDEDExample SUCCEEDED
elapsed_timerequired
number
The measured duration of an event. The time is expressed in seconds.Example 120.27
invocation_coderequired
string
Product invocation response code. For more information please check invocation code mapping.Example 6001
configuration_id
string
Product configuration ID.
product_build_hash
string
Hash value that generated from builder.
campaign_id
string
Campaign ID
user_agent
string
Optional. Represents actor's user agent. This will not be derived from the request headers if omitted.Example Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3
person_guid
string
Person GUID
phone_call_callback_number
string
Callback number
virtual_phone_number
string
To phone number
communication_identifier
string
From phone number
call_center_number
string
Call center number
lead_identifier
string
Lead identifier
voice_transcription
string
The text representation of the spoken audio, transcribed from voice input.
sms_text
string
The SMS text that we received.
x-sc-trace-id
string
Id to trace all transactions related. It will be generated automatically if not provided.
Response 201application/json
2 fields
Ok.
Field
Type
Description
id
string
Unique metric id.
message
string
Message the metric was successfully created
Response 400application/json
1 fields
Failed Creation.
Field
Type
Description
message
string
Message reason why the creation has failed
Response 403application/json
1 fields
Forbidden
Field
Type
Description
message
string
Error message
Response 422application/json
2 fields
Unprocessable Entity
Field
Type
Description
message
string
Error message
error
string
Error
POST/metrics/query
Create Asynchronous Health Metric Query
create_async_health_query_execution
Create Asynchronous Health Query Execution
Query Execution
Create Asynchronous Health Metric Query creates and executes the query immediately, for the query status and results invoke Get Asynchronous Health Metric Query Result.
If you invoke multiple times Get Asynchronous Health Metric Query Result for the same query_id you will receive the same results set that was created during the (first) execution.
Each execution of Create Asynchronous Health Metric Query creates a new query and result set.
Limits
Limit
Value
Concurrent Query Execution
20 query execution per second
Timezone
The Health product uses the timezone Eastern Standard Time (UTC-5). Please specify the include_timezone field in the query configuration to get time with timezone information included.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
Parameters
2
Parameter
Type
Example
Description
x-sc-trace-idrequired
stringheader
01GYYMHV78DVPV5TSHPQTJ31X9
Trace ID
x-api-keyrequired
stringheader
<redacted>
API key
Request bodyapplication/json
22 fields
Field
Type
Description
product_identifier
one of
Product identifier
product_api_identifier
one of
Product api identifier
transaction_id
one of
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
response_collection_id
one of
A response collection in Staircase is a container for the elements that a product has as an output for its execution. Combination of transaction ID and response collection ID uniquely identifies a single execution.
invocation_code
one of
Code that indicates invocation response
status
one of
Indicates status of the process.
configuration_id
one of
Product configuration ID.
product_build_hash
one of
Hash value that generated from builder.
campaign_id
one of
campaign_id from metric body.
user_agent
one of
user_agent from metric body.
person_guid
one of
person_guid from metric body.
phone_call_callback_number
one of
callback number from metric body.
virtual_phone_number
one of
virtual_phone_number number from metric body.
call_center_number
one of
call_center_number number from metric body.
lead_identifier
one of
lead_identifier from metric body.
communication_identifier
one of
phone number from metric body.
voice_transcription
one of
The text representation of the spoken audio, transcribed from voice input.
query_configuration
object
Query configuration
include_timezone
boolean
Includes timezone info and update date format to ISO8601.
include_host_environment
boolean
Includes environment domain info to result set.
callback_url
string (uri)
When query execution is done, this url will be called with resultExample https://webhook.com/callback
start_daterequired
string
Datetime must be in ISO8601 format.Example 2021-08-13T00:00:00
end_daterequired
string
Datetime must be in ISO8601 format. Should be later than `start_date`Example 2021-08-13T23:59:59
x-sc-trace-id
string
Id to trace all transactions related.Example 041fe98-4005-438d-9e14-5849ed8d6cc6
Response 201application/json
2 fields
Ok.
Field
Type
Description
query_id
string
Unique identifier for running query execution
status
string
Status of the query execution
Response 400application/json
1 fields
Failed Creation.
Field
Type
Description
message
string
Message reason why the creation has failed
Response 403application/json
1 fields
Forbidden
Field
Type
Description
message
string
Error message
Response 422application/json
2 fields
Unprocessable Entity
Field
Type
Description
message
string
Error message
error
string
Error
GET/metrics/query/{query_id}
Get Asynchronous Health Metric Query Result
get_async_health_query_result
The service retrieves a list of metrics by given query id. To retrieve all results, send the next_token provided on the previous call until next_token does not appear in the response.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
text/html
Not found.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>404 Not found</h1></center>\r\n</body>\r\n</html>\r\n
Parameters
6
Parameter
Type
Example
Description
x-sc-trace-idrequired
stringheader
01GYYMHV78DVPV5TSHPQTJ31X9
Trace ID
query_idrequired
stringpath
1fc23e2-b13e-405a-a3de-a5228950e3b8
Unique query execution id
x-api-keyrequired
stringheader
<redacted>
API key
limit
integerquery
150
The number of results to return in this request.
next_token
stringquery
000000000000
The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.)
query_idrequired
stringpath
query_id_1
Query ID received previously with asynchronous query creation
Response 200application/json
4 fields
Ok.
Field
Type
Description
status
string
Status of the query executionFAILEDIN_PROGRESSSUCCEEDEDExample SUCCEEDED
result_csv_file
string
Url for query result in CSV formatExample https://athena-query-results-293107503335.s3.amazonaws.com/1cf6527c-95cc-4998-b273-d3f4b9dd8014.csv?%2Fol&Expires=1661502173
next_token
string
Indicates next page exist. Using this token next page can retrieve.Example QVdMejZQT0gzY1I5ZmZCOXF2V1NlQW1Za2xITTNRYWtiVFViRUswYUVScWk2ZFJ3Q0xRRFFaQkx0QXVNVlU3K0JvZU8yTDIzc0RCSGNlcGg0TE5ZdExIeWJNeDlidDBSNkE9PQ==
Unique product api identifier.Example 548070b4-6ea7-459e-9746-5020446b3a73
transaction_id
string
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business. A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.Example 3cd0ffa-6e87-40a8-bc84-697155131f4c
response_collection_id
string
A response collection in Staircase is a container for the elements that a product has as an output for its execution. Combination of transaction ID and response collection ID uniquely identifies a single execution.Example 01F2MHXNNNVK02YEY63Q5EQ59T
elapsed_time
number
The measured duration of an event. The time is expressed in seconds.Example 14.55
status
string
Indicates status of the process.Example IN_PROGRESS
Group values with a given field.
Allowed field names:
product_identifier
product_api_identifier
transaction_id
response_collection_id
status
invocation_code
configuration_id
product_build_hash
Methods
Allows applying methods on filtered and grouped results. Methods are defined and applicable according to filed names.
row is a special keyword for representing a single row in the result set.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
Parameters
2
Parameter
Type
Example
Description
x-sc-trace-idrequired
stringheader
01GYYMHV78DVPV5TSHPQTJ31X9
Trace ID
x-api-keyrequired
stringheader
<redacted>
API key
Request bodyapplication/json
6 fields
Field
Type
Description
daterequired
object
Date filter and interval specification
start_daterequired
string
If provided, filters by start_date it must be used together with the end_date. Date must be in ISO8601 format.Example 2021-08-13T00:00:00
end_daterequired
string
If provided, filters by end_date it must be used together with the start_date. Date must be in ISO8601 format.Example 2021-08-13T23:59:59
interval
object
Date interval
typerequired
string
Interval typedayhourminutesecondExample minute
valuerequired
integer
Interval valueExample 1
filters
object[]
List of filters
field_namerequired
string
Filter field nameconfiguration_idinvocation_codeproduct_api_identifierproduct_build_hashproduct_identifierresponse_collection_idstatustransaction_idExample status
field_valuerequired
string
Filter field valueExample FAILED
operatorrequired
string
The operator that will be used for comparison=
group_byrequired
string[]
Field names that will be used for grouping
methods
object[]
Methods that will be applied to grouped metrics
method_namerequired
string
Method nameAVGCOUNTSUMExample COUNT
field_namerequired
string
Field nameconfiguration_idelapsed_timeinvocation_codeproduct_api_identifierproduct_build_hashproduct_identifierresponse_collection_idrowstatustransaction_idExample row
callback_url
string (uri)
When query execution is done, this url will be called with resultExample https://webhook.com/callback
query_configuration
object
Query configuration
include_timezone
boolean
Includes timezone info and update date format to ISO8601.
include_host_environment
boolean
Includes environment domain info to result set.
Response 201application/json
2 fields
Ok.
Field
Type
Description
query_id
string
Unique identifier for running query execution
status
string
Status of the query execution
Response 400application/json
1 fields
Failed Creation.
Field
Type
Description
message
string
Message reason why the creation has failed
Response 403application/json
1 fields
Forbidden
Field
Type
Description
message
string
Error message
Response 422application/json
2 fields
Unprocessable Entity
Field
Type
Description
message
string
Error message
error
string
Error
GET/metrics/aggregation/query/{query_id}
Get Health Aggregation Query Result[new]
get_aggregated_health_query_result
Get Health Aggregation Query Result
The service retrieves aggregated metric query result. To retrieve all results, send the next_token provided on the previous call until next_token does not appear in the response.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
text/html
Not found.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>404 Not found</h1></center>\r\n</body>\r\n</html>\r\n
Parameters
5
Parameter
Type
Example
Description
x-sc-trace-idrequired
stringheader
01GYYMHV78DVPV5TSHPQTJ31X9
Trace ID
x-api-keyrequired
stringheader
<redacted>
API key
limit
integerquery
150
The number of results to return in this request.
next_token
stringquery
000000000000
The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.)
query_idrequired
stringpath
query_id_1
Query ID received previously with asynchronous query creation
Response 200application/json
4 fields
Ok.
Field
Type
Description
status
string
Status of the query executionFAILEDIN_PROGRESSSUCCEEDEDExample SUCCEEDED
result_csv_file
string
Url for query result in CSV formatExample https://athena-query-results-293107503335.s3.amazonaws.com/1cf6527c-95cc-4998-b273-d3f4b9dd8014.csv?%2Fol&Expires=1661502173
next_token
string
Indicates next page exist. Using this token next page can retrieve.Example QVdMejZQT0gzY1I5ZmZCOXF2V1NlQW1Za2xITTNRYWtiVFViRUswYUVScWk2ZFJ3Q0xRRFFaQkx0QXVNVlU3K0JvZU8yTDIzc0RCSGNlcGg0TE5ZdExIeWJNeDlidDBSNkE9PQ==
{
"error": "metric_type test_nnn does not exist "
}
application/json
Error Response
{
"error": "123 is not of type 'string'\n\nFailed validating 'type' in schema['properties']['product']['properties']['place']:\n {'type': 'string'}\n\nOn instance['product']['place']:\n 123"
}
text/html
Error Response
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API key
Request bodyapplication/json
5 fields
Field
Type
Description
product
object
Metric object
sin
string
Metric field example
place
string
Metric field example
address
string
Metric field example
techno
integer[]
Metric field example
metric_typerequired
string
Metric field example
name
string
Metric field example
Response 201application/json
1 fields
Created Response
Field
Type
Description
resp
string
Response
Response 400application/json
1 fields
Error Response
Field
Type
Description
error
string
Error Response
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
PUT/put-metric-type
Update Metric Type
update_metric_type
This service update an existing metric type and its fields, allowing the customer to update their own metrics based on events when a metric is posted to the Health.
This service update an existing metric type and its fields, allowing the customer to update their own metrics based on events when a metric is posted to the Health.
This service update an existing metric type and its fields, allowing the customer to update their own metrics based on events when a metric is posted to the Health /post-metric service.
The metric type name is the main reference. The field names can be reference to build a new report.
{
"message": "the metric_type was successfully updated"
}
application/json
Error response
{
"error": "error updating metric type: metric_type_name is a required field "
}
text/html
Error response
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
<redacted>
Key
Request bodyapplication/json
2 fields
Field
Type
Description
schema
object
The metric type schema
type
string
Type declaration example
required
string[]
Required array. All the field which are required in the schema
properties
object
Example fields
product
object
Example fields
type
string
Example type
properties
object
Example fields
address
object
Example fields
type
string
Example type
techno
object
Example Array Field
type
string
Example type
items
object
Example Field
name
object
Example Field
type
string
Example type
metric_type_name
string
Unique identifier of the metric type
Response 201application/json
1 fields
Metric type created response
Field
Type
Description
message
string
Message
Response 400application/json
1 fields
Error response
Field
Type
Description
error
string
Error
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 504application/json
1 fields
504 Timeout response.
Field
Type
Description
message
string
Endpoint request timed out
POST/create-metric-type
Create Metric Type
create_new_metric_type
This service defines a metric type and its fields, allowing the customer to create their own metrics based on events when a metric is posted to the Health.
This service defines a metric type and its fields, allowing the customer to create their own metrics based on events when a metric is posted to the Health /post-metric service.
The metric type name is the main reference. The field names can be reference to build a new report.
{
"message": "the new metric_type was successfully created"
}
application/json
Error response
{
"error": "error creating metric type: metric_type_name is a required field "
}
text/html
Error response
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
<redacted>
Key
Request bodyapplication/json
2 fields
Field
Type
Description
schema
object
The metric type schema
type
string
Type declaration example
required
string[]
Required array. All the field which are required in the schema
properties
object
Example fields
product
object
Example fields
type
string
Example type
properties
object
Example fields
address
object
Example fields
type
string
Example type
techno
object
Example Array Field
type
string
Example type
items
object
Example Field
name
object
Example Field
type
string
Example type
metric_type_name
string
Unique identifier of the metric type
Response 201application/json
1 fields
Metric type created response
Field
Type
Description
message
string
Message
Response 400application/json
1 fields
Error response
Field
Type
Description
error
string
Error
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 504application/json
1 fields
504 Timeout response.
Field
Type
Description
message
string
Endpoint request timed out
Environments Data
POST/register-env
Register Environment and API Key
store_new_environment_credentials
Register the environment and api key the customer wants to get in reports.
Register the environment and API key, this will allow Health to retrieve data from one environment to another. The data is migrated daily, the customer can retrieve reports from local and other registered environments.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API key
Request bodyapplication/json
2 fields
Field
Type
Description
hostrequired
string
The environment hostExample health.staircaseapi.com
api-keyrequired
string (api-key)
The api-key used in order to access APIs in the hostExample xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Response 201application/json
1 fields
Ok.
Field
Type
Description
message
string
The environment was stored successfully
Response 400application/json
1 fields
400 response.
Field
Type
Description
message
string
Error in storing the environment invalid host
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 500application/json
1 fields
500 response.
Field
Type
Description
message
string
Internal server error
Response 504application/json
1 fields
504 Timeout response.
Field
Type
Description
message
string
Endpoint request timed out
Report Subscription
POST/report-subscription
Create Report Subscription
report-subscription
Subscription to receive a report through Slack notification.
Subscription to receive a report through Slack notification. Specify the period either by days, week, or month, and the filters to apply.
You can subscribe to the following reports:
Partner Report: Subscribe to receive the Partner report. See this link for more information.
Products by operation status: Subscribe to receive the Product By Operation Status Report. See this link for more information.
Summary Reports: Subscribe to receive the Summary Report by Status. See this link for more information.
Products by unique transactions report: Subscribe to receive the Unique Transactions By Product Report. See this link for more information.
Custom reports created in the service /build-report
The Slack media type is currently allowed. A token must be provided to send the notification. After the subscription, the user will receive the report through a post with the results in the configured period.
Follow this link to choose or create new apps in Slack. Use the app token "Bot User OAuth Token"
{
"error": "period field is invalid. format allowed: <number>d, <number>w, <number>m "
}
application/json
Subscription error response
{
"error": "the Subscription solo already exists"
}
application/json
Subscription error response
{
"error": "There is no custom report with the name: cabuc"
}
text/html
Subscription error response
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API key
Request bodyapplication/json
11 fields
Field
Type
Description
subscription_namerequired
string
Unique Identifier of the Subscription
group_by
string
Option to retrieve unique transactions by field transaction_id, request_collection_id or response_collection_id. It is only used in report type product_by_operation_status or partner report
periodrequired
string
The period is sent using d for days, w for weeks and m for months, the number always goes first e.g. 3w
cronrequired
string
The scheduler definition is required for cumulative reports. Currently, supports only daily reports. Example of scheduler definition "0 9,16 * * *" → Get report between 00:00 - 09:00 and 00:00 - 16:00 for every day.
environments
string[]
Environments
send_to_idrequired
string
Slack channel name or Member ID (For private DM)
mediarequired
string
The only type allowed at the moment is slack
products
string[]
List of products used in the query to build the reports which will be sent
partners
string[]
List of partners (only for report_type = partner_report) used in the query to build the reports which will be sent
token
string
In order to use it to send reports through slack this Field is required, the app token must be authorized in the User Token Scopes with files:write
report_type
string
The report name (partner_report, summary_report, product_by_operation_status and product_unique_transactions_report) or Custom report name
Response 201application/json
1 fields
Subscription success response
Field
Type
Description
message
string
Message
Response 400application/json
1 fields
Subscription error response
Field
Type
Description
error
string
Error
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
POST/error-subscription
Create Error Report Subscription
create_error_subscription
This service sends a notification when an error is posted for a product service endpoint in Health.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
<redacted>
Key
Request bodyapplication/json
5 fields
Field
Type
Description
subscription_name
string
Unique Identifier of the Subscription
send_to_id
string
Slack channel name or Member ID (For private DM)
media
string
The only type allowed at the moment is slack
products
string[]
List of products used in the query to build the reports which will be sent
token
string
In order to use it to send reports through slack this Field is required, the app token must be authorized in the User Token Scopes with files:write
Response 201application/json
1 fields
Success Response
Field
Type
Description
message
string
Message
Response 400application/json
1 fields
Error Response
Field
Type
Description
error
string
Error
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
DELETE/delete-subscription/{subscription_id}
Delete Report Subscription
delete_subscription_id
This service allows removing a notification subscription.
This service allows removing a notification subscription, the subscription name must be provided. After deleting the subscription, the notification will not be received through slack.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
text/html
Not found.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>404 Not found</h1></center>\r\n</body>\r\n</html>\r\n
Parameters
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Key
subscription_idrequired
stringpath
MNe
Unique identifier of a subscription which will be deleted.
This service allows removing a notification subscription.
This service allows removing a notification subscription, the subscription name must be provided. After deleting the subscription, the notification will not be received through Slack.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
text/html
Not found.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>404 Not found</h1></center>\r\n</body>\r\n</html>\r\n
Parameters
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Key
subscription_idrequired
stringpath
MNe
Unique identifier of a subscription which will be deleted.
Response 200application/json
1 fields
Auto generated using Swagger Inspector
Field
Type
Description
message
string
Message
Response 400application/json
1 fields
Bad request.
Field
Type
Description
error
string
Error message.
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 404application/json
1 fields
Not found.
Field
Type
Description
error
string
Error message.
GET/get-subscriptions
Retrieve All Report Subscriptions
get_all_subscription
It retrieves a list of subscriptions registered, all subscriptions send a notification with the report type selected, the method, and the send_to_id.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Key
Response 200application/json
2 fields
Subscription data.
Field
Type
Description
subscriptions
object[]
Subscription data.
period
string
Period.
cron
string
Period.
send_to_id
string
ID where it will be sent.
subscription_name
string
Unique identifier of the subscription.
media
string
Slack the only value allowed at the moment.
report_type
string
Type of the report.
query_info
object
Filters detail
customer_x_api_key
string
It is the key required in order to use the API. Filters by customer_api_key.
environments
string[]
Environments
products
string[]
List of products used in the query to build the reports which will be sent
error_subscriptions
object[]
Error Subscriptions
subscription_name
string
Unique identifier of the subscription.
send_to_id
string
ID where it will be sent.
query_info
object
Filters detail
products
string[]
List of products for error metrics.
media
string
Slack the only value allowed at the moment.
Response 400application/json
1 fields
400 Bad Request
Field
Type
Description
error
string
Error message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Reports
GET/summary_report_by_status
Retrieve Summary Report by Status
get_report_summary_report_by_status
This report brings the total number of metrics by status.
This report brings the total number of metrics by status. You can get the following information about your products by using this report:
The metrics posted for per product
The metrics that succeeded per product.
The metrics that failed, this means that an error or exception occurred in the product while processing one of the services.
{
"message": "error: end_date is a required field"
}
text/html
Error response
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
6
Parameter
Type
Example
Description
start_daterequired
stringquery
2021-04-01
Filters by start_date it must be used together with the end_date. Date must be in ISO8601 format: YYYY-MM-DD
end_daterequired
stringquery
2021-05-30
Filters by end_date. Date must be in ISO8601 format: YYYY-MM-DD
environments
stringquery
account.staircaseapi.com,health.staircaseapi.com
List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports.
products
stringquery
employment,income
List of product names to filter, the report will bring all product names if this input is not available.
next_token
stringquery
000000000000
The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.)
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API key
Response 200application/json
1 fields
Example Success Response
Field
Type
Description
report
object
report
Items
object[]
Items
total
integer
Total
host_env
string
Environment
product_name
string
Product name
succeeded
string
Succeeded
failed
string
Failed
Next_token
string
Next token pagination purpose
Response 400application/json
1 fields
Error response
Field
Type
Description
message
string
Error Message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 500application/json
1 fields
500 response.
Field
Type
Description
message
string
Internal server error
GET/partner_report
Retrieve Partner Report
get_report_partner_report
This report retrieves the number of transactions and the last operation status by partner in the given timeframe period.
The Mortgage products operations with a data partner are registered from the beginning of the transaction until it is completed. This report retrieves the number of transactions and the last operation status by partner in the given timeframe period.
The data will be aggregated between all environments registered. See this link for more information.
{
"message": "error: end_date is a required field"
}
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
7
Parameter
Type
Example
Description
start_daterequired
stringquery
2021-05-01
Filters the data by a range of dates starting with this date. Date must be in ISO8601 format: YYYY-MM-DD
end_daterequired
stringquery
2021-05-31
Filters the data until this date. Date must be in ISO8601 format: YYYY-MM-DD
environments
stringquery
documentation.staircaseapi.com
List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports.
products
stringquery
employment,income
List of product names to filter, the report will bring all product names if this input is not available.
group_by
stringquery
request_collection_id
Option to retrieve unique transactions by field transaction_id, request_collection_id or response_collection_id.
partners
stringquery
atomic,citadel
The name of the data partners in Mortgage products.
x-api-key
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Key
Response 200application/json
1 fields
Success Response
Field
Type
Description
report
object
Report
Items
object[]
Items
total
integer
Total
partner
string
Partner
product_name
string
Product name
total_by_status
object
Total
COMPLETED
integer
Operation status
Response 400application/json
1 fields
Auto generated using Swagger Inspector
Field
Type
Description
message
string
Message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 504application/json
1 fields
504 Timeout response.
Field
Type
Description
message
string
Endpoint request timed out
GET/product_by_operation_status
Retrieve Product by Operation Status Report
get_report_product_by_operation_status
This report retrieves the number of transactions and the last operation's status for the given timeframe period.
Every single Staircase service endpoint (such as POST /persistence/transactions or POST /aus/underwrite) is required to provide operation status updates to denote the progress of a transaction in its execution. For more information and examples see this link
This report retrieves the number of transactions and the last operation's status for the given timeframe period.
{
"message": "error: end_date is a required field"
}
text/html
Error response
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
7
Parameter
Type
Example
Description
start_daterequired
stringquery
2021-04-01
Filters by start_date it must be used together with the end_date. Date must be in ISO8601 format: YYYY-MM-DD
end_daterequired
stringquery
2021-05-30
Filters by end_date. Date must be in ISO8601 format: YYYY-MM-DD
environments
stringquery
account.staircaseapi.com,health.staircaseapi.com
List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports.
products
stringquery
employment,income
List of product names to filter, the report will bring all product names if this input is not available.
group_by
stringquery
request_collection_id
Option to retrieve unique transactions by field transaction_id, request_collection_id or response_collection_id.
next_token
stringquery
000000000000
The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.)
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
API key
Response 200application/json
1 fields
Example Success Response
Field
Type
Description
report
object
Report
Items
object[]
Items
total
integer
Total
host_env
string
Environment
product_name
string
Product Name
IN PROGRESS
string
Operation Status
STARTED
string
Operation Status
Next_token
string
Next token pagination
Response 400application/json
1 fields
Error response
Field
Type
Description
message
string
Message
Response 403application/json
2 fields
403 response
Field
Type
Description
url
string
URL
message
string
Message
Response 500application/json
1 fields
500 response.
Field
Type
Description
message
string
Internal server error
GET/product_unique_transactions_report
Retrieve Unique Transactions By Product Report
get_report_product_unique_transactions_report
This report brings the total number of unique transactions by status and a breakdown per day.
This report brings the total number of unique transactions by status and a breakdown per day. We can have multiple metrics registered for the same transaction, this report will bring unique transaction id count.
You can get the following information about your products by using this report:
The transactions processed per product.
The transactions that were processed by a service endpoint and succeeded.
The transactions that were processed by a service endpoint and reported an exception or error.
{
"message": "error: end_date is a required field"
}
text/html
Error response
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
6
Parameter
Type
Example
Description
start_daterequired
stringquery
2021-04-01
Filters by start_date it must be used together with the end_date. Date must be in ISO8601 format: YYYY-MM-DD
end_daterequired
stringquery
2021-05-30
Filters by end_date. Date must be in ISO8601 format: YYYY-MM-DD
environments
stringquery
account.staircaseapi.com,health.staircaseapi.com
List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports.
products
stringquery
employment,income
List of product names to filter, the report will bring all product names if this input is not available.
next_token
stringquery
000000000000
The token for the next set of items to return. (You received this token from a previous call. If you have reached the end of the stream, the returned token is null.)
{
"message": "error: cost_category is a required field"
}
application/json
Error response
{
"message": "error: product_name is a required field"
}
application/json
Error response
{
"message": "error: start_date is a required field"
}
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
Parameters
6
Parameter
Type
Example
Description
end_daterequired
stringquery
2021-10-18
end_date
products
stringquery
employment,income
List of product names to filter
cost_categoryrequired
stringquery
customer
Cost Category (customer, partner)
start_daterequired
stringquery
2021-10-12
start_date
environments
stringquery
account.staircaseapi.com,health.staircaseapi.com
List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports.
{
"message": "error: cost_category is a required field"
}
application/json
403 response
{
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post",
"message": "This key is not valid for this service."
}
{
"message": "error: end_date is a required field"
}
application/json
Error response
{
"message": "error: cost_category is a required field"
}
application/json
Error response
{
"message": "error: product_name is a required field"
}
Parameters
7
Parameter
Type
Example
Description
end_daterequired
stringquery
2021-10-18
end_date
products
stringquery
employment,income
List of product names to filter
cost_categoryrequired
stringquery
customer
Cost Category (customer, partner)
start_daterequired
stringquery
2021-10-12
start_date
date_range_type
stringquery
daily
Allows grouping costs by selected date type.
environments
stringquery
account.staircaseapi.com,health.staircaseapi.com
List of host environment to filter, the report will bring all environments if this input is not available. Only configured environments will be included in the reports.
