<!-- https://staircase.co/platform/data/language -->
# Language

# Language

Bidirectional translation between a caller's own field vocabulary and the canonical model, at single-record and bulk scale.

A language is a registered mapping. Language carries the registry, generates and validates rulesets, translates records in both directions, and exposes graph queries in a form a caller can send as structured data rather than as a query language.

Bulk translation runs on a Spark cluster. The measurement on record is 7,848 translations in 299 seconds across 20 executors.

## How it works

This is the mechanism behind any caller keeping its own field names without per-caller code. A vendor's vocabulary and a lender's vocabulary are the same kind of object here — both are registered languages over the same model — which is why the agency mappings sit in the registry alongside the customer ones.

The payoff shows up in validation. A required-field rule declared once at the model surfaces to each caller against that caller's own paths, because the translation runs over the error as well as over the data.

## Operations

<!--source:api-specifications-->

### Lexicon
<!--/source-->

`POST` `/build-payload`

<!--source:api-specifications-->

#### Build Payload
<!--/source-->

`buildPayload`

<!--source:api-specifications-->
Build Payload builds a payload based on provided JSONPaths and values.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "$.deal_sets[0].parties[0].individual.first_name": "John",
 "$.deal_sets[0].parties[0].roles[0].party_type": "Borrower",
 "$.deal_sets[0].parties[0].roles[0].employers[0].legal_entity_name": "Truework Inc",
 "$.deal_sets[0].parties[0].taxpayer_identifiers[0].value": "999-00-0000"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403
<!--/source-->

<!--source:api-specifications-->
application/json Copy 200 response

```
{
 "deal_sets": {
 "deal_set": [
 {
 "deals": {
 "deal": [
 {
 "parties": {
 "party": [
 {
 "individual": {
 "name": "John"
 },
 "roles": {
 "role": [
 {
 "role_detail": {
 "party_type": "Borrower"
 },
 "borrower": {
 "employers": {
 "employer": [
 {
 "legal_entity": {
 "legal_entity_detail": {
 "full_name": "Truework Inc"
 }
 }
 }
 ]
 }
 }
 }
 ]
 },
 "taxpayer_identifiers": {
 "taxpayer_identifier": [
 {
 "type": "EmployerIdentificationNumber",
 "value": "999-00-0000"
 }
 ]
 }
 }
 ]
 }
 }
 ]
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Other responses

`200`

`PUT` `/lexicon`

<!--source:api-specifications-->

#### Create/Update Staircase Lexicon
<!--/source-->

`createUpdateStaircaseLexicon`

<!--source:api-specifications-->
Create/Update Staircase Lexicon - for translation between versions
<!--/source-->

<!--source:api-specifications-->
Create/Update Staircase Lexicon replaces mappings for a staircase-to-staircase language.

Replaces previously created mappings - can be in .csv or .json format.

- Lexicon naming based on sc_version_from, sc_version_to params:
- For .csv-based languages - use query parameters.
```
Example: ?sc_version_from=0&sc_version-to=2
```

- For .json-based languages - use .json payload.
```
Example: sc_versions: {sc_version_from: 0, sc_version_to: 2}
```

Translates between Staircase language versions, and is internally named VX_TO_VY - where X is lower, Y is higher version. FromPath and ToPath definitions are defined by sc_version_from and sc_version_to in lexicon definition.

Show the rest Example: Lexicon: V0_TO_V2

Lexicon writer initially writes a lexicon from V0 to V2 - in this case sc_version_from = 0, sc_version_to = 2. Later, wants to add detail, etc. and defines lexicon from V2 to V0. In this case, new lexicon overwrites existing one with same name: V0_TO_V2 - in this case, however, internal definition shows sc_version_from = 2 and sc_version_to = 0.

During runtime, incoming payload indicates sc_version_from and sc_version_to. Forward translation is done if versions match, reverse translation otherwise.

When retrieving Lexicon - must pay close attention to directionality contained within language definition to determine how lexicon was originally written.

Guide for building a .csv-based language

Guide for building a .json-based language

Retrieve a pre-built language to understand how they are constructed.

If the language is given in .csv format, which is more straightforward and can be built by a business analyst, Translator converts the .csv file into the more technical .json format.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "content_type": "application/json",
 "mapping": {
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].date": "$.bundle[0].date",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].high_value_range": "$.bundle[0].upper",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range": "$.bundle[0].lower",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].value": "$.bundle[0].zestimate"
 },
 "values_mapping": [
 {
 "element": "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range",
 "mapping": [
 {
 "language_value": "FooBar",
 "staircase_value": "HelloWorld"
 },
 {
 "language_value": "WorldHello",
 "staircase_value": "BarBaz"
 }
 ]
 }
 ],
 "sc_versions": {
 "sc_version_from": 0,
 "sc_version_to": 2
 }
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
400403
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
2
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `sc_version_from` required | `integer` query | `1` | <!--source:api-specifications-->.csv-only - staircase-to-staircase language - from version<!--/source--> |
| `sc_version_to` required | `integer` query | `1` | <!--source:api-specifications-->.csv-only - staircase-to-staircase language - to version<!--/source--> |

##### Request body`application/json`

<!--source:api-specifications-->
6 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `mapping`required | `object` | <!--source:api-specifications-->Mapping object<!--/source--> |
| `values_mapping`required | `object[]` | <!--source:api-specifications-->Value mapping array<!--/source--> |
| `element`required | `string` | <!--source:api-specifications-->Value mapping element<!--/source--> |
| `mapping` | `object[]` | <!--source:api-specifications-->Value mapping array<!--/source--> |
| `staircase_value`required | `string` | <!--source:api-specifications-->Staircase value string<!--/source--> |
| `language_value`required | `string` | <!--source:api-specifications-->Language value string<!--/source--> |
| `unique_arrays` | `object` | <!--source:api-specifications-->Key-value pairs, where key is JSONPath to array of objects, and value is key, that has been unique<!--/source--> |
| `merge_arrays` | `object` | <!--source:api-specifications-->Key-value pairs, where key is JSONPath to array which will contain merged elements, and value is an array, which contains JSONPaths to arrays that should be excluded from result and all their elements should be included to the JSONPath specified as a key.<!--/source--> |
| `content_type`required | `string` | <!--source:api-specifications-->Content type string<!--/source--> |
| `sc_versions`required | `object` | <!--source:api-specifications-->Staircase version object<!--/source--> |
| `sc_version_from`required | `integer` | <!--source:api-specifications-->Staircase version from<!--/source--> |
| `sc_version_to`required | `integer` | <!--source:api-specifications-->Staircase version to<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Other responses

`204``422``500`

`GET` `/elements/{element_path}`

<!--source:api-specifications-->

#### Retrieve Mappings for Element
<!--/source-->

`retrieveMapping`

<!--source:api-specifications-->
Retrieve Mappings for Element retrieves a list of mappings across all available languages for the specified element.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403
<!--/source-->

<!--source:api-specifications-->
application/json Copy List of mappings

```
{
 "lang-name": "$utils.split('$.address', ' ')[1]",
 "lang-name2": "$.address"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `element_path` required | `string` path | `%24.deal_sets%5B0%5D.collaterals%5B0%5D.address.city` | <!--source:api-specifications-->(*URLEncoded*)[] JSONPath to element is Staircase language<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Other responses

`200`

`GET` `/lexicon`

<!--source:api-specifications-->

#### Retrieve Single Staircase Lexicon
<!--/source-->

`retrieveSingleStaircaseLexicon`

<!--source:api-specifications-->
Retrieve Single Staircase Lexicon retrieves a Staircase lexicon name, mapping, and content type.

A lexicon translates between Staircase language versions, and is internally named VX_TO_VY - where X is lower, Y is higher version. FromPath and ToPath definitions are defined by sc_version_from and sc_version_to in lexicon definition.

Example: Lexicon: V0_TO_V2

Lexicon writer initially writes a lexicon from V0 to V2 - in this case sc_version_from = 0, sc_version_to = 2. Later, wants to add detail, etc. and defines lexicon from V2 to V0. In this case, new lexicon overwrites existing one with same name: V0_TO_V2 - in this case, however, internal definition shows sc_version_from = 2 and sc_version_to = 0.

During runtime, incoming payload indicates sc_version_from and sc_version_to. Forward translation is done if versions match, reverse translation otherwise.

When retrieving Lexicon - must pay close attention to directionality contained within language definition to determine how lexicon was originally written.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Language

```
{
 "name": "string",
 "mapping": {
 "$.foo": "$.bar",
 "$.biz": "$.baz"
 },
 "mapping_info": {
 "language_elements": {
 "coverage": "string",
 "mapped_count": 0,
 "unmapped_count": 0,
 "unmapped": [
 "string"
 ]
 },
 "staircase_elements": {
 "coverage": "string",
 "mapped_count": 0,
 "unmapped_count": 0,
 "unmapped": [
 "string"
 ]
 }
 },
 "values_mapping": [
 {
 "element": "string",
 "mapping": [
 {
 "staircase_value": "string",
 "language_value": "string"
 }
 ]
 }
 ],
 "required_fields": {
 "language_elements": [
 "string"
 ],
 "staircase_elements": [
 "string"
 ]
 },
 "sc_versions": {
 "sc_version_from": 0,
 "sc_version_to": 1
 },
 "content_type": "application/json"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Language not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
2
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `sc_version_from` required | `integer` query | `2` | <!--source:api-specifications-->Staircase version from<!--/source--> |
| `sc_version_to` required | `integer` query | `2` | <!--source:api-specifications-->Staircase version to<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
7 fields
<!--/source-->
<!--source:api-specifications-->
Language
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | <!--source:api-specifications-->Name<!--/source--> |
| `mapping` | `object` | <!--source:api-specifications-->Mapping object<!--/source--> |
| `mapping_info` | `object` | <!--source:api-specifications-->Mapping info object<!--/source--> |
| `language_elements` | `object` | <!--source:api-specifications-->Mapping info object - language elements<!--/source--> |
| `coverage` | `string` | <!--source:api-specifications-->Element coverage<!--/source--> |
| `mapped_count` | `number` | <!--source:api-specifications-->Element mapped count<!--/source--> |
| `unmapped_count` | `number` | <!--source:api-specifications-->Element unmapped count<!--/source--> |
| `unmapped` | `string[]` | <!--source:api-specifications-->Element unmapped array<!--/source--> |
| `staircase_elements` | `object` | <!--source:api-specifications-->Staircase element object<!--/source--> |
| `coverage`required | `string` | <!--source:api-specifications-->Element coverage<!--/source--> |
| `mapped_count`required | `number` | <!--source:api-specifications-->Element mapped count<!--/source--> |
| `unmapped_count`required | `number` | <!--source:api-specifications-->Element unmapped count<!--/source--> |
| `unmapped`required | `string[]` | <!--source:api-specifications-->Element unmapped array<!--/source--> |
| `values_mapping` | `object[]` | <!--source:api-specifications-->Value mapping array<!--/source--> |
| `element`required | `string` | <!--source:api-specifications-->Value mapping element<!--/source--> |
| `mapping` | `object[]` | <!--source:api-specifications-->Value mapping element<!--/source--> |
| `staircase_value` | `string` | <!--source:api-specifications-->Value mapping staircase value<!--/source--> |
| `language_value` | `string` | <!--source:api-specifications-->Value mapping language value<!--/source--> |
| `required_fields` | `object` | <!--source:api-specifications-->Required fields object<!--/source--> |
| `language_elements`required | `string[]` | <!--source:api-specifications-->Language's elements array<!--/source--> |
| `staircase_elements`required | `string[]` | <!--source:api-specifications-->Staircase's elements array<!--/source--> |
| `sc_versions` | `object` | <!--source:api-specifications-->Staircase version<!--/source--> |
| `sc_version_from`required | `integer` | <!--source:api-specifications-->Staircase version from<!--/source--> |
| `sc_version_to`required | `integer` | <!--source:api-specifications-->Staircase version to<!--/source--> |
| `content_type` | `string` | <!--source:api-specifications-->Content type<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`422`

<!--source:api-specifications-->

### Monitoring Dashboard
<!--/source-->

`GET` `/dashboard/configurations`

<!--source:api-specifications-->

#### Get Dashboard Configurations
<!--/source-->

`getDashboardConfigurations`

<!--source:api-specifications-->
**Retrieve registered dashboard configurations.

<!--/source-->

##### Response

<!--source:api-specifications-->
400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

##### Response `200``application/json`

<!--source:api-specifications-->
3 fields
<!--/source-->
<!--source:api-specifications-->
Configurations retrieved successfully
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `health_key` | `string` | <!--source:api-specifications-->Environment health key.<!--/source--> |
| `host_environment` | `string` | <!--source:api-specifications-->Environment domain name.<!--/source--> |
| `config_type` | `string` | <!--source:api-specifications-->Dashboard configuration type.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

`PUT` `/dashboard/configurations`

<!--source:api-specifications-->

#### Create Dashboard Configuration
<!--/source-->

`createDashboardConfiguration`

<!--source:api-specifications-->
The primary function of this service is to facilitate the configuration of a dashboard that is specifically designed to monitor language products within a specified environment. The data required for monitoring will be retrieved through the utilization of a Health key and the information obtained will be presented using the Console product. For further clarification on the practical application of this service, kindly refer to the views that are maintained by the Language team. It should be noted that data will be fetched on a daily basis, with the worker commencing at precisely 07:00 am (UTC).

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "health_key": "health-key",
 "host_environment": "lang.staircaseapi.com"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
201400403404422
<!--/source-->

<!--source:api-specifications-->
application/json Copy Configuration response

```
{
 "message": "Configuration created."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.

```
{
 "message": "Ruleset with name 'atomic_staircase-graph_TRANSLATE' cannot be deleted while it has rules. Please, delete all rules first and try again."
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `host_environment`required | `string` | <!--source:api-specifications-->Environment domain name.<!--/source--> |
| `health_key`required | `string` | <!--source:api-specifications-->Health key.<!--/source--> |

##### Response `201``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Configuration response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Endpoint result message.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `422``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

`DELETE` `/dashboard/configurations/{host_environment}`

<!--source:api-specifications-->

#### Delete Dashboard Configuration
<!--/source-->

`deleteDashboardConfiguration`

<!--source:api-specifications-->
This service removes configuration.

<!--/source-->

##### Response

<!--source:api-specifications-->
200403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Configuration response

```
{
 "message": "Configuration deleted."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `host_environment` required | `string` path | `lang.staircaseapi.com` | <!--source:api-specifications-->Environment domain name<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Configuration response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Endpoint result message.<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

<!--source:api-specifications-->

### EMR
<!--/source-->

`POST` `/emr`

<!--source:api-specifications-->

#### Start EMR Translation
<!--/source-->

`startEMRTranslation`

<!--source:api-specifications-->
Start new EMR translation
<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "input_bucket_name": "foo",
 "input_path": "data",
 "output_bucket_name": "bar",
 "from_language": "my_lang",
 "to_language": "lexicon"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully started the translation.

```
{
 "product_id": "test_product",
 "status": "operational"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Container not found"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
8 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `input_bucket_name`required | `string` | <!--source:api-specifications-->Bucket name where to take the input data from.<!--/source--> |
| `input_path`required | `string` | <!--source:api-specifications-->Prefix to data in the input bucket.<!--/source--> |
| `input_schema` | `object[]` | <!--source:api-specifications-->Fields names and datatypes.<!--/source--> |
| `Name` | `string` | <!--source:api-specifications-->Field name.<!--/source--> |
| `Type` | `string` | <!--source:api-specifications-->Field datatype.<!--/source-->`bigint``boolean``double``string` |
| `output_bucket_name` | `string` | <!--source:api-specifications-->Bucket name where to put the output data. Optional if datalake_name is provided.<!--/source--> |
| `from_language`required | `string` | <!--source:api-specifications-->Language to translate from.<!--/source--> |
| `to_language`required | `string` | <!--source:api-specifications-->Language to translate to.<!--/source--> |
| `datalake_name` | `string` | <!--source:api-specifications-->Mortgage data lake to use. Will be used to define output s3-location, tables for entities unification, and columns for output tables to save.<!--/source--> |
| `callback_url` | `string` | <!--source:api-specifications-->If specified, the URL will be called when Job is finished. We will send POST request to the URL with jobRunId, state and stateDetails in the request body as JSON.<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
3 fields
<!--/source-->
<!--source:api-specifications-->
Successfully started the translation.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `applicationId`required | `string` | <!--source:api-specifications-->applicationId<!--/source--> |
| `jobRunId`required | `string` | <!--source:api-specifications-->jobRunId<!--/source--> |
| `arn`required | `string` | <!--source:api-specifications-->arn<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Missing API key
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

`GET` `/fake`

<!--source:api-specifications-->

#### FakeEMR
<!--/source-->

`FooBar`

<!--source:api-specifications-->
Fake
<!--/source-->

<!--source:api-specifications-->
foo

<!--/source-->

##### Response

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Container not found"
}
```

<!--/source-->

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Missing API key
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Other responses

`204`

`GET` `/emr/{job_id}`

<!--source:api-specifications-->

#### Get EMR Translation status
<!--/source-->

`getEMRTranslation`

<!--source:api-specifications-->
EMR translation status
<!--/source-->

##### Response

<!--source:api-specifications-->
200404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Data about the EMR translation

```
{
 "product_id": "test_product",
 "status": "operational"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Container not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `job_id` required | `string` path | `00fdj7a1e1ai000a` | <!--source:api-specifications-->Job ID<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
6 fields
<!--/source-->
<!--source:api-specifications-->
Data about the EMR translation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `applicationId`required | `string` | <!--source:api-specifications-->ID of app<!--/source--> |
| `jobRunId`required | `string` | <!--source:api-specifications-->ID of current Job run<!--/source--> |
| `createdAt`required | `string` | <!--source:api-specifications-->Creation time of the job<!--/source--> |
| `updatedAt`required | `string` | <!--source:api-specifications-->Last update time of the job<!--/source--> |
| `state`required | `string` | <!--source:api-specifications-->Current state of the job<!--/source--> |
| `stateDetails`required | `string` | <!--source:api-specifications-->Details of the current state<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Missing API key
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

<!--source:api-specifications-->

### MDL
<!--/source-->

`POST` `/etl/jobs`

<!--source:api-specifications-->

#### Start MDL ETL JOB
<!--/source-->

`startMDLETLJob`

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "year": 2022,
 "month": 1,
 "day": 1,
 "datalake_name": "datalake"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully started the translation.

```
{
 "executionArn": "123"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Container not found"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
4 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `year` | `integer` | <!--source:api-specifications-->Year<!--/source-->Example `2022` |
| `month` | `integer` | <!--source:api-specifications-->Month<!--/source-->Example `1` |
| `day` | `integer` | <!--source:api-specifications-->Day<!--/source-->Example `1` |
| `datalake_name` | `string` | <!--source:api-specifications-->Datalake Name<!--/source-->Example `datalake` |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Successfully started the translation.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `executionArn`required | `string` | <!--source:api-specifications-->executionArn<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Missing API key
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

<!--source:api-specifications-->

### Languages
<!--/source-->

`PUT` `/languages/{language_name}`

<!--source:api-specifications-->

#### Create or Update Language
<!--/source-->

`updateLanguage`

<!--source:api-specifications-->
Create or Update Language replaces mappings for a specified language. All previously created mappings are removed, and new mappings are created. If a language with the specified name doesn't exist, this service will create it. In general, languages are either pre-built and stored in GitHub, or built directly by a customer. They can be in either .csv or .json format.

Guide for building a .csv-based language

Show the rest Guide for building a .json-based language

Retrieve a pre-built language to understand how they are constructed.

If the language is given in .csv format, which is more straightforward and can be built by a business analyst, Translator converts the .csv file into the more technical .json format.

#### JSONPath syntax

| JSONPath | Description |
| --- | --- |
| $ | the root object/element |
| @ | the current object/element |
| `. or []` | child operator |
| `..` | recursive descent. JSONPath borrows this syntax from E4X. |
| * | wildcard. All objects/elements regardless their names |
| [] | subscript operator. XPath uses it to iterate over element collections and for predicates. In JavaScript and JSON it is the native array operator. |
| [,] | Union operator in XPath results in a combination of node sets. JSONPath allows alternate names or array indices as a set. |
| [start:end:step] | array slice operator borrowed from ES4. |
| ? | applies a filter (script) expression. |
|  | script expression, using the underlying script engine. |

More info and examples can be found here

Also, you can specify constant values instead of JSONPath, for example:

```
{
 "name": "new_language",
 "mapping": {
 "$.value": "Some constant value"
 }
}
```

Sometimes, you might need to set dyanmic JSONPath, that will be generated based on data, that you have passed, for this purpose you can use `{{ <jsonPath> }}` syntax, so `<jsonPath>` will be executed first against your data, f.e you create language like this:

```
{
 "mapping": {
 "$.foo": "$.data.{{ $.target_field }}"
 }
}
```

So when translation begins, `$.target_field` will be queried, and result of this query will replace `{{ $.target_field }}`.

For next input:

```
{
 "target_field": "bar",
 "data": {
 "bar": "baz"
 }
}
```

You will get next result:

```
{
 "foo": "baz"
}
```

You may also need to set up a mapping to only happen in a single direction. For example, only when translating to staircase or from staircase. In order to do this place the mapping into the appropriate section in "single_direction_mappings". The mapping itself should look the same.

```
{
 "single_direction_mappings": {
 "to_staircase": {
 "$.foo_only_to": "$.data.{{ $.target_field }}"
 },
 "from_staircase": {
 "$.foo_only_from": "$.data.{{ $.target_field }}"
 }
 }
}
```

Lastly you may want to pre-process your data before translation or post-process after translation. This is possible by setting up hooks. In order to use hooks you will need to create endpoints inside of your staircase environment and then link the paths to those endpoints in the mapping hooks property. For example, if your environment is you will set up an endpoint at and then set mapping_hooks to {"pre": "my/pre/hook"}. The domain will be added automatically. The pre hook will be sent the exact request payload that was sent to the "/translate" endpoint. The post hook will be sent the translated data as json with the result under the key "translation_result".

```
{
 "mapping_hooks": {
 "pre": "my/pre/hook",
 "post": "my/post/hook"
 }
}
```

Also, we have some predefined `utils` that we can use in our mappings, just using `$utils.<util_name>(*args)`

List of currently supported utils:

#### Join many elements to one string

`$utils.join([*elements], character)`

| Attribute | Type | Description |
| --- | --- | --- |
| elements | list of JSONPaths or constants | List of JSONPaths or constants, to elements to be joined |
| character | string | Character for join provided elements |

Note: Constants are items not starting with $ - are joined as-is.

Return value: Joined string

Example:

```
{
 "name": "util_language",
 "mapping": {
 "$utils.join(['$.address.line_text', '$.address.city', '$.address.state_code', '$.postal_code', 'USA'], ' ')": "$.address"
 }
}
```

#### Split one element to many

`$utils.split(element, separator)`

| Attribute | Type | Description |
| --- | --- | --- |
| element | string | JSONPath to the element that should be split |
| separator | string | separator |

Return value: array of string

Example:

```
{
 "name": "util_language",
 "mapping": {
 "$.deal_sets[0].collaterals[0].address.line_text": "$utils.split('$.address', ' ')[0]",
 "$.deal_sets[0].collaterals[0].address.city": "$utils.split('$.address', ' ')[1]",
 "$.deal_sets[0].collaterals[0].address.state_code": "$utils.split('$.address', ' ')[2]",
 "$.deal_sets[0].collaterals[0].address.postal_code": "$utils.split('$.address', ' ')[3]"
 }
}
```

#### Slice String

`$utils.slice(element, beginIndex, endIndex)`

| Attribute | Type | Description |
| --- | --- | --- |
| element | string | JSONPath to the element to be sliced |
| beginIndex | number | The zero-based index at which to begin extraction. |
| endIndex | number | The zero-based index before which to end extraction. The character at this index will not be included. |

#### Use first element that has a value defined

`$utils.first_defined(elements)`

| Attribute | Type | Description |
| --- | --- | --- |
| elements | list of JSONPathes | List of JSONPathes to elements, each path will be checked in order of list to find the first defined |

Return value: value of first defined element or null

Example:

```
{
 "name": "util_language",
 "mapping": {
 "$.name": "$utils.first_defined(['$.official_name', '$.first_name', '$.nickname'])",
 }
}
```

#### String

`$utils.if_value_in(element, values)`

| Attribute | Type | Description |
| --- | --- | --- |
| element | string | JSONPath to the element, the value of this element will be checked against the values list |
| values | list of strings | List of values deemed to be valid, if the element doesn't match any values it will return null |

Return value: value of element if it's deemed valid or null

Example:

```
{
 "name": "util_language",
 "mapping": {
 "$.deal_type": "$utils.if_value_in('$.type', ['type_a', 'type_b', 'type_c'])"
 }
}
```

#### Transform values

Specify `values_mapping` to transform values. Example:

Use the keyword default for no match. Note: Feature is useful for one-way mapping - use caution when reverse-mapping from staircase back to language.

```
{
 "name": "values_mapping_language",
 "values_mapping": [
 {
 "element": "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range",
 "mapping": [
 {"staircase_value": "HelloWorld", "language_value": "FooBar"},
 {"staircase_value": "BarBaz", "language_value": "WorldHello"},
 {"staircase_value": "CatchAll", "language_value": "_default_"},
 ],
 }
 ]
}
```

Where element is JSONPath in staircase language, and mapping is list of values mapping for specified element

#### Date handling

Specify `normalize_date` to transform dates into standard yyyy-MM-dd format or `denormalize_date` to transform dates from this format.

```
{
 "mapping": {},
 "single_direction_mappings": {
 "to_staircase": {
 "$.borrower_birth_date": "$utils.normalize_date('$.birthday', 'yyyy/MM/dd')"
 },
 "from_staircase": {
 "$utils.denormalize_date('$.borrower_birth_date', 'yyyy/MM/dd')": "$.birthday"
 }
 }
}
```

Date to be in in standard ISO: year: yyyy, month: MM, day: dd, hour: hh, hour24:HH, minute: mm, second: ss, ms: SSS etc. If it is a timestamp, specify "epoch" for date_format argument If it should parsed from any format (for normalize_date), specify "any" for date_format argument

Letters T, Z and UTC to be stripped out prior to conversion.

Example: yyyy-MM-dd HH:mm:ss.SSS for 2019-01-02T15:26:02.123Z UTC

#### DateTime handling

Specify `normalize_datetime` to transform dates/times into standard yyyy-MM-ddTHH.mm.ss.SSS-0X:00 format or `denormalize_datetime` to transform dates/times from this format.

```
{
 "mapping": {},
 "single_direction_mappings": {
 "to_staircase": {
 "$.sample_datetime_field": "$utils.normalize_datetime('$.datetime_in', 'yyyy-MM-dd HH:mm:ss.SSS', 'UTC', 'ET')",
 "$.sample_datetime_field2": "$utils.normalize_datetime('$.datetime_in_epoch', 'epoch', 'UTC', 'ET')"
 },
 "from_staircase": {
 "$utils.denormalize_datetime('$.sample_datetime_field', 'yyyy-MM-dd HH:mm:ss.SSS', 'ET', 'UTC')": "$.datetime_in"
 "$utils.denormalize_datetime('$.sample_datetime_field2', 'epoch', 'ET', 'UTC')": "$.datetime_in_epoch"
 }
 }
}
```

$utils.normalize_datetime(target_field, input_datetime_format, fromTimezone, toTimezone) $utils.denormalize_datetime(target_field, output_datetime_format, fromTimezone, toTimezone)

Date to be in in standard ISO or epoch If it should parsed from any format, specify "any" for input_datetime_format/output_datetime_format argument fromTimezone and toTimezone must be specified as "UTC","ET","CT","PT" Daylight Savings Time is calcuated based on target date, and will be returned based on target date

year: yyyy, month: MM, day: dd, hour: hh, hour24:HH, minute: mm, second: ss, ms: SSS etc.

Output date/time in ISO standard: yyyy-MM-ddTHH:mm:ss.SSS-0X:00 X = offset from UTC (i.e. 5 for EST / 4 for EDT)

Example: ('$.datetime_in', 'yyyy-MM-dd HH:mm:ss.SSS','UTC','ET') - converts from UTC to ET Example: ($.datetime_in_epoch', 'epoch','UTC','ET') - converts from epoch - in UTC by definition - to ET

#### Parse Float

Specify `parse_float` to transform floats into standard format. Second value - number of digits past decimal.

```
{
 "name": "util_language",
 "mapping": {
 "$.float_value_result": "$utils.parse_float('$.float_value_input', '2')"
 },
}
```

to use with wildcards:

```
{
 "name": "util_language",
 "mapping": {
 "$.deal_sets.deal_set[0].deals.deal[0].assets.asset[*].cash_or_market_value_amount": "$utils.map(\'$.report.items[0].accounts[*].balances.current\',\'$utils.parse_float(item,2)\')"
 },
}
```

note: item is a keyword - and must be used as-is

Parses float and trims digits past decimal to integer given - rounds as appropriate. Incoming float values can come in as either string ("234.556") or float (234.556). Outgoing values are numeric only. JSON does not differentiate between integer and float, as such, trailing zeros are trimmed. If a float is un-translatable, will be returned as null/None.

Examples:

| Input | DigitsPastDecimal | Result |
| --- | --- | --- |
| 234.567 | 2 | 234.57 |
| Foobaar | 2 | None |
| 234.567 | 6 | 234.567 |
| 234 | 6 | 234 |

#### Sum Numbers

Specify `sum_numbers` to sum numbers and truncate/round as above.

```
{
 "name": "util_language",
 "mapping": {
 "$.sum_numbers_result": "$utils.sum_numbers('$.sum_number_in';'$.sum_number_in2';'sum_number_in3', '2')"
 },
}
```

Items are truncated/rounded prior to summation. Final sum is also truncated/rounded as specified.

#### Multiply Numbers

Specify `multiply_numbers` to multiply numbers and truncate/round as above.

```
{
 "name": "util_language",
 "mapping": {
 "$.multiply_numbers_result": "$utils.multiply_numbers('$.number_in';12, '2')"
 },
}
```

Items are truncated/rounded prior to summation. Final sum is also truncated/rounded as specified.

#### Parse location

You can parse street address and street intersection for the United States. Util knows about directional prefixes and suffixes, fractional building numbers, building units, grid-based addresses (such as those used in parts of Utah), 5 and 9 digit ZIP codes, and all of the official USPS abbreviations for street types, state names and secondary unit designators.

`$utils.parse_location(element)`

| Attribute | Type | Description |
| --- | --- | --- |
| element | valid JSONPathes | JSONPath to the element, that should be parsed |

Return value:

```
{
 "title": "Address"
 "type": "object",
 "properties": {
 "number": {
 "type": "string",
 "description": "House or street number."
 },
 "prefix": {
 "type": "string",
 "description": "Directional prefix for the street, such as N, NE, E, etc. A given prefix should be one to two characters long."
 },
 "street": {
 "type": "string",
 "description": "Name of the street, without directional or type qualifiers."
 },
 "type": {
 "type": "string",
 "description": "Abbreviated street type, e.g. Rd, St, Ave, etc. See the USPS official type abbreviations at for a list of abbreviations used."
 },
 "suffix": {
 "type": "string",
 "description": "Directional suffix for the street, as above."
 },
 "city": {
 "type": "string",
 "description": "Name of the city, town, or other locale that the address is situated in."
 },
 "state": {
 "type": "string",
 "description": "The state which the address is situated in, given as its two-letter postal abbreviation. for a list of abbreviations used."
 },
 "zip": {
 "type": "string",
 "description": "Five digit ZIP postal code for the address, including leading zero, if needed."
 },
 "sec_unit_type": {
 "type": "string",
 "description": "If the address includes a Secondary Unit Designator, such as a room, suite or appartment, the sec_unit_type field will indicate the type of unit."
 },
 "sec_unit_num": {
 "type": "string",
 "description": "If the address includes a Secondary Unit Designator, such as a room, suite or appartment, the sec_unit_num field will indicate the number of the unit (which may not be numeric)."
 }
 }
}
```

None of his properties is guaranteed and depends on adress that is provided

###### Example:

```
{
 "mapping": {
 "$.number": "$utils.parse_location('$.address')['number']",
 "$.city_state": "$utils.join([$utils.parse_location('$.address')['city'], $utils.parse_location('$.address')['state']], ' ')"
 },
 "name": "address_location"
}
```

#### SetNull

Specify `set_null` to hardcode a null to the field - will show in JSON as 'None'. Cannot be used with wildcards.

###### Example:

```
{
 "name": "util_language",
 "mapping": {
 "$.null_value_to": "set_null",
 "set_null": "$.null_value_from"
 },
}
```

#### Generate ID

You have ability to generate ULID by using `$utlis.ulid`

`$utils.ulid(element, many)`

| Attribute | Type | Description |
| --- | --- | --- |
| element | string | JSONPath in your payload, it can point to anything (object, array, string, etc.), if during translation value, that will be result for two usage of this util will be the same, than it will generate same ids |
| many | boolean | Indicate, if provided element points to array, generate one ids, based on the whole array, or id for every array element |

###### Example:

###### Language:

```
{
 "mapping": {
 "$.elements[*].id": "$utils.ulid('$.input[*].foo')",
 "$.data[*].id": "$utils.ulid('$.input[*].bar')"
 }
}
```

###### Input:

```
{
 "foo": [1, 2, "hello"],
 "bar": [1, 2, "hello"]
}
```

###### Output:

```
{
 "elements": [
 {"id": "01F4EYZ82K7M46DQAZKZT4Y7QT"},
 {"id": "01F4EYZVVM3BTAYHBHV1AJDQZC"},
 {"id": "01F4EZ05VWZZ3BM3EFP6FYQ28H"}
 ],
 "data": [
 {"id": "01F4EYZ82K7M46DQAZKZT4Y7QT"},
 {"id": "01F4EYZVVM3BTAYHBHV1AJDQZC"},
 {"id": "01F4EZ05VWZZ3BM3EFP6FYQ28H"}
 ]
}
```

As you can see, we generated id's, but we have same id's in `elements` and `data` arrays, because input contains same values in objects by provided in language JSONPathes

#### Frame

If your languge is in `application/ld+json` you can apply frame algorithm to your payload, and query data from it

`$utils.frame(element, frameObject)`

| Attribute | Type | Description |
| --- | --- | --- |
| element | string | JSONPath for querying framed payload |
| frameObject | object | JSON-LD frame |

Language example:

```
{
 "mapping": {
 "$.book_title": "$utils.frame('$[\'ex:contains\'][\'dc11:title\']', { '@type': 'ex:Library', 'ex:contains': { '@type': 'ex:Book' } })"
 },
 "jsonld_context": {
 "dc11": "",
 "ex": "",
 "xsd": "",
 "ex:contains": {
 "@type": "@id"
 }
 },
 "content_type": "application/ld+json"
}
```

Input:

```
{
 "@graph": [
 {
 "@id": "",
 "@type": "ex:Library",
 "ex:contains": ""
 },
 {
 "@id": "",
 "@type": "ex:Book",
 "dc11:creator": "Plato",
 "dc11:title": "The Republic",
 "ex:contains": ""
 },
 {
 "@id": "",
 "@type": "ex:Chapter",
 "dc11:description": "An introductory chapter on The Republic.",
 "dc11:title": "The Introduction"
 }
 ]
}
```

Output:

```
{
 "book_title": "The Republic"
}
```

#### Convert string case

`$utils.convert_case(element, case)`

| Attribute | Type | Description |
| --- | --- | --- |
| element | JSONPath | JSONPath to be converted |
| case | string | Supported conversions: upper, lower |

Return value: Converted string

Example:

```
{
 "name": "util_language",
 "mapping": {
 "$utils.convert_case('$.address.state_code', 'upper')": "$.state"
 }
}
```

#### Extract text with regex

`$utils.regex_extract(element, regex)`

| Attribute | Type | Description |
| --- | --- | --- |
| element | JSONPath | JSONPath to be extracted from |
| regex | regex | The regex to use for extracting text from the element |

Return value: Extracted string

Example:

```
{
 "name": "regex_language",
 "mapping": {
 "$.income": "$utils.regex_extract('$.borrower_income', '\\d+')"
 }
}
```

#### Set current date

`$utils.set_current_date`

Example:

```
{
 "name": "current_date_language",
 "mapping": {
 "$.current_date": "$utils.set_current_date"
 }
}
```

Return value: string with current date in normalized format "yyyy-MM-dd" by 'America/New_York' timezone.

#### Format field

`$utils.format(element, type)`

| Attribute | Type | Description |
| --- | --- | --- |
| element | JSONPath | JSONPath to be extracted from |
| type | string | Type of formatting to produce. Choices are "ssn", "itin", "percent", "phone_number", "phone_number_parentheses" |

Return value: Formatted string

Example:

```
{
 "name": "format-ssn",
 "mapping": {
 "$.ssn": "$utils.format('$.incoming_ssn', 'ssn')"
 }
}
```

#### Relationship

`$utils.relationship(element, query, key, relName)`

Map XLINK relationships (`1:1` and `1:M`) used in XML-like schemas

| Attribute | Type | Description |
| --- | --- | --- |
| element | JSONPath | JSONPath to extract first relationship entity |
| query | JSONPath | JSONPath to extract the second relationship entity |
| key | JSONPath | JSONPath of key that contains the value of first relationship component |
| relName | string | Name to be used for relationship in output object |

The following is an example mapping (note: mappings for this operation are single-direction):

```
{
 "single_direction_mappings": {
 "to_staircase": {
 "$.relationships.relationship[*]|ASSET_LIABILITY-$.assets[?(@.@type=='real_estate_owned')]-with_liability[*]": "$utils.relationship('$.assets[?(@.@type==\'real_estate_owned\')]', 'with_liability[*]', '@id', 'ASSET_LIABILITY')"
 }
 }
}
```

The above mapping uses the JSON Path query `$.assets[?(@.@type==\'real_estate_owned\')]` to get the relationship's left-side (or from-) entity. The value in its `@id` field will be use to mark this first entity in the created output. The JSON Path `with_liability[*]` marks the value of right-side (or to-) entity in the relationship. The relationship's name is

```
{
 "people": [
 {
 "@id": "BORROWER_1",
 "@type": "borrower",
 "owns_asset": [
 "ASSET_1",
 "ASSET_2"
 ]
 }
 ],
 "assets": [
 {
 "@id": "ASSET_1",
 "@type": "retirement_account",
 "has_account_identifier": {
 "has_value": "4444"
 },
 "has_asset_description": {
 "has_value": "Roth IRA"
 },
 "has_market_value_amount": {
 "has_value": 923.27
 }
 },
 {
 "@id": "ASSET_2",
 "@type": "real_estate_owned",
 "has_market_value_amount": {
 "has_value": 25632.87
 },
 "with_liability": [
 "LIABILITY_1"
 ]
 }
 ],
 "liabilities": [
 {
 "@id": "LIABILITY_1",
 "@type": "liability",
 "has_liability_payment_amount": {
 "has_value": 923.27
 }
 }
 ]
}
```

When the language mappings are applied to the above example input, the following output is created:

```
{
 "relationships": {
 "relationship": [
 {
 "relationship_link": "ASSET_LIABILITY",
 "link_from": "ASSET_2",
 "link_to": "LIABILITY_1"
 }
 ]
 }
}
```

<!--/source-->

##### Request

<!--source:api-specifications-->
Example with utilsXML Language exampleExample with values mapping
<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "mapping": {
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].date": "$.bundle[0].date",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range": "$.bundle[0].lower",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].high_value_range": "$.bundle[0].upper",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].value": "$.bundle[0].zestimate",
 "$utils.join(['$.deal_sets[0].collaterals[0].address.line_text', '$.deal_sets[0].collaterals[0].address.city', '$.deal_sets[0].collaterals[0].address.state_code', '$.deal_sets[0].collaterals[0].address.postal_code'], ' ')": "$.address",
 "$.deal_sets[0].collaterals[0].address.line_text": "$utils.split('$.address', ' ')[0]",
 "$.deal_sets[0].collaterals[0].address.city": "$utils.split('$.address', ' ')[1]",
 "$.deal_sets[0].collaterals[0].address.state_code": "$utils.split('$.address', ' ')[2]",
 "$.deal_sets[0].collaterals[0].address.postal_code": "$utils.split('$.address', ' ')[3]"
 },
 "sc_version": 0
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "content_type": "application/xml",
 "mapping": {
 "$.about_versions.about_version_identifier": "$.MESSAGE[0].ABOUT_VERSIONS[0].ABOUT_VERSION[0].AboutVersionIdentifier[0]._text[0]",
 "$.about_versions.data_version_identifier": "$.MESSAGE[0].ABOUT_VERSIONS[0].ABOUT_VERSION[0].DataVersionIdentifier[0]._text[0]",
 "$.deal_sets[*].about_versions.data_version_identifier": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].ABOUT_VERSIONS[0].ABOUT_VERSION[0].DataVersionName[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.address.address_line_text": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].ADDRESS[0].AddressLineText[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.address.city_name": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].ADDRESS[0].CityName[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.address.postal_code": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].ADDRESS[0].PostalCode[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.address.state_code": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].ADDRESS[0].StateCode[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_detail.attachment_type": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].AttachmentType[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_detail.construction_method_type": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].ConstructionMethodType[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_detail.financed_unit_count": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].FinancedUnitCount[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_detail.property_estate_type": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyEstateType[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_detail.property_estimated_value_amount": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyEstimatedValueAmount[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_detail.property_existing_clean_energy_lien_indicator": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyExistingCleanEnergyLienIndicator[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_detail.property_in_project_indicator": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyInProjectIndicator[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_detail.property_mixed_usage_indicator": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyMixedUsageIndicator[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_detail.property_usage_type": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PropertyUsageType[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_detail.pud_indicator": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_DETAIL[0].PUDIndicator[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_valuations[*].property_valuation_detail.appraisal_identifier": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_VALUATIONS[0].PROPERTY_VALUATION[*].PROPERTY_VALUATION_DETAIL[0].AppraisalIdentifier[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.property_valuations[*].property_valuation_detail.property_valuation_amount": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].PROPERTY_VALUATIONS[0].PROPERTY_VALUATION[*].PROPERTY_VALUATION_DETAIL[0].PropertyValuationAmount[0]._text[0]",
 "$.deal_sets[*].collaterals[*].subject_property.sales_contracts[*].sales_contract_detail.sales_contract_amount": "$.MESSAGE[0].DEAL_SETS[0].DEAL_SET[*].DEALS[0].DEAL[0].COLLATERALS[0].COLLATERAL[*].SUBJECT_PROPERTY[0].SALES_CONTRACTS[0].SALES_CONTRACT[*].SALES_CONTRACT_DETAIL[0].SalesContractAmount[0]._text[0]"
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "mapping": {
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].date": "$.bundle[0].date",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].high_value_range": "$.bundle[0].upper",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range": "$.bundle[0].lower",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].value": "$.bundle[0].zestimate"
 },
 "values_mapping": [
 {
 "element": "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range",
 "mapping": [
 {
 "language_value": "FooBar",
 "staircase_value": "HelloWorld"
 },
 {
 "language_value": "WorldHello",
 "staircase_value": "BarBaz"
 }
 ]
 }
 ],
 "sc_version": 0
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400403
<!--/source-->

<!--source:api-specifications-->
application/json Copy Async update accepted

```
Async update accepted
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
6
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `language_name` required | `string` path | `my_lang` | <!--source:api-specifications-->Language name<!--/source--> |
| `validate` | `boolean` query | `true` | <!--source:api-specifications-->Whether to validate the language before inserting. By default it will be validated.<!--/source--> |
| `sc_version` | `integer` query | `1` | <!--source:api-specifications-->Version of the staircase language to which this language targets (.csv only)<!--/source--> |
| `payload_content_type` | `string` query | `application/json` | <!--source:api-specifications-->Content type of payload - defaults to application/json (.csv only)<!--/source--> |
| `async` | `boolean` query | `true` | <!--source:api-specifications-->Whether to execute the update asynchronously, this is best for larger operations. Be default, async is off. Use the retrieve language update status endpoint to check status and the retrieve language endpoint to get the updated language.<!--/source--> |
| `parse_enum_values_types` | `boolean` query | `true` | <!--source:api-specifications-->if enum values should be parsed with datatypes (booleans, integers, floats), set this parameter to true.<!--/source--> |

##### Request body`application/json`

<!--source:api-specifications-->
10 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | <!--source:api-specifications-->Language name<!--/source--> |
| `mapping`required | `object` | <!--source:api-specifications-->Mapping<!--/source--> |
| `single_direction_mappings` | `object` | <!--source:api-specifications-->Single direction mappings<!--/source--> |
| `values_mapping` | `object[]` | <!--source:api-specifications-->Mapping values<!--/source--> |
| `element`required | `string` | <!--source:api-specifications-->Element<!--/source--> |
| `mapping`required | `object[]` | <!--source:api-specifications-->Mapping<!--/source--> |
| `staircase_value`required | `string` | <!--source:api-specifications-->Staircase value<!--/source--> |
| `language_value`required | `string` | <!--source:api-specifications-->Language value<!--/source--> |
| `unique_arrays` | `object` | <!--source:api-specifications-->Key-value pairs, where key is JSONPath to array of objects, and value is key, that has been unique<!--/source--> |
| `merge_arrays` | `object` | <!--source:api-specifications-->Key-value pairs, where key is JSONPath to array which will contain merged elements, and value is an array, which contains JSONPaths to arrays that should be excluded from result and all their elements should be included to the JSONPath specified as a key.<!--/source--> |
| `content_type` | `string` | <!--source:api-specifications-->Content type<!--/source-->`application/json``application/ld+json``application/xml` |
| `sc_version` | `integer` | <!--source:api-specifications-->Staircase version language is mapped to - defaults to 0<!--/source--> |
| `validate_paths` | `boolean` | <!--source:api-specifications-->Turn on or off the validation of language mapping paths. By default, turned on.<!--/source--> |
| `async` | `boolean` | <!--source:api-specifications-->Whether to execute the update asynchronously, this is best for larger operations. Be default, async is off. Use the retrieve language update status endpoint to check status and the retrieve language endpoint to get the updated language.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Other responses

`202``204``422`

`GET` `/languages/{language_name}/status`

<!--source:api-specifications-->

#### Retrieve Language Update Status
<!--/source-->

`retrieveLanguageStatus`

<!--source:api-specifications-->
Retrieve Language Update Status retrieves the status of an asynchronous language update.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Language

```
{
 "status": "RUNNING"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Language not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `language_name` required | `string` path | `my_lang` | <!--source:api-specifications-->Language name<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Language
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | <!--source:api-specifications-->Update in progress<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

`DELETE` `/languages/{language_name}`

<!--source:api-specifications-->

#### Delete Language
<!--/source-->

`deleteLanguage`

<!--source:api-specifications-->
Delete Language removes a language from the translator.

<!--/source-->

##### Response

<!--source:api-specifications-->
400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Language not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `language_name` required | `string` path | `my_lang` | <!--source:api-specifications-->Language name<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`204`

`GET` `/languages/{language_name}/elements`

<!--source:api-specifications-->

#### Retrieve Language Elements
<!--/source-->

`retrieveLanguageElements`

<!--source:api-specifications-->
Retrieve Language Elements retrieves a list of Staircase elements present in a language.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy List of staircase elements present in language

```
[
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].date",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].low_value_range",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].high_value_range",
 "$.deal_sets[0].collaterals[0].property_valuations[0].avms[0].value",
 "$.deal_sets[0].collaterals[0].address.line_text",
 "$.deal_sets[0].collaterals[0].address.city",
 "$.deal_sets[0].collaterals[0].address.state_code",
 "$.deal_sets[0].collaterals[0].address.postal_code"
]
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Language not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `language_name` required | `string` path | `my_lang` | <!--source:api-specifications-->Language name<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`200`

`GET` `/languages`

<!--source:api-specifications-->

#### Retrieve Languages
<!--/source-->

`retrieveLanguages`

<!--source:api-specifications-->
Retrieve Languages returns a list of all supported languages on the platform.

Note: There is a maximum amount of languages returned in a response. If there are more languages left to retrieve, the next field in the response will contain the name of the last retrieved language. To retrieve the next set of languages, use the optional after_name query parameter.

Show the rest
```
curl --location --request GET '' \
--header 'x-api-key: <redacted>' \
--header 'Content-Type: application/json'
```

```
"languages": [
 {"name": "mismo34", "version": "3.4", "content_type": "application/ld+json"},
 {"name": "jsonlang", "version": "0.1", "content_type": "application/json"},
 {"name": "xmlang", "version": "0.1", "content_type": "text/xml"},
 ]
 }
```

<!--/source-->

##### Response

<!--source:api-specifications-->
400403
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
2
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `after_name` | `string` query | `mismo34` | <!--source:api-specifications-->name of the last language retrieved in the list<!--/source--> |
| `limit` | `integer` query | `100` | <!--source:api-specifications-->number of items per page<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
200 response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `next` | `string` | <!--source:api-specifications-->Name of the last language evaluated (bookmark)<!--/source--> |
| `languages` | `object[]` | <!--source:api-specifications-->Language name, version and type of content for the language mapping<!--/source--> |
| `name` | `string` | <!--source:api-specifications-->Language name<!--/source--> |
| `version` | `string` | <!--source:api-specifications-->Staircase language version<!--/source--> |
| `content_type` | `string` | <!--source:api-specifications-->Type of content for the language mapping<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

`GET` `/languages/{language_name}`

<!--source:api-specifications-->

#### Retrieve Single Language
<!--/source-->

`retrieveLanguage`

<!--source:api-specifications-->
Retrieve Single Language retrieves a language name, mapping, and content type for a language. If the language is being updated asynchronously and the update hasn't finished the response will contain a status.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Language

```
{
 "name": "my_lang",
 "mapping_info": {
 "language_elements": {
 "coverage": "100%",
 "unmapped_count": 0,
 "mapped_count": 3,
 "unmapped": []
 },
 "staircase_elements": {
 "coverage": "100%",
 "unmapped_count": 0,
 "mapped_count": 4,
 "unmapped": []
 }
 },
 "mapping": {
 "$.deal_sets.deal_set[0].deals.deal[0].assets.asset[*].account_identifier": "$.report.items[0].accounts[*].mask",
 "$.deal_sets.deal_set[0].deals.deal[0].services.service[0].verification_of_assets.verification_of_assets_response.partner_product": "Assets",
 "$.deal_sets.deal_set[0].deals.deal[0].services.service[0].verification_of_assets.verification_of_assets_response.service_date": "$utils.slice('$.report.date_generated', 0, 10)",
 "$.document.extracted_data.fanniemae_or_freddiemac": "$.extractedData[?(@.name == 'Form_Name')].data"
 },
 "values_mapping": [
 {
 "mapping": [
 {
 "staircase_value": "Fannie Mae",
 "language_value": "fanniemae"
 },
 {
 "staircase_value": "Freddie Mac",
 "language_value": "freddiemac"
 }
 ],
 "element": "$.document.extracted_data.fanniemae_or_freddiemac"
 }
 ],
 "sc_version": 0,
 "content_type": "application/json"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Language not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `language_name` required | `string` path | `my_lang` | <!--source:api-specifications-->Language name<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
6 fields
<!--/source-->
<!--source:api-specifications-->
Language
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | <!--source:api-specifications-->name<!--/source--> |
| `mapping` | `object` | <!--source:api-specifications-->Mapping type either string or array<!--/source--> |
| `mapping_info` | `object` | <!--source:api-specifications-->Meta information about existing mapping<!--/source--> |
| `language_elements` | `object` | <!--source:api-specifications-->Meta information about existing mapping elements<!--/source--> |
| `coverage` | `string` | <!--source:api-specifications-->Meta information about coverage<!--/source--> |
| `mapped_count` | `number` | <!--source:api-specifications-->Meta information about mapped_count<!--/source--> |
| `unmapped_count` | `number` | <!--source:api-specifications-->Meta information about unmapped_count<!--/source--> |
| `unmapped` | `string[]` | <!--source:api-specifications-->Meta information about unmapped<!--/source--> |
| `staircase_elements` | `object` | <!--source:api-specifications-->Meta information about staircase elements<!--/source--> |
| `coverage` | `string` | <!--source:api-specifications-->Meta information about coverage<!--/source--> |
| `mapped_count` | `number` | <!--source:api-specifications-->Meta information about mapped_count<!--/source--> |
| `unmapped_count` | `number` | <!--source:api-specifications-->Meta information about unmapped_count<!--/source--> |
| `unmapped` | `string[]` | <!--source:api-specifications-->Meta information about unmapped<!--/source--> |
| `sc_version` | `integer` | <!--source:api-specifications-->Sc_version number<!--/source--> |
| `values_mapping` | `object[]` | <!--source:api-specifications-->Array of values mapping<!--/source--> |
| `element` | `string` | <!--source:api-specifications-->Element name<!--/source--> |
| `mapping` | `object[]` | <!--source:api-specifications-->Mapping array<!--/source--> |
| `staircase_value` | `string` | <!--source:api-specifications-->Staircase value<!--/source--> |
| `language_value` | `string` | <!--source:api-specifications-->Language value<!--/source--> |
| `content_type` | `string` | <!--source:api-specifications-->Type of content sent in the response<!--/source-->`application/json``application/ld+json``application/xml` |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

<!--source:api-specifications-->

### Mappings
<!--/source-->

`POST` `/mappings/{mapping_name}/import`

<!--source:api-specifications-->

#### Create Mapping from Payload
<!--/source-->

`createMapping`

<!--source:api-specifications-->
Create mapping from existing payload
<!--/source-->

<!--source:api-specifications-->
Import mapping takes an existing payload and creates a starter mapping from it.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "settings": {
 "auto-create": true
 },
 "data": {
 "report": {
 "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d",
 "client_report_id": "123abc",
 "date_generated": "2020-06-05T22:47:53Z",
 "days_requested": 3,
 "items": [
 {
 "accounts": [
 {
 "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
 "name": "Plaid Saving",
 "official_name": "Plaid Silver Standard 0.1% Interest Saving"
 }
 ]
 }
 ],
 "user": {
 "client_user_id": "123456789",
 "email": "accountholder0@example.com",
 "first_name": "Alberta",
 "last_name": "Charleson",
 "middle_name": "Bobbeth",
 "phone_number": "111-222-3333",
 "ssn": "999-00-0000"
 }
 },
 "request_id": "eYupqX1mZkEuQRx",
 "warnings": []
 }
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
201400403
<!--/source-->

<!--source:api-specifications-->
application/json Copy Mapping created successfully

```
{
 "name": "mapping_name",
 "mapping_info": {
 "language_elements": {
 "coverage": 0,
 "mapped_count": 0,
 "unmapped_count": 16,
 "unmapped": [
 "$.report.asset_report_id",
 "$.report.client_report_id",
 "$.report.date_generated",
 "$.report.days_requested",
 "$.report.items[*].accounts[*].account_id",
 "$.report.items[*].accounts[*].name",
 "$.report.items[*].accounts[*].official_name",
 "$.report.user.client_user_id",
 "$.report.user.email",
 "$.report.user.first_name",
 "$.report.user.last_name",
 "$.report.user.middle_name",
 "$.report.user.phone_number",
 "$.report.user.ssn",
 "$.request_id",
 "$.warnings[*]"
 ]
 },
 "staircase_elements": {
 "coverage": 0,
 "mapped_count": 0,
 "unmapped_count": 0,
 "unmapped": null
 }
 },
 "mapping": {
 "": [
 "$.report.asset_report_id",
 "$.report.client_report_id",
 "$.report.date_generated",
 "$.report.days_requested",
 "$.report.items[*].accounts[*].account_id",
 "$.report.items[*].accounts[*].name",
 "$.report.items[*].accounts[*].official_name",
 "$.report.user.client_user_id",
 "$.report.user.email",
 "$.report.user.first_name",
 "$.report.user.last_name",
 "$.report.user.middle_name",
 "$.report.user.phone_number",
 "$.report.user.ssn",
 "$.request_id",
 "$.warnings[*]"
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Unable to create mapping from payload

```
{
 "message": "Unable to create mapping from payload"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `mapping_name` required | `string` path | `my_mapping` | <!--source:api-specifications-->Mapping name<!--/source--> |

##### Request body`application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `settings` | `object` | <!--source:api-specifications-->Settings object<!--/source--> |
| `auto-create` | `boolean` | <!--source:api-specifications-->Whether to save the mapping after importing it. Defaults to true.<!--/source--> |
| `data` | `object` | <!--source:api-specifications-->Data object<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Unable to create mapping from payload
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Other responses

`201`

<!--source:api-specifications-->

### Rules Generator
<!--/source-->

`POST` `/rules-generator/jobs`

<!--source:api-specifications-->

#### Generate Rules
<!--/source-->

`generateRules`

<!--source:api-specifications-->
Generate Rules from one language to another. Currently supports mapping from/to:

- `lexicon`
- `staircase-graph`
- `staircase-mismo-limited`

Multiple algorithms are supported. The source of the partner language schema to match is the Lexicon Languages Registry.

List of algorithms:

- property_matching - The algorithm uses similarity between property and class names to generate rules. Good fit for more flat languages.
- containers_first_matching - The algorithm uses the similarity between class names in the first priority, and property names in the second, to generate rules. Good fit for more nested languages.
- gpt - The algorithm uses GPT-4 to generate rules.

There is also a possibility to select a string similarity algorithm and similarity score cutoff. These parameters define how particular containers and properties will be chosen as the best match to map in rules. The possible values for `similarity_algorithm` are ratio, jaro, and jaro_winkler:

Show the rest
- ratio (default) calculates the Levenshtein distance ratio of similarity between two sequences;
- jaro and jaro_winkler are string-edit distance algorithms that give more favorable ratings to strings that match from the beginning.

#### Parties Mapping

##### (works only for `containers_first_matching` algorithm)

In MISMO and MISMO-like languages, parties have a slightly different structure from staircase languages. In order to map parties from the partner language to the staircase you need to specify a path to value in the partner language that determines party type and corresponding value in the staircase language. Check the request body example for more details.

#### Static Mappings

##### (works only for `containers_first_matching` algorithm)

The rules-generation process consists of matching containers and end-properties:

- containers are objects and arrays.
- end-properties are literal values - strings, numbers, and booleans.

There are common cases when a partner language has similar end-properties to staircase language, but their container structure and names might be pretty different. The static mapping parameter solves this problem.

Static mappings are specialized for "hard-coding" the mappings only for containers, so the service is able to map properties (and child containers that are not specified in static mappings) between these containers by the similarity algorithm. Suppose some end-properties should be mapped although they don't match by similarity algorithm. In that case, the user should map it just manually by himself inside the generated rules sample after the generation.

Static mappings are specified in the `static_mappings` field of the `algorithm_settings` and might have a recursive structure with a `children` field for each mapping. `foreign_container` and `staircase_container` are relative paths (relative to the parent mapping, if it is in `children`) to the containers in the partner and staircase languages respectively. In staircase language it might be a v2 container in a root mapping, or a relationship in `children` mappings.

`foreign_container` might consist of a single node (like "role") or multiple nodes joined with a front slash (like "role/roles/roleDetail"). In this case, intermediate containers are treated as skipped in rules, so they will be mapped to the empty staircase path (`""`). The same logic might be applied by specifying `null` values for `staircase_container` & `staircase_type`.

So, these static mappings:

```
[ 
 { 
 "foreign_container": "x/y/z", 
 "staircase_container": "assets", 
 "staircase_type": "asset" 
 }
]
```

are absolutely equal to these:

```
[ 
 { 
 "foreign_container": "x", 
 "staircase_container": null, 
 "staircase_type": null 
 },
 { 
 "foreign_container": "x/y", 
 "staircase_container": null, 
 "staircase_type": null 
 },
 { 
 "foreign_container": "x/y/z", 
 "staircase_container": "assets", 
 "staircase_type": "asset" 
 }
]
```

and these:

```
[
 },
 { 
 "foreign_container": "x", 
 "staircase_container": null, 
 "staircase_type": null,
 "children": [
 { 
 "foreign_container": "y", 
 "staircase_container": null, 
 "staircase_type": null,
 "children": [
 { 
 "foreign_container": "z", 
 "staircase_container": "assets", 
 "staircase_type": "asset" 
 }
 ]
 }
 ]
 }
]
```

It might be useful to map different nested objects to the single item of the same staircase container & type:

```
[
 {
 "foreign_container": "ASSETS",
 "staircase_container": "assets",
 "staircase_type": "asset",
 "children": [
 {
 "foreign_container": "ASSET/ASSET_DETAIL",
 "staircase_container": null,
 "staircase_type": null
 }
 ]
 ]
 }
]
```

In this case, all the properties of the `ASSETS` and the `ASSET_DETAIL` objects will be mapped to the same `asset` item.

If some foreign container is array and should be mapped to the staircase relationship, you should map exactly this array container to the relationship, and if needed, specify nested objects as `children`: For example, you have data like this:

```
{
 "borrower": {
 "name": "John Doe",
 "some_dummy_node": {
 "hmda_races": [
 {
 "hmda_races_info": {
 "hmda_race_type": "bla-bla-bla"
 },
 "additional_info": {
 "race_type_additional_description": "bla-bla-bla"
 },
 }
 ]
 }
 }
}
```

and you want to map `hmda_races` array to the `with_hmda_race` borrower's relationship. In this case, static mappings should look like this:

```
[
 {
 "foreign_container": "borrower/some_dummy_node/hmda_races",
 "staircase_container": "with_hmda_race",
 "staircase_type": "hmda_race",
 "children": [
 {
 "foreign_container": "hmda_races_info",
 "staircase_container": null,
 "staircase_type": null
 },
 {
 "foreign_container": "additional_info",
 "staircase_container": null,
 "staircase_type": null
 }
 ]
 }
]
```

##### More complete example

```
{ 
 "algorithm_settings": { 
 "static_mappings": [ 
 { 
 "foreign_container": "foreign_container_1", 
 "staircase_container": "staircase_container_1", 
 "staircase_type": "staircase_type_1", 
 "children": [ 
 { 
 "foreign_container": "child_foreign_container_1", 
 "staircase_container": "child_staircase_container_1", 
 "staircase_type": "staircase_type_1_1", 
 "evaluate_separate": true, 
 "filter": { 
 "path": "filter_path_1", 
 "value": "filter_value_1", 
 "operation": "IS_EQUAL" 
 } 
 }, 
 { 
 "foreign_container": "child_foreign_container_2", 
 "staircase_container": "child_staircase_container_2", 
 "staircase_type": "staircase_type_1_2" 
 } 
 ] 
 }, 
 { 
 "foreign_container": "foreign_container_2", 
 "staircase_container": "staircase_container_2", 
 "staircase_type": "staircase_type_2", 
 "evaluate_separate": true, 
 "filter": { 
 "path": "filter_path_3", 
 "value": true, 
 "operation": "IS_EQUAL" 
 } 
 } 
 ] 
 } 
}
```

<!--/source-->

##### Request

<!--source:api-specifications-->
Property matching exampleContainer matching example with parties mappingContainer matching with static mappings
<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "lang_from": "credit",
 "lang_to": "staircase-graph",
 "algorithm": "property_matching"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "lang_from": "mismo-like",
 "lang_to": "staircase-graph",
 "algorithm": "container_first_matching",
 "algorithm_settings": {
 "parties_mapping": {
 "path_to_type_value": "roles/roleDetail/partyRoleType",
 "mappings": [
 {
 "foreign_type": "PARTY_ROLE_ENUM_BORROWER",
 "staircase_type": "borrower"
 },
 {
 "foreign_type": "PARTY_ROLE_ENUM_CO_BORROWER",
 "staircase_type": "co_borrower"
 },
 {
 "foreign_type": "PARTY_ROLE_ENUM_LOAN_ORIGINATOR",
 "staircase_type": "loan_originator"
 }
 ]
 }
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "lang_from": "some_partner_lang",
 "lang_to": "staircase-graph",
 "algorithm": "container_first_matching",
 "algorithm_settings": {
 "static_mappings": [
 {
 "foreign_container": "foreign_container_1",
 "staircase_container": "staircase_container_1",
 "staircase_type": "staircase_type_1",
 "children": [
 {
 "foreign_container": "child_foreign_container_1",
 "staircase_container": "child_staircase_container_1",
 "staircase_type": "staircase_type_1_1",
 "evaluate_separate": true,
 "filter": {
 "path": "filter_path_1",
 "value": "filter_value_1",
 "operation": "IS_EQUAL"
 }
 },
 {
 "foreign_container": "child_foreign_container_2",
 "staircase_container": "child_staircase_container_2",
 "staircase_type": "staircase_type_1_2"
 }
 ],
 "evaluate_separate": false
 },
 {
 "foreign_container": "foreign_container_2",
 "staircase_container": "staircase_container_2",
 "staircase_type": "staircase_type_2",
 "evaluate_separate": true,
 "filter": {
 "path": "filter_path_3",
 "value": true,
 "operation": "IS_EQUAL"
 }
 }
 ]
 }
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Generated rules

```
{
 "id": "5be17d0e-425e-4419-bf7f-18caca2ed530",
 "status": "running",
 "lang_from": "staircase-graph",
 "lang_to": "credit"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Forbidden

```
{
 "message": "Invalid Api Key"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Resource is not found

```
{
 "message": "Job not found."
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
4 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `lang_from`required | `string` | <!--source:api-specifications-->Language to generate rules from<!--/source--> |
| `lang_to`required | `string` | <!--source:api-specifications-->Language to generate rules to<!--/source--> |
| `algorithm`required | `string` | <!--source:api-specifications-->Algorithm to use for generating rules<!--/source-->`container_first_matching``gpt``property_matching` |
| `algorithm_settings` | `object` | <!--source:api-specifications-->Algorithm settings.<!--/source--> |
| `similarity_algorithm` | `string` | <!--source:api-specifications-->The name of the similarity algorithm to use. The possible values are 'ratio', 'jaro', and 'jaro_winkler'. - 'ratio' (***default***) calculates the Levenshtein distance ratio of similarity between two sequences; - 'jaro' and 'jaro_winkler' are string-edit distance algorithms that give more favorable ratings to strings that match from the beginning.<!--/source-->`jaro``jaro_winkler``ratio` |
| `score_cutoff` | `number (float)` | <!--source:api-specifications-->The minimum score a pair must have to be considered a match. This is based on the similarity measure provided by the selected algorithm. It represents the minimum allowed similarity score between two strings for them to be considered a match.<!--/source--> |
| `override_container_names` | `object[]` | <!--source:api-specifications-->Array of objects with container names to override.<!--/source--> |
| `staircase_type`required | `string` | <!--source:api-specifications-->`@type` for which container name should be overridden.<!--/source--> |
| `staircase_container`required | `string` | <!--source:api-specifications-->Container name in staircase language to set always.<!--/source--> |
| `parties_mapping` | `object` | <!--source:api-specifications-->Parties mapping settings. Required for container_first_matching algorithm.<!--/source--> |
| `path_to_type_value` | `string` | <!--source:api-specifications-->Relative path starting from parties(case insensitive container) to value in partner language that determines party type.<!--/source--> |
| `mappings` | `object[]` | <!--source:api-specifications-->Array of mappings from partner language party type to staircase language party type.<!--/source--> |
| `foreign_type` | `string` | <!--source:api-specifications-->Party type in partner language.<!--/source--> |
| `staircase_type` | `string` | <!--source:api-specifications-->Party type in staircase language.<!--/source--> |
| `static_mappings` | `object[]` | <!--source:api-specifications-->Static mappings are specified to hard-code the mappings only for containers with container_first_matching algorithm. Can have a recursive structure with 'children' field for each mapping.<!--/source--> |
| `foreign_container`required | `string` | <!--source:api-specifications-->The identifier of the foreign container that needs to be mapped. Might have multiple nodes separated by '/'.<!--/source--> |
| `staircase_container`required | `string` | <!--source:api-specifications-->The identifier of the staircase container to which the foreign container is mapped. Might have multiple nodes separated by '/'.<!--/source--> |
| `staircase_type`required | `string` | <!--source:api-specifications-->The type of the staircase container.<!--/source--> |
| `children` | `object[]` | <!--source:api-specifications-->The array of child static mappings, allowing for recursive mapping structures.<!--/source--> |
| `evaluate_separate` | `boolean` | <!--source:api-specifications-->A boolean flag indicating whether to evaluate the mapping separately.<!--/source--> |
| `filter` | `object` | <!--source:api-specifications-->An object that specifies the filter conditions for the mapping for the direction `Foreign -> Staircase`.<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->The path to the property in the container that needs to be filtered.<!--/source--> |
| `value` | `one of` | <!--source:api-specifications-->The value against which the property at the given path will be checked.<!--/source--> |
| `operation` | `string` | <!--source:api-specifications-->The operation to be performed for filtering. Currently, only 'IS_EQUAL' operation is supported.<!--/source-->`IS_EQUAL` |

##### Response `202``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Generated rules
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | <!--source:api-specifications-->Generation id<!--/source--> |
| `status`required | `string` | <!--source:api-specifications-->Generation status<!--/source-->`running` |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Forbidden
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Resource is not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

`GET` `/rules-generator/jobs/{id}`

<!--source:api-specifications-->

#### Get Rules Generation Status
<!--/source-->

`getRulesGenerationStatus`

##### Response

<!--source:api-specifications-->
200 Running200 Failed200 Completed400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Rules Generation Status

```
{
 "id": "5be17d0e-425e-4419-bf7f-18caca2ed530",
 "status": "running",
 "lang_from": "staircase-graph",
 "lang_to": "credit",
 "errors": null,
 "rules": null,
 "statistics": null
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Rules Generation Status

```
{
 "id": "5be17d0e-425e-4419-bf7f-18caca2ed530",
 "status": "failed",
 "lang_from": "staircase-graph",
 "lang_to": "credit",
 "errors": [
 "Error message 1",
 "Error message 2"
 ],
 "rules": null,
 "statistics": null
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Rules Generation Status

```
{
 "id": "5be17d0e-425e-4419-bf7f-18caca2ed530",
 "status": "completed",
 "lang_from": "staircase-graph",
 "lang_to": "credit",
 "errors": null,
 "statistics": {
 "mapped_properties_count": 3,
 "unmapped_properties_count": 1,
 "coverage_ratio": 0.75,
 "unmapped_properties": [
 "MESSAGE/DEAL_SETS/PARTIES/PARTY/ROLES/ROLE/PARTY_ROLE_IDENTIFIERS/PARTY_ROLE_IDENTIFIER/PartyRoleIdentifier"
 ],
 "mapped_properties": [
 {
 "from": "MESSAGE/DEAL_SETS/DEAL_SET/DEALS/DEAL/ABOUT_VERSIONS/ABOUT_VERSION/@SequenceNumber",
 "to": "data_versions/has_sequence_number/has_value"
 },
 {
 "from": "MESSAGE/DEAL_SETS/DEAL_SET/DEALS/DEAL/ABOUT_VERSIONS/ABOUT_VERSION/DataVersionName",
 "to": "data_versions/has_data_version_name/has_value"
 },
 {
 "from": "MESSAGE/DEAL_SETS/PARTIES/PARTY/LEGAL_ENTITY/LEGAL_ENTITY_DETAIL/FullName",
 "to": "organizations/has_organization_name/has_value"
 }
 ]
 },
 "rules": [
 {
 "definition": {
 "from": {
 "path": "MESSAGE/DEAL_SETS/DEAL_SET/DEALS/DEAL/ABOUT_VERSIONS"
 },
 "to": {
 "path": "data_versions"
 },
 "attribute_mappings": [
 {
 "from": {
 "value": "data_version"
 },
 "to": {
 "path": "@type"
 }
 },
 {
 "from": {
 "path": "ABOUT_VERSION"
 },
 "to": {
 "path": ""
 },
 "attribute_mappings": [
 {
 "from": {
 "path": "@SequenceNumber"
 },
 "to": {
 "path": "has_sequence_number/has_value"
 }
 },
 {
 "from": {
 "path": "DataVersionName"
 },
 "to": {
 "path": "has_data_version_name/has_value"
 }
 }
 ]
 }
 ]
 }
 },
 {
 "definition": {
 "from": {
 "path": "MESSAGE/DEAL_SETS/DEAL_SET/DEALS/DEAL/PARTIES/PARTY",
 "filter": {
 "path": "ROLES/ROLE/ROLE_DETAIL/PartyRoleType",
 "IS_EQUAL": "NotePayTo"
 }
 },
 "to": {
 "path": "organizations"
 },
 "attribute_mappings": [
 {
 "from": {
 "value": "note_pay_to"
 },
 "to": {
 "path": "@type"
 }
 },
 {
 "from": {
 "path": "LEGAL_ENTITY/LEGAL_ENTITY_DETAIL/FullName"
 },
 "to": {
 "path": "has_organization_name/has_value"
 }
 }
 ]
 }
 }
 ]
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Forbidden

```
{
 "message": "Invalid Api Key"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Resource is not found

```
{
 "message": "Job not found."
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `id` required | `string` path | `01H1Y44CSD0CQ7Z26S7QTJ2EF5` | <!--source:api-specifications-->Job id<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
7 fields
<!--/source-->
<!--source:api-specifications-->
Rules Generation Status
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `id`required | `string` | <!--source:api-specifications-->Generation id<!--/source--> |
| `status`required | `string` | <!--source:api-specifications-->Generation status<!--/source-->`completed``failed``running` |
| `lang_from`required | `string` | <!--source:api-specifications-->Language to generate rules from<!--/source--> |
| `lang_to`required | `string` | <!--source:api-specifications-->Language to generate rules to<!--/source--> |
| `rules`required | `object[]` | <!--source:api-specifications-->Array of generated rules<!--/source--> |
| `definition`required | `string` | <!--source:api-specifications-->Rule definition<!--/source--> |
| `errors`required | `string[]` | <!--source:api-specifications-->Array of errors that occurred during generation.<!--/source--> |
| `statistics` | `object` | <!--source:api-specifications-->Statistics of the generated mappings.<!--/source--> |
| `mapped_properties_count`required | `integer` | <!--source:api-specifications-->The number of properties that were mapped.<!--/source--> |
| `unmapped_properties_count`required | `integer` | <!--source:api-specifications-->The number of properties that were not mapped.<!--/source--> |
| `coverage_ratio`required | `number (float)` | <!--source:api-specifications-->The percentage of properties that were mapped.<!--/source--> |
| `unmapped_properties`required | `string[]` | <!--source:api-specifications-->The array of unmapped properties.<!--/source--> |
| `mapped_properties`required | `object[]` | <!--source:api-specifications-->The array of mapped properties.<!--/source--> |
| `foreign_path`required | `string` | <!--source:api-specifications-->The path to the property in the foreign language.<!--/source--> |
| `staircase_path`required | `string` | <!--source:api-specifications-->The path to the property in the staircase language.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Forbidden
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Resource is not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

<!--source:api-specifications-->

### Monitoring Testing
<!--/source-->

`GET` `/testing/configurations`

<!--source:api-specifications-->

#### Get Testing Configurations
<!--/source-->

`getTestingConfigurations`

<!--source:api-specifications-->
**Retrieve registered testing configurations.

<!--/source-->

##### Response

<!--source:api-specifications-->
400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

##### Response `200``application/json`

<!--source:api-specifications-->
3 fields
<!--/source-->
<!--source:api-specifications-->
Configurations retrieved successfully
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `health_key` | `string` | <!--source:api-specifications-->Environment health key.<!--/source--> |
| `host_environment` | `string` | <!--source:api-specifications-->Environment domain name.<!--/source--> |
| `config_type` | `string` | <!--source:api-specifications-->Testing configuration type.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

`GET` `/testing/runs`

<!--source:api-specifications-->

#### List Testing Runs
<!--/source-->

`listTestingRuns`

<!--source:api-specifications-->
**Retrieve testing runs.

<!--/source-->

##### Response

<!--source:api-specifications-->
400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
2
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `testing_environment` | `string` query | `test.staircaseapi.com` | <!--source:api-specifications-->Testing Environment<!--/source--> |
| `test_run_invocation_type` | `string` query | `http` | <!--source:api-specifications-->Testing run invocation type<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
7 fields
<!--/source-->
<!--source:api-specifications-->
Testing run retrieved successfully
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `test_run_id` | `string` | <!--source:api-specifications-->Unique test run id.<!--/source--> |
| `test_run_status` | `string` | <!--source:api-specifications-->Test run status<!--/source--> |
| `test_run_invocation_type` | `string` | <!--source:api-specifications-->Test run invocation type.<!--/source--> |
| `test_run_result` | `object[]` | <!--source:api-specifications-->Test run result details.<!--/source--> |
| `test_worker_id` | `string` | <!--source:api-specifications-->Test run worker id.<!--/source--> |
| `expire_at` | `string` | <!--source:api-specifications-->Test run result expiration time.<!--/source--> |
| `created_at` | `string` | <!--source:api-specifications-->Test run creation time.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

`PUT` `/testing/configurations`

<!--source:api-specifications-->

#### Create Testing Configuration
<!--/source-->

`createTestingConfiguration`

<!--source:api-specifications-->
The primary function of this service is to enable the creation of testing configurations. The testing service, which is responsible for testing the language product against test cases generated from historical invocations, conducts multiple tests throughout the day. It should be noted that the test cases themselves are generated daily and have an expiration period of one month

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "health_key": "health-key",
 "host_environment": "lang.staircaseapi.com"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404422
<!--/source-->

<!--source:api-specifications-->
application/json Copy Configuration response

```
{
 "message": "Configuration created."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.

```
{
 "message": "Ruleset with name 'atomic_staircase-graph_TRANSLATE' cannot be deleted while it has rules. Please, delete all rules first and try again."
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `host_environment`required | `string` | <!--source:api-specifications-->Environment domain name.<!--/source--> |
| `health_key`required | `string` | <!--source:api-specifications-->Health key.<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Configuration response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Endpoint result message.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `422``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

`DELETE` `/testing/configurations/{host_environment}`

<!--source:api-specifications-->

#### Delete Testing Configuration
<!--/source-->

`deleteTestingConfiguration`

<!--source:api-specifications-->
This service removes configuration.

<!--/source-->

##### Response

<!--source:api-specifications-->
200403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Configuration response

```
{
 "message": "Configuration deleted."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `host_environment` required | `string` path | `lang.staircaseapi.com` | <!--source:api-specifications-->Environment domain name<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Configuration response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Endpoint result message.<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

`POST` `/testing/runs`

<!--source:api-specifications-->

#### Start Testing Run
<!--/source-->

`startTestingRun`

<!--source:api-specifications-->
The purpose of this service is to execute test cases in a specified environment. Upon invocation, the collected test cases will be run against the installed version of the Language product. Each individual run will be identified with a unique identifier, which will enable interested parties to query the corresponding result. It should be noted that the information pertaining to test run results will be valid for a period of two months before expiration

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "api_key": "api-key",
 "testing_environment": "lang.staircaseapi.com"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Test run response

```
{
 "test_run_id": "01GSWG340T18R53MK6YYS64DD7"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `testing_environment`required | `string` | <!--source:api-specifications-->Environment domain name.<!--/source--> |
| `api_key`required | `string` | <!--source:api-specifications-->API key.<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Test run response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `test_run_id` | `string` | <!--source:api-specifications-->Test run identifier.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

`GET` `/testing/runs/{test_run_id}`

<!--source:api-specifications-->

#### Get Testing Run
<!--/source-->

`getTestingRun`

<!--source:api-specifications-->
**Retrieve testing run.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Testing run retrieved successfully

```
{
 "expire_at": "1683887213",
 "test_run_status": "success",
 "created_at": "2023-03-13T10:26:53.444553+00:00",
 "test_run_id": "01GVD84EP2YPDWG6EMFH6K0NJZ",
 "finished_at": "2023-03-13T10:30:58.736202+00:00",
 "test_run_invocation_type": "http",
 "test_run_result": [
 {
 "summary": {
 "collected": "38",
 "passed": "38",
 "failed": "0",
 "error": "0",
 "xfailed": "0",
 "skipped": "0"
 },
 "local_path": "/tmp/tmpw52i9gi5/01GVD84EP2YPDWG6EMFH6K0NJZ/2023-02-19",
 "total_duration": "142.44527006149292",
 "failed_test_cases": [],
 "status": "OK"
 }
 ],
 "testing_environment": "test.staircaseapi.com",
 "test_worker_id": "language-testing-runner-worker:859b57c4-82d3-482e-8b30-afb3f66871d7",
 "logs": [
 "[Container] 2023/03/13 10:28:27 Entering phase BUILD\n",
 "[Container] 2023/03/13 10:28:27 Running command python3.9 testing_test_runner_codebuild_worker.py\n",
 "{\"level\":\"INFO\",\"location\":\"<module>:270\",\"message\":\"Test Runner Worker started for test run: 01GVD84EP2YPDWG6EMFH6K0NJZ...\",\"timestamp\":\"2023-03-13 10:28:28,685+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
 "{\"level\":\"INFO\",\"location\":\"prepare_test_files_for_test_run:168\",\"message\":\"Preparing tests for date:2023-02-19\",\"timestamp\":\"2023-03-13 10:28:31,853+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
 "{\"level\":\"INFO\",\"location\":\"prepare_test_files_for_test_run:170\",\"message\":\"Preparing tests for env:<redacted>-ce86d6bcfe.staircaseapi.com\",\"timestamp\":\"2023-03-13 10:28:31,853+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
 "{\"level\":\"INFO\",\"location\":\"prepare_test_files_for_test_run:195\",\"message\":\"Preparing test files finished /tmp/tmpw52i9gi5: 01GVD84EP2YPDWG6EMFH6K0NJZ\",\"timestamp\":\"2023-03-13 10:28:36,103+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
 "{\"level\":\"INFO\",\"location\":\"run_defined_tests:108\",\"message\":\"Running tests under /tmp/tmpw52i9gi5/01GVD84EP2YPDWG6EMFH6K0NJZ/2023-02-19\",\"timestamp\":\"2023-03-13 10:28:36,107+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
 "============================= test session starts ==============================\n",
 "platform linux -- Python 3.9.16, pytest-7.2.0, pluggy-1.0.0\n",
 "rootdir: /codebuild/output/src052753333/src\n",
 "plugins: xdist-3.2.1, mock-3.10.0\n",
 "gw0 I / gw1 I / gw2 I / gw3 I / gw4 I / gw5 I / gw6 I / gw7 I / gw8 I / gw9 I / gw10 I / gw11 I / gw12 I / gw13 I / gw14 I / gw15 I / gw16 I / gw17 I / gw18 I / gw19 I / gw20 I / gw21 I / gw22 I / gw23 I / gw24 I / gw25 I / gw26 I / gw27 I / gw28 I / gw29 I / gw30 I / gw31 I / gw32 I / gw33 I / gw34 I / gw35 I / gw36 I / gw37 I\n",
 "gw0 [38] / gw1 [38] / gw2 [38] / gw3 [38] / gw4 [38] / gw5 [38] / gw6 [38] / gw7 [38] / gw8 [38] / gw9 [38] / gw10 [38] / gw11 [38] / gw12 [38] / gw13 [38] / gw14 [38] / gw15 [38] / gw16 [38] / gw17 [38] / gw18 [38] / gw19 [38] / gw20 [38] / gw21 [38] / gw22 [38] / gw23 [38] / gw24 [38] / gw25 [38] / gw26 [38] / gw27 [38] / gw28 [38] / gw29 [38] / gw30 [38] / gw31 [38] / gw32 [38] / gw33 [38] / gw34 [38] / gw35 [38] / gw36 [38] / gw37 [38]\n",
 "\n",
 "...................................... [100%]{\"level\":\"INFO\",\"location\":\"run_defined_tests:133\",\"message\":\"Test result: 0\",\"timestamp\":\"2023-03-13 10:30:58,733+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
 "{\"level\":\"INFO\",\"location\":\"<module>:276\",\"message\":\"Test Runner Finished in 150.050298212\",\"timestamp\":\"2023-03-13 10:30:58,736+0000\",\"service\":\"Testing Test Runner Worker\"}\n",
 "\n",
 "======================== 38 passed in 142.45s (0:02:22) ========================\n",
 "\n",
 "[Container] 2023/03/13 10:30:58 Phase complete: BUILD State: SUCCEEDED\n",
 "[Container] 2023/03/13 10:30:58 Phase context status code: Message: \n",
 "[Container] 2023/03/13 10:30:58 Entering phase POST_BUILD\n",
 "[Container] 2023/03/13 10:30:58 Phase complete: POST_BUILD State: SUCCEEDED\n",
 "[Container] 2023/03/13 10:30:58 Phase context status code: Message: \n"
 ]
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `test_run_id` required | `string` path | `01GST3JQ3DZT2GJ8DBBATN9VQ4` | <!--source:api-specifications-->Test run identifier<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
9 fields
<!--/source-->
<!--source:api-specifications-->
Testing run retrieved successfully
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `test_run_id` | `string` | <!--source:api-specifications-->Unique test run id.<!--/source--> |
| `test_run_status` | `string` | <!--source:api-specifications-->Test run status<!--/source--> |
| `test_run_invocation_type` | `string` | <!--source:api-specifications-->Test run invocation type.<!--/source--> |
| `test_worker_id` | `string` | <!--source:api-specifications-->Test run worker id.<!--/source--> |
| `expire_at` | `string` | <!--source:api-specifications-->Test run result expiration time.<!--/source--> |
| `created_at` | `string` | <!--source:api-specifications-->Test run creation time.<!--/source--> |
| `finished_at` | `string` | <!--source:api-specifications-->Test run result finish time.<!--/source--> |
| `test_run_result` | `object[]` | <!--source:api-specifications-->Test run result details.<!--/source--> |
| `logs` | `string[]` | <!--source:api-specifications-->Test run logs<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

`PUT` `/monitoring/testing/data`

<!--source:api-specifications-->

#### Create Update Testing Data
<!--/source-->

`createUpdateTestingData`

<!--source:api-specifications-->
This endpoint enables users to create or update testing data in JSON format. The testing data can be either a translation file or a language file.

<!--/source-->

##### Request

<!--source:api-specifications-->
TestTranslationDataExampleTestLanguageDataExample
<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "file_path": "2023-03-12/test.staircaseapi.com/translations/staircase-graph_to_credit-input/111116VY6GRVSJVZV2CPCJYRYY_staircase-graph_to_credit-input.json",
 "payload": {
 "test": "data"
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "file_path": "2023-03-12/test.staircaseapi.com/languages/credit-input.json",
 "payload": {
 "test": "data"
 }
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404422
<!--/source-->

<!--source:api-specifications-->
application/json Copy Configuration response

```
{
 "message": "Test data created/updated."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.

```
{
 "message": "Ruleset with name 'atomic_staircase-graph_TRANSLATE' cannot be deleted while it has rules. Please, delete all rules first and try again."
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `file_path`required | `string` | <!--source:api-specifications-->Test data path.<!--/source--> |
| `payload`required | `string` | <!--source:api-specifications-->Test data payload.<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Configuration response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Endpoint result message.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `422``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

`GET` `/monitoring/testing/data/{file_path}`

<!--source:api-specifications-->

#### Get Testing Data
<!--/source-->

`getTestingData`

<!--source:api-specifications-->
This endpoint allows users to retrieve testing data in JSON format. The path to the testing data should be provided in the correct format, and it should be URL encoded.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Configurations retrieved successfully

```
{
 "test": "data"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `file_path` required | `string` path | `2023-03-10%test.staircaseapi.com%2Ftranslations%2Fcredit-mismo34_to_staircase-graph%2F01GV60FP5813DD0EXJ2PK7K422_credit-mismo34_to_staircase-graph.json` | <!--source:api-specifications-->Testing data path<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Other responses

`200`

`DELETE` `/monitoring/testing/data/{file_path}`

<!--source:api-specifications-->

#### Delete Testing Data
<!--/source-->

`deleteTestingData`

<!--source:api-specifications-->
This endpoint allows users to delete testing data with the provided path. Path should be URL encoded.

<!--/source-->

##### Response

<!--source:api-specifications-->
200403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Configuration response

```
{
 "message": "Testing data deleted."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `file_path` required | `string` path | `2023-03-10%test.staircaseapi.com%2Ftranslations%2Fcredit-mismo34_to_staircase-graph%2F01GV60FP5813DD0EXJ2PK7K422_credit-mismo34_to_staircase-graph.json` | <!--source:api-specifications-->Testing data path<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Configuration response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Endpoint result message.<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

`POST` `/testing/encryption/key`

<!--source:api-specifications-->

#### Register Testing Data Private Key
<!--/source-->

`RegisterTestingDataPrivateKey`

<!--source:api-specifications-->
Start Testing Run
<!--/source-->

<!--source:api-specifications-->
This endpoint enables users to register their private key for RSA encryption and decryption. The private key should be provided in the PEM format. Once the private key is registered, it can be used to decrypt the symmetric key that is used for decrypting the testing data.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "key": "<redacted>"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Key response

```
{
 "message": "Key registered"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "message": "{'data': ['Missing data for required field.']}"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "API key is not valid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Object not found"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `key`required | `string` | <!--source:api-specifications-->Private key.<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Key response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Key registered.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Message<!--/source--> |

<!--source:api-specifications-->

### Translate
<!--/source-->

`GET` `/translate/{translation_id}`

<!--source:api-specifications-->

#### Retrieve Translation Status
<!--/source-->

`retrieveTranslatedPayload`

<!--source:api-specifications-->
Retrieve Translation Status retrieves a translation status and the result, if available. The response will contain a signed URL for the file containing the result. This file will contain both the returned data and any warnings or errors detected during translation.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Translation status

```
{
 "status": "SUCCEEDED",
 "translation_id": "8519db-f03b-4a13-885b-5d67d338ea0",
 "started_at": "2021-11-04 12:18:08.903000+00:00",
 "translation": {
 "output_url": "https://example_file.json?Expires=1627597250",
 "mimetype": "application/json"
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Language not found"
}
```

<!--/source-->

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `translation_id` required | `string` path | `f618ce80-dg5b-4ce2-9996-9d1d3240864d` | <!--source:api-specifications-->Translation ID<!--/source--> |

##### Response `200``application/json`

<!--source:api-specifications-->
4 fields
<!--/source-->
<!--source:api-specifications-->
Translation status
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | <!--source:api-specifications-->Status description<!--/source--> |
| `translation_id` | `string` | <!--source:api-specifications-->Translation ID<!--/source--> |
| `started_at` | `string` | <!--source:api-specifications-->Time when translation started in DateTime format<!--/source--> |
| `translation` | `object` | <!--source:api-specifications-->Signed URL for the document containing the output and media type of the translation<!--/source--> |
| `output_url` | `string` | <!--source:api-specifications-->Signed URL for the document containing the output<!--/source--> |
| `mimetype` | `string` | <!--source:api-specifications-->Media type of the translation<!--/source-->`application/json``application/xml` |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

`POST` `/translate`

<!--source:api-specifications-->

#### Translate Received Payload
<!--/source-->

`translateReceivedPayload`

<!--source:api-specifications-->
Translating a received payload
<!--/source-->

<!--source:api-specifications-->
Translate Received Payload translates any valid object in the Staircase data model from one language to another. Languages are identified by language_name.

In the request body, provide the language to translate from (lang_from), the language to translate to (lang_to). Call Retrieve Languages to retrieve language_name(s) for languages that exist in your environment.

Also, in the request body, provide both a valid Staircase data model object or snippet to be translated (data), and the version of Staircase language that the data model object/snippet belongs to. Call Retrieve Data Model Schema to retrieve a complete Staircase data model schema and all objects contained within.

Can also be used to translate between different staircase language/lexicon versions. Set 'lang_from' and 'lang_to' to 'staircase', and use sc_version_from, sc_version_to query parameters. See /lexicon for more info.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{ 'data': 'object data in customer_lang format', 'lang_from':'customer_lang', 'lang_to':'staircase' }
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200202400403404
<!--/source-->

<!--source:api-specifications-->
application/json Copy 200 response

```
{
 "type": "employment",
 "permissible_purpose": "risk-assessment",
 "target": {
 "first_name": "First",
 "last_name": "Last",
 "social_security_number": "***-**-9999",
 "contact_email": "joesmith@example.org",
 "company": {
 "name": "Truework Inc"
 }
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Async translation accepted

```
{
 "translation_id": "8519db-f03b-4a13-885b-5d67d338ea0",
 "started_at": "2021-11-04 12:18:08.903000+00:00",
 "callback_url": "https://webhook.site/6788842-f03b-4a13-885b-5d67d338ea09"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data failed validation

```
{
 "MissingData": {
 "message": "{'data': ['Missing data for required field.']}"
 },
 "ValidationFailed": {
 "message": "Invalid v0 paths detected",
 "invalid_paths": [
 {
 "path": "$.deal_set.pawrty[0].individual.name.first",
 "message": "Could not find the given path"
 },
 {
 "path": "deal_set.partie[0].individual.name.last",
 "message": "All valid paths are expected to start with $."
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request is forbidden, API key is not valid

```
{
 "message": "Your API key is not valid, please refresh it."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Requested resource not found

```
{
 "message": "Language not found"
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
11 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `lang_from`required | `string` | <!--source:api-specifications-->Language of the payload<!--/source--> |
| `lang_to`required | `string` | <!--source:api-specifications-->Language of the desired translation<!--/source--> |
| `include_missing` | `boolean` | <!--source:api-specifications-->Include mapped fields in output even if originals don't exist in input<!--/source--> |
| `apply_lexicon_types` | `boolean` | <!--source:api-specifications-->Validates and converts output values according to their types specified in lexicon. Works only for translation to staircase v0 language.<!--/source--> |
| `data`required | `object` | <!--source:api-specifications-->Any object in a valid Staircase model<!--/source--> |
| `version` | `integer` | <!--source:api-specifications-->Version of staircase language<!--/source-->`0``1` |
| `metadata` | `object` | <!--source:api-specifications-->Any metadata about this translation<!--/source--> |
| `transaction_id` | `string` | <!--source:api-specifications-->Transaction ID associated with this translation. This value will be used in reporting to Health.<!--/source--> |
| `collection_id` | `string` | <!--source:api-specifications-->Collection ID associated with this translation. This value will be used in reporting to Health.<!--/source--> |
| `sc_version_from` | `integer` | <!--source:api-specifications-->For staircase to staircase translations - when lang_from and lang_to are staircase<!--/source--> |
| `sc_version_to` | `integer` | <!--source:api-specifications-->For staircase to staircase translations = when lang_from and lang_to are staircase<!--/source--> |
| `async` | `boolean` | <!--source:api-specifications-->When false, translation will be returned in a synchronous manner. If async is turned on, translation and translation status will need to be retrieved via Retrieve Translation.<!--/source--> |
| `callback_url` | `string` | <!--source:api-specifications-->Webhook URL to receive translation result<!--/source--> |

##### Response `202``application/json`

<!--source:api-specifications-->
3 fields
<!--/source-->
<!--source:api-specifications-->
Async translation accepted
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `translation_id` | `string` | <!--source:api-specifications-->Translation ID<!--/source--> |
| `started_at` | `string` | <!--source:api-specifications-->Time when translation started in DateTime format<!--/source--> |
| `callback_url` | `string` | <!--source:api-specifications-->Webhook URL to receive translation result<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request data failed validation
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | <!--source:api-specifications-->Error message<!--/source--> |
| `invalid_paths` | `object[]` | <!--source:api-specifications-->Details about the request and invalidity<!--/source--> |
| `path` | `string` | <!--source:api-specifications-->Path from the request<!--/source--> |
| `message` | `string` | <!--source:api-specifications-->Details about invalidity<!--/source--> |

##### Response `403``application/json`

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Request is forbidden, API key is not valid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->API URL<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Requested resource not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Other responses

`200``422`

<!--source:api-specifications-->

### Language Operations
<!--/source-->

`POST` `/product/products/language/invocations`

<!--source:api-specifications-->

#### Extended Translate
<!--/source-->

`extendedTranslate`

<!--source:api-specifications-->
Current Endpoint performs extended translation service, which includes invocation extension and entity translation along with regular translation.

In order to execute extended translation workflow provide `from_language`, `to_language` and `data` fields in the `request_data` object. Operation is async, in order to check status input "language" as `product_name` and returned `invocation_id` to retrieve status endpoint.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "request_data": {
 "from_language": "staircase-graph",
 "to_language": "test_language_1",
 "data": {
 "invocations": [
 {
 "has_invocation_code_type": {
 "has_value": "40004"
 }
 }
 ],
 "graph_entities": [
 {
 "has_data_path": {
 "has_value": "person/has_first_name"
 }
 }
 ]
 }
 }
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
202400404
<!--/source-->

<!--source:api-specifications-->
application/json Copy Generated rules

```
{
 "product_flow_name": "language-translation-workflow",
 "metadata": {},
 "response_collection_id": "01H7SQAMJ98YT3D0KJ9W99D647",
 "invocation_mode": "single_flow",
 "widget_url": "",
 "invocation_id": "01H7SQAMJ98YT3D0KJ9W99D647",
 "invocation_status": "STARTED",
 "transaction_id": "01H7SQAK56R1DB10255J2M780K",
 "request_collection_id": "01H7SQAMTH9A84SEBDMSCNCET5",
 "request_data": {
 "from_language": "staircase-graph",
 "to_language": "test_language_1",
 "data": {
 "invocations": [
 {
 "has_invocation_code_type": {
 "has_value": "40004"
 }
 }
 ],
 "graph_entities": [
 {
 "has_data_path": {
 "has_value": "person/has_first_name"
 }
 }
 ]
 }
 },
 "api_id": null,
 "_links": {
 "health_metrics": "https://bushnell.staircaseapi.com/code-health-checker/metric/01H7SQAK56R1DB10255J2M780K?product_name=language"
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Request data invalid

```
{
 "message": "Request body is invalid."
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Resource is not found

```
{
 "message": "Job not found."
}
```

<!--/source-->

##### Request body`application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `request_data` | `object` | <!--source:api-specifications-->Request data.<!--/source--> |
| `from_language` | `string` | <!--source:api-specifications-->Language name to translate from.<!--/source--> |
| `to_language` | `string` | <!--source:api-specifications-->Language name to translate to.<!--/source--> |
| `data` | `object` | <!--source:api-specifications-->Content to translate.<!--/source--> |

##### Response `202``application/json`

<!--source:api-specifications-->
9 fields
<!--/source-->
<!--source:api-specifications-->
Generated rules
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `product_flow_name` | `string` | <!--source:api-specifications-->Name of the executed product flow.<!--/source--> |
| `invocation_id` | `string` | <!--source:api-specifications-->Invocation ID.<!--/source--> |
| `invocation_status` | `string` | <!--source:api-specifications-->Invocation Status.<!--/source-->`ACTION_REQUIRED``COMPLETED``FAILED``RUNNING``STARTED` |
| `transaction_id` | `string` | <!--source:api-specifications-->Transaction ID used for invocation.<!--/source--> |
| `request_collection_id` | `string` | <!--source:api-specifications-->Request Collection ID.<!--/source--> |
| `request_data` | `object` | <!--source:api-specifications-->Input data.<!--/source--> |
| `response_collection_id` | `string` | <!--source:api-specifications-->Response Collection ID.<!--/source--> |
| `widget_url` | `string (uri)` | <!--source:api-specifications-->URL of the widget.<!--/source--> |
| `metadata` | `object` | <!--source:api-specifications-->Response collection metadata.<!--/source--> |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Request data invalid
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

##### Response `404``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Resource is not found
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |

<!--source:api-specifications-->

### Operations
<!--/source-->

`POST` `/hello-world`

<!--source:api-specifications-->

#### Hello World
<!--/source-->

<!--source:api-specifications-->
Dummy hello world endpoint

<!--/source-->

##### Other responses

`200`

`GET` `/info`

<!--source:api-specifications-->

#### Info endpoint
<!--/source-->

<!--source:api-specifications-->
Placeholder endpoint. As this is a language repo, it must be used in conjunction with the Translator Service.

<!--/source-->

##### Other responses

`200`

`POST` `/languages`

<!--source:api-specifications-->

#### Export language
<!--/source-->

`export_language`

##### Parameters

<!--source:api-specifications-->
1
<!--/source-->

| Parameter | Type | Description |
| --- | --- | --- |
| `x-api-key` required | `string` header | <!--source:api-specifications-->API key<!--/source--> |

##### Request body`application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `langugage_description_url` | `string` | — |

##### Response `201``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
201 response
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | — |

##### Response `400``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
No language by specified url
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

## Errors

`400``403``404``422``500`

## More in Data

- Previous product: Content
- Next product: ML