<!-- https://staircase.co/products/verification/income -->
# Income

# Income

Income verification and derivation across a vendor roster, with a model-based derivation path routed as one more vendor.

A caller sends a borrower. The product works down the ordering below and returns canonical income records — employer, pay frequency, amounts, and the period each covers.

Where no vendor holds a record, a derivation path reads the documents already attached to the file and produces income figures from them. It sits in the same ordering as the data vendors rather than in a separate branch.

## How it works

Derivation is routed as a vendor rather than run as a fallback mode. A caller receives the same response shape either way, and the record carries which vendor produced it, so a downstream qualification step can weigh a derived figure differently without a second code path.

Income and employment are separate products because they answer separate questions and their vendor rosters differ, even though several vendors appear on both.

## Dual listing

Income is filed under two categories. The other listing is Income under Automation, and neither listing carries a recorded specification.

## Operations

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

### Partners
<!--/source-->

`GET` `/partners`

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

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

`retrievePartners`

<!--source:api-specifications-->
Retrieve Partners retrieves an object containing all active partners for income verification and details about the partner. Use the `partner` property to invoke the partner directly in the product invocation.

<!--/source-->

##### Response

<!--source:api-specifications-->
application/json Copy Successfully returned the partner object

```
[
 {
 "partner": "partner_name_1",
 "active": true,
 "byoc": true,
 "order": 1,
 "status": "active",
 "verification_type": "borrower"
 },
 {
 "partner": "partner_name_2",
 "active": true,
 "byoc": false,
 "order": 2,
 "status": "active",
 "verification_type": "instant"
 },
 {
 "partner": "partner_name_3",
 "active": false,
 "byoc": true,
 "order": 3,
 "status": "upcoming",
 "verification_type": "manual"
 }
]
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

<!--source:api-specifications-->
6 fields
<!--/source-->
<!--source:api-specifications-->
Successfully returned the partner object
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `byoc` | `boolean` | <!--source:api-specifications-->If value is set to "True", customer must add its own partner credentials to be able to use this partner for verification.<!--/source--> |
| `active` | `boolean` | <!--source:api-specifications-->If set to "True" partner can be used for verification. If set to "False" partner will be disabled for verification and excluded from the waterfall.<!--/source--> |
| `status` | `string` | <!--source:api-specifications-->Parameter for documentation. Can be set to "active" and "upcoming".<!--/source--> |
| `verification_type` | `string` | <!--source:api-specifications-->If value is set to "borrower", borrower needs to authorize verification process via provided URL. Whether value is set to "instant", verification process is done without any third party interventions. If value is set to "manual", verification process needs to be approved manually by selected data partner (Truework partner only).<!--/source-->`borrower``instant``manual` |
| `partner` | `string` | <!--source:api-specifications-->Partner name.<!--/source--> |
| `order` | `integer` | <!--source:api-specifications-->Order value provides priority on waterfall execution, where number 1 represents the highest priority and such will be executed first in the waterfall feature.<!--/source--> |

##### Other responses

`403`

`GET` `/product/income/partners`

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

#### Retrieve Product Partners
<!--/source-->

`getVendors`

<!--source:api-specifications-->
Retrieve Partners retrieves:

-All the Partners (vendors) configured in the Product Flows configurations.

-The Order of the partner in the Product Waterfall Settings or default order in Product Flows if Product Waterfall was not configured.

-The status of the partners as active/upcoming according to the configurations of the product flows of these partners (partner will be active if at least one flow is active).'

<!--/source-->

##### Response

<!--source:api-specifications-->
application/json Copy Successfully returned the partner object

```
[
 {
 "partner": "partner_name_1",
 "active": true,
 "byoc": true,
 "order": 1,
 "status": "active",
 "verification_type": "borrower"
 },
 {
 "partner": "partner_name_2",
 "active": true,
 "byoc": false,
 "order": 2,
 "status": "active",
 "verification_type": "instant"
 },
 {
 "partner": "partner_name_3",
 "active": false,
 "byoc": true,
 "order": 3,
 "status": "upcoming",
 "verification_type": "manual"
 }
]
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `active` | `boolean` query | `false` | <!--source:api-specifications-->Include vendors with active product flows<!--/source--> |

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

<!--source:api-specifications-->
6 fields
<!--/source-->
<!--source:api-specifications-->
Successfully returned the partner object
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `byoc` | `boolean` | <!--source:api-specifications-->If value is set to "True", customer must add its own partner credentials to be able to use this partner for verification.<!--/source--> |
| `active` | `boolean` | <!--source:api-specifications-->If set to "True" partner can be used for verification. If set to "False" partner will be disabled for verification and excluded from the waterfall.<!--/source--> |
| `status` | `string` | <!--source:api-specifications-->Parameter for documentation. Can be set to "active" and "upcoming".<!--/source--> |
| `verification_type` | `string` | <!--source:api-specifications-->If value is set to "borrower", borrower needs to authorize verification process via provided URL. Whether value is set to "instant", verification process is done without any third party interventions. If value is set to "manual", verification process needs to be approved manually by selected data partner (Truework partner only).<!--/source-->`borrower``instant``manual` |
| `partner` | `string` | <!--source:api-specifications-->Partner name.<!--/source--> |
| `order` | `integer` | <!--source:api-specifications-->Order value provides priority on waterfall execution, where number 1 represents the highest priority and such will be executed first in the waterfall feature.<!--/source--> |

##### Other responses

`403`

`GET` `/partners/ordering`

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

#### Retrieve Partners Ordering
<!--/source-->

`getPartnersOrdering`

<!--source:api-specifications-->
Get Partners Ordering
<!--/source-->

<!--source:api-specifications-->
Retrieve Partners Ordering returns the partner ordering, for Verification Income waterfall execution.

Product will execute waterfall process only in case you are using default as partner parameter (instead of partner name) for Verify Income

For example if partner5 has order set to 1 we will try to use it before partner1 with order set to 2.

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Successfully received ordering of the partners

```
[
 {
 "partner": "partner1",
 "order": 1
 },
 {
 "partner": "partner2",
 "order": 2
 }
]
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Successfully received ordering of the partners
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `partner_order` | `object` | <!--source:api-specifications-->Partner and order<!--/source--> |
| `partner` | `string` | Example `partner1` |
| `order` | `number` | Example `1` |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

`GET` `/products/income/partners/ordering`

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

#### Retrieve Partners Ordering
<!--/source-->

`getPartnersOrdering`

<!--source:api-specifications-->
Get Partners Ordering
<!--/source-->

<!--source:api-specifications-->
Retrieve Partners Ordering returns the partner ordering, for Verification Income waterfall execution.

Product will execute waterfall process only in case you are using default as partner parameter (instead of partner name) for Verify Income

For example if partner5 has order set to 1 we will try to use it before partner1 with order set to 2.

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Successfully received ordering of the partners

```
[
 {
 "partner": "partner1",
 "order": 1
 },
 {
 "partner": "partner2",
 "order": 2
 }
]
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Successfully received ordering of the partners
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `partner_order` | `object` | <!--source:api-specifications-->Partner and order<!--/source--> |
| `partner` | `string` | Example `partner1` |
| `order` | `number` | Example `1` |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

`PUT` `/partners/ordering`

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

#### Update Partners Ordering
<!--/source-->

`updatePartnersOrdering`

<!--source:api-specifications-->
Update Partners Order updates the order of execution during Verify Income for all partners in the product.

We allow our customers an option to use preferred partner in ordering they select. Ordering with lower number has priority in product execution.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "ordering": [
 {
 "partner": "partner1",
 "order": 1
 },
 {
 "partner": "partner2",
 "order": 10
 }
 ]
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Successfully updated order for partners

```
{
 "message": "Partner ordering updated!"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Failed to update the partner from one of the reasons

```
{
 "message": "Partner doesn't exist in database"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `ordering` | `object[]` | — |
| `partner` | `string` | <!--source:api-specifications-->Partner name<!--/source-->Example `wage` |
| `order` | `number` | <!--source:api-specifications-->Partner order<!--/source-->Example `1` |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Successfully updated order for partners
<!--/source-->

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

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Failed to update the partner from one of the reasons
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Partner doesn't exist in database<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

`PUT` `/products/income/partners/ordering`

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

#### Update Partners Ordering
<!--/source-->

`updatePartnersOrdering`

<!--source:api-specifications-->
Update Partners Order updates the order of execution during Verify Income for all partners in the product.

We allow our customers an option to use preferred partner in ordering they select. Ordering with lower number has priority in product execution.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "ordering": [
 {
 "partner": "partner1",
 "order": 1
 },
 {
 "partner": "partner2",
 "order": 10
 }
 ]
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Successfully updated order for partners

```
{
 "message": "Partner ordering updated!"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Failed to update the partner from one of the reasons

```
{
 "message": "Partner doesn't exist in database"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `ordering` | `object[]` | — |
| `partner` | `string` | <!--source:api-specifications-->Partner name<!--/source-->Example `wage` |
| `order` | `number` | <!--source:api-specifications-->Partner order<!--/source-->Example `1` |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Successfully updated order for partners
<!--/source-->

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

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Failed to update the partner from one of the reasons
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Partner doesn't exist in database<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

`GET` `/partners/{partner}/schema`

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

#### Retrieve Partner Credentials Schema
<!--/source-->

`getPartnerSchema`

<!--source:api-specifications-->
Retrieve Partner Credentials Schema retrieves the required partner schema for credentials.

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Successfully returned the partner schema object

```
{
 "$schema": "http://json-schema.org/draft-07/schema",
 "$id": "http://example.com/example.json",
 "type": "object",
 "title": "Partner root schema",
 "description": "Partner credentials schema for connector flows.",
 "webhook": false,
 "default": {},
 "examples": [
 {
 "key1": "value1",
 "key2": "value2"
 }
 ],
 "required": [
 "key1",
 "key2"
 ],
 "properties": {
 "key1": {
 "$id": "#/properties/key1",
 "type": "string",
 "title": "Partner key1 schema",
 "description": "Partner key1",
 "default": "",
 "examples": [
 "value1"
 ]
 },
 "key2": {
 "$id": "#/properties/key2",
 "type": "string",
 "title": "Partner key2 schema",
 "description": "Partner key2",
 "default": "",
 "examples": [
 "value2"
 ]
 }
 },
 "additionalProperties": true
}
```

<!--/source-->

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

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

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `partner` required | `string` path | `partner_name` | <!--source:api-specifications-->Name of the partner for which we wan't to retrieve schema<!--/source--> |

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

<!--source:api-specifications-->
10 fields
<!--/source-->
<!--source:api-specifications-->
Successfully returned the partner schema object
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `schema` | `string` | <!--source:api-specifications-->Schema URL<!--/source--> |
| `id` | `string` | <!--source:api-specifications-->Schema ID<!--/source--> |
| `type` | `string` | <!--source:api-specifications-->JSON type<!--/source--> |
| `title` | `string` | <!--source:api-specifications-->Schema title<!--/source--> |
| `description` | `string` | <!--source:api-specifications-->Schema description<!--/source--> |
| `webhook` | `boolean` | <!--source:api-specifications-->Value that indicates if partner requires webhook setup<!--/source--> |
| `default` | `object` | <!--source:api-specifications-->Default value for schema<!--/source--> |
| `examples` | `object[]` | <!--source:api-specifications-->List of examples<!--/source--> |
| `key1` | `string` | <!--source:api-specifications-->Example 1<!--/source--> |
| `key2` | `string` | <!--source:api-specifications-->Example 2<!--/source--> |
| `required` | `string[]` | <!--source:api-specifications-->Required fields<!--/source--> |
| `properties` | `object` | <!--source:api-specifications-->Properties of Schema<!--/source--> |
| `key1` | `object` | <!--source:api-specifications-->Key 1 Schema<!--/source--> |
| `id` | `string` | <!--source:api-specifications-->Property ID<!--/source--> |
| `type` | `string` | <!--source:api-specifications-->Property value type<!--/source--> |
| `title` | `string` | <!--source:api-specifications-->Title for property<!--/source--> |
| `description` | `string` | <!--source:api-specifications-->Description for property<!--/source--> |
| `default` | `string` | <!--source:api-specifications-->Default value if exists<!--/source--> |
| `examples` | `string[]` | <!--source:api-specifications-->List of examples for given property<!--/source--> |
| `key2` | `object` | <!--source:api-specifications-->Key 2 Schema<!--/source--> |
| `id` | `string` | <!--source:api-specifications-->Property ID<!--/source--> |
| `type` | `string` | <!--source:api-specifications-->Property value type<!--/source--> |
| `title` | `string` | <!--source:api-specifications-->Title for property<!--/source--> |
| `description` | `string` | <!--source:api-specifications-->Description for property<!--/source--> |
| `default` | `string` | <!--source:api-specifications-->Default value if exists<!--/source--> |
| `examples` | `string[]` | <!--source:api-specifications-->List of examples for given property<!--/source--> |

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

`PUT` `/partners/{partner}/status`

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

#### Update Partner Status
<!--/source-->

`updatePartnerStatus`

<!--source:api-specifications-->
Update Partner Status updates the active parameter of a partner to either true or false. Set partner name that you want to enable/disable.

If partner has active set to false you won't be able to use this partner when doing income verification or while using Company Search.

If partner has active set to true you will be able to use this partner when doing income verification and for Company Search.

Please note that a given partner can only be activated if credentials are set, please use the Setup endpoints to set credentials.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "active": true
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Successfully updated active parameter for the partner

```
{
 "message": "Partner status updated!"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Failed to update the partner from one of the reasons

```
{
 "message": "Partner doesn't exist in database"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `partner` required | `string` path | `partner_name` | <!--source:api-specifications-->Name of the partner for which we wan't to update status<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `active`required | `boolean` | Example `true` |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Successfully updated active parameter for the partner
<!--/source-->

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

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Failed to update the partner from one of the reasons
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Partner doesn't exist in database<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

`PATCH` `/products/income/partners/{partner}/status`

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

#### Update Partner Status
<!--/source-->

`updatePartnerStatus`

<!--source:api-specifications-->
Update Partner Status updates the active parameter of a partner to either true or false. Set partner name that you want to enable/disable.

If partner has active set to false you won't be able to use this partner when doing income verification or while using Company Search.

If partner has active set to true you will be able to use this partner when doing income verification and for Company Search.

Please note that a given partner can only be activated if credentials are set, please use the Setup endpoints to set credentials.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "active": true
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Successfully updated active parameter for the partner

```
{
 "message": "Partner status updated!"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Failed to update the partner from one of the reasons

```
{
 "message": "Partner doesn't exist in database"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `partner` required | `string` path | `partner_name` | <!--source:api-specifications-->Name of the partner for which we wan't to update status<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `active`required | `boolean` | Example `true` |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Successfully updated active parameter for the partner
<!--/source-->

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

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Failed to update the partner from one of the reasons
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Partner doesn't exist in database<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

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

### Workflow
<!--/source-->

`POST` `/products/income/invocations`

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

#### Verify Income
<!--/source-->

`invokeProductFlow`

<!--source:api-specifications-->
Verify Income creates a verification request for provided transaction, collection and selected partner.

To better understand how to use this endpoint and how the entire income flow works check out the Overview Page and the detailed tutorial.

To invoke Income, you will need:

- a transaction_id, and
- a collection_id with valid data.

To get correct information from the income product, creating the request collection is extremely important. Hence, we heavily recommend looking at Create Collection documentation before this one.

Show the rest

#### Verification options

Manual Verification parameter

The manual_verification option enables you to add or remove partners that perform manual income verifications. When manual_verification=false, Income will exclude all partners performing manual VOI. This limits the search for partners performing VOI, and also reduces the time it takes to complete a VOI.

Exclude Borrower parameter

The exclude_borrower option enables you to remove the borrower from the VOI loop. When exclude_borrower=false, the borrower must provide credentials for Income verification prior to the partner performing the VOI. This increases borrower interaction, and also increases the chance that the VOI will be successfully completed.

The borrower needs to authorize the verification by entering payroll provider or bank credentials to the URL (widget_url) provided in the verification response. Call Retrieve Partners to retrieve test credentials for partners that have the borrower in the loop.

Instant Verification parameter

The instant_verification option enables you to add or remove partners that perform instant verifications. When instant_verification=true, Income will use all partners performing instant verification. This can limit the search for partners performing VOI, and also reduces the time it takes to complete a VOI.

Partner name parameter

The partner_name option enables you to select a preferred partner, or use "default" as the value. If you use "default" as the partner_name, Income will find the best match and use that partner for verification process. If you want to use a specific partner, call Retrieve Partners to see all income verification partners.

Callback URL parameter

The callback_url option enables you to send a URL with the request. This URL will be used to send a callback when the verification process status changes, including changes in status of underlying service invocations.

Send SMS parameter

The send_sms option enables you to send an SMS to the borrower when an authorization for the verification is needed. The default SMS text is "Lender has provided verification link to your E-mail address, please open link in browser, and finish verification process", if you wish to change the default SMS text you can send an optional sms_text parameter with your custom text message.

Send Email parameter

The send_email option enables you to email the borrower when an authorization for the verification is needed. The Email will be sent to the email address specified in the input collection. The Email uses the standard email template voi_email_template, if you wish to update the template please refer to the Update Email Template documentation. Please note that the template takes in two passed variables, which are the applet URL and employer_name, and those are required variables and should not be altered, for more info check the Email Product section.

Redirect URL parameter

Providing the redirect_url is optional and allows you to redirect the borrower to a URL of your choosing after linking the borrower's income verification. If left empty or no options parameter is passed, this URL defaults to the Staircase homepage.

If the waterfall feature is enabled, partner is selected based on the partner ordering.

To use the waterfall feature set the partner name to default. This way verification will be executed following the ordering for all available data partners. Use Update Partners Ordering and Retrieve Partners Ordering to set and get the orderings. If two data partners share the same legal entity full name the verification will be done based on the ordering of data partners.

Verify Income returns, as a synchronous acknowledgement, a new collection_id. The new collection_id represents an empty container which will hold the partner's response once processing has completed.

Some Partners require the borrower to authenticate, if the response contains the `url` property then the URL should be forwarded to the borrower and authenticated. The url is valid until the `expiration_time` which is denoted in EST.

Use the newly returned collection_id together with transaction_id in Retrieve Collection to get verification result.

#### Monitoring the health of the Income product

The Income product is integrated with the Health product, a cloud-based DevOps service that monitors the health of APIs. With the help of Health product, you can monitor the process of verification. To check the health of the Income product, you can use the create async health query execution API. This API allows you to specify a time period, a response collection ID ("id" returned as result of Income verification), and a product or API identifier. Here are the relevant product and API identifiers for the Income product:

- Income Product Identifier: 64b4b099-2ec6-448c-a33e-8c15dd167ab1
- Income Verification API ID: d1b1e55b-7398-4cb6-9e6f-d7ab3e5b83d4

To check the health after submitting a new Income verification request, you can use the following request payload:

```
{
 "start_date": "2023-01-28T00:00:00",
 "end_date": "2023-12-29T23:59:59",
 "response_collection_id": "01GNPTVCE9E737Y7HFEK9QKQRV",
 "product_identifier": "64b4b099-2ec6-448c-a33e-8c15dd167ab1",
 "product_api_identifier": "d1b1e55b-7398-4cb6-9e6f-d7ab3e5b83d4",
}
```

To check the overall health of your income transaction, you can use the following request payload:

```
{
 "start_date": "2023-01-28T00:00:00",
 "end_date": "2023-12-29T23:59:59",
 "response_collection_id": "01GNPTVCE9E737Y7HFEK9QKQRV",
 "product_identifier": "d1b1e55b-7398-4cb6-9e6f-d7ab3e5b83d4"
}
```

To retrieve the results of your health query, use the get async health query result API. This API takes the query execution ID returned by the create async health query execution API as a parameter. When you retrieve the results of your health query, you should see at least one health metric with corresponding status information (e.g. "SUCCEEDED", "FAILED").

##### Setting up alarms

You can set up alarms to be notified when the health of the Income product. To do this, use the create_health_alarm API. This API allows you to specify a threshold value and a notification method.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
 "collection_id": "01F0KHKADN0HRFXMCQQXPA6AFZ",
 "partner_name": "Partner",
 "callback_url": "https://webhook.site/1234",
 "options": {
 "manual_verification": true,
 "exclude_borrower": false,
 "instant_verification": true,
 "send_sms": false
 }
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400 MissingTransactionID400 MissingCollectionID400 MissingPartnerName400 InvalidPartnerName400 InvalidJSONBody403404422 InvalidTransactionIDFormat422 InvalidCollectionIDFormat
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request for Verification of Income created successfully. Please take the contained widget_url and forward it to the borrower. The url is valid until the `expiration_time`. The `expiration_time` is denoted in EST.

```
{
 "collection_id": "01F0KHKADN0HRFXMCQQXPA6AFZ",
 "url": "www.staircase.co",
 "expiration_time": "2021-04-22T12:51:25-04:00"
}
```

<!--/source-->

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

```
{
 "message": "Please make sure your body contains transaction_id."
}
```

<!--/source-->

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

```
{
 "message": "Please make sure your body contains collection_id"
}
```

<!--/source-->

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

```
{
 "message": "Please make sure your body contains partner_name"
}
```

<!--/source-->

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

```
{
 "message": "Please provide a valid partner name. To get available partners, you can use /partners endpoint."
}
```

<!--/source-->

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

```
{
 "message": "Request body had invalid format. Please provide a valid JSON"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Unable to get collection. Please check input collection id"
}
```

<!--/source-->

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

```
{
 "message": "transaction_id value had non-alphanumeric characters. Please check transaction id"
}
```

<!--/source-->

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

```
{
 "message": "collection_id value had non-alphanumeric characters. Please check collection id"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string (ulid)` | <!--source:api-specifications-->Staircase Transaction Identifier<!--/source-->Example `01F0KHK7DN3H5JZ4QJKMYAM6GB` |
| `collection_id`required | `string (ulid)` | <!--source:api-specifications-->Staircase Collection Identifier<!--/source-->Example `01F0KHKADN0HRFXMCQQXPA6AFZ` |
| `partner_name` | `string` | <!--source:api-specifications-->To get available partners, you can use /partners endpoint<!--/source--> |
| `callback_url` | `string` | <!--source:api-specifications-->Callback URL - will be used by product to send a callback when the invocation status changes.<!--/source--> |
| `options` | `object` | <!--source:api-specifications-->You can use options to customize the verification<!--/source--> |
| `manual_verification` | `boolean` | <!--source:api-specifications-->This option allows us to add partners that perform manual verification to your search list while finding the most suitable partner for you. This option takes a longer time and gives you a broader search.<!--/source--> |
| `exclude_borrower` | `boolean` | <!--source:api-specifications-->Some of our partners include borrowers in the loop while executing the verification. Income is verified by requesting information from borrower. If you want to exclude the borrower from the process, you must select *exclude_borrower* = *true* in options.<!--/source--> |
| `instant_verification` | `boolean` | <!--source:api-specifications-->This option allows us to add partners that perform instant verification to the search list while finding the most suitable partner for VOI.<!--/source--> |
| `send_sms` | `boolean` | <!--source:api-specifications-->This option allows us to send SMS to the borrower when an authorization for the verification is needed. The SMS text is "Lender has provided verification link to your E-mail address, please open link in browser, and finish verify process"<!--/source--> |
| `send_email` | `boolean` | <!--source:api-specifications-->If set to True, product will email the borrower when an authorization for the verification is needed. The Email will contain the URL to the authorization and the Company name.<!--/source--> |

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

<!--source:api-specifications-->
3 fields
<!--/source-->
<!--source:api-specifications-->
Request for Verification of Income created successfully. Please take the contained widget_url and forward it to the borrower. The url is valid until the `expiration_time`. The `expiration_time` is denoted in EST.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `collection_id` | `string (ulid)` | <!--source:api-specifications-->Staircase Collection Identifier<!--/source-->Example `01F0KHKADN0HRFXMCQQXPA6AFZ` |
| `url` | `string` | <!--source:api-specifications-->URL that needs to be sent to the borrower<!--/source--> |
| `expiration_time` | `string (date-time)` | <!--source:api-specifications-->Expiration time in EST. The operation will result in failure after this date has passed.<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
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-->
Unprocessable Entity
<!--/source-->

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

##### Other responses

`400`

`POST` `/transactions`

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

#### Create Transaction
<!--/source-->

`createTransaction`

<!--source:api-specifications-->
Create Transaction creates a transaction in Staircase.

Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business.

Transactions are identified by a unique key called transaction_id. As you use different Staircase products to gather the data needed for a specific instance of your transaction type, and receive different sets of output from each product, use the same transaction_id to correlate all the outputs to the same transaction.

A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you've assembled. To access all collections associated with a given transaction_id, try out /transactions/{transaction_id}/collections

<!--/source-->

##### Response

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

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

```
{
 "transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
 "created_at": "2021-05-11T03:39:27.129434-04:00"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Transaction created successfully
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string (ulid)` | <!--source:api-specifications-->Staircase Transaction Identifier<!--/source-->Example `01F0KHK7DN3H5JZ4QJKMYAM6GB` |
| `created_at` | `string` | <!--source:api-specifications-->ISO 8601 format with EST timezone<!--/source-->Example `2021-05-11T03:39:27.129434-04:00` |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

`POST` `/approval`

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

#### Upload Approval Document
<!--/source-->

`uploadApproval`

<!--source:api-specifications-->
Upload Approval
<!--/source-->

<!--source:api-specifications-->
Upload Approval Document allows a Lender to upload a Borrower-signed approval document in .pdf form, to increase the income verification success rate.

Upload Approval Document uploads a .pdf document (blob) to Persistence.

You can upload PDF using HTML Request Maker Try It Out. Place your api_key in the request header, set the request body to binary and browse to your signed approval document. Click Send to upload your document.

Show the rest To upload a document programmatically, use the programmatic upload example below. After the approval document is successfully uploaded, a blob_id value is provided. Example: 'blob_id': '01EZYHKY4EXFW4Z8RKWHDP1KHB'

After you got successful response, you need to use the blob_id in collection with the following path.

```
$.document_sets.document_set[0].documents.document[0].foreign_objects.foreign_object[0].staircase_blob_id
```

To upload a document within code, you can to use a below example.

```
import requests
url = ""
payload = open("borrower_approval_document.pdf", "rb")
headers = {
 'x-api-key': 'API_KEY',
 'Content-Type': 'application/pdf'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
Select option 'binary' in order to upload file
```

<!--/source-->

##### Response

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

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

```
{
 "blob_id": "01EZYNPEJMP5J3G8DVF8S4QXH2"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Unable to get collection. Please check input collection id"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Approval uploaded
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `blob_id` | `string` | <!--source:api-specifications-->ID of blob on AWS, put this later than as part of income verification collection body to be used by verification process<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

##### Other responses

`400`

`POST` `/transactions/{transaction_id}/collections`

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

#### Create Collection
<!--/source-->

`createCollection`

<!--source:api-specifications-->
Create Collection creates a collection of data attached to a transaction_id. Then, you can use this collection to invoke Verify Income endpoint to retrieve Income verification response. Once you have created a collection, you can send it, along with your api_key and transaction_id, to more than one Income partner.

We assembled an example that you can access by invoking Retrieve Example Schema endpoint. Simply select an entry in the array and pass it directly into the request body for Create Collection endpoint.

Show the rest

#### Mock Responses

You can mock data to get mock responses without setting any partner credentials. Staircase Income API uses a mock request response strategy that allows you to test your pipeline before setting your partner credentials. Currently, Income looks at the taxpayer identifier (SSN) and the employer name fields to detect whether the request is a mock request or not. You can set these fields by setting:

For staircase-graph collections:

```
$.organizations[*].has_organization_name.has_value
```

```
$.people[*].has_taxpayer_identifier_value.has_value
```

For staircase-limited collections:

```
$.deal_sets.deal_set[0].deals.deal[0].parties.party[0].roles.role[0].borrower.employers.employer[0].legal_entity.full_name
```

```
$.deal_sets.deal_set[0].deals.deal[0].parties.party[0].taxpayer_identifiers.taxpayer_identifier[0].value
```

Mock SSN and Company names and their relative partner responses are available in the table below:

| SSN | Company Name | Partner Data |
| --- | --- | --- |
| 000000001 | Fox Subacute | Argyle |
| 000000001 | Uber | Atomic |
| 000000001 | Amazon | Equifax |
| 000000001 | Finbank | Finicity |
| 000000001 | Apple | Meridian |
| 000000001 | Fairport Little League Inc. | Pinwheel |
| 000000001 | Truework DEMO | Truework |
| 000000001 | Truework DEMO | Truework-Instant |
| 000000001 | Lexipol | Plaid |

If you want to retrieve low income response please use the following invoke details below:

| SSN | Company Name | Partner Data |
| --- | --- | --- |
| 000000002 | N/A | default |

You can call Retrieve Example Schema with the query parameter `return_example=true` to retrieve examples for the data body of a request.

#### Day-1 Certainty

For Day-1 certainty, partners that require indicators to be sent in the request, you can use the following field:

```
$.loans[*].has_day_1_certainty_indicator.has_value
```

<!--/source-->

##### Request

<!--source:api-specifications-->
Input Example staircase-graphInput Example staircase-limited
<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "data": {
 "people": [
 {
 "@type": "borrower",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8ABC",
 "has_first_name": {
 "has_value": "FirstName"
 },
 "has_last_name": {
 "has_value": "LastName"
 },
 "has_birth_date": {
 "has_value": "1993-01-11"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "111223333"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ],
 "works_for": [
 "01FD6ZNGNFKY3B7CX0YN6NH56E"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "33 IRVING PLACE"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "NEW YORK"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "test@test.com"
 },
 "has_phone_number": {
 "has_value": "+123456789"
 }
 }
 ],
 "organizations": [
 {
 "@id": "01FD6ZNGNFKY3B7CX0YN6NH56E",
 "has_organization_name": {
 "has_value": "Company Name"
 }
 }
 ],
 "loans": [
 {
 "@id": "01G3B5DKRT27W61Y3ZK57JSGBE",
 "has_day_1_certainty_indicator": {
 "has_value": "123456789"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "data": {
 "deal_sets": {
 "deal_set": [
 {
 "deals": {
 "deal": [
 {
 "parties": {
 "party": [
 {
 "customer_transaction_id": "6f039329-3fd6-44c1-a460-9af546e798de",
 "individual": {
 "contact_points": {
 "contact_point": [
 {
 "contact_point_telephone": {
 "value": "+1234567890"
 },
 "contact_point_email": {
 "value": "test@test.com"
 }
 }
 ]
 },
 "name": {
 "first": "John",
 "last": "Jackson"
 }
 },
 "roles": {
 "role": [
 {
 "borrower": {
 "birth_date": "1993-01-11",
 "employers": {
 "employer": [
 {
 "legal_entity": {
 "full_name": "Amazon"
 }
 }
 ]
 },
 "residences": {
 "residence": [
 {
 "address": {
 "additional_line_text": "None",
 "city": "NEW YORK",
 "country": "US",
 "line_text": "33 IRVING PLACE",
 "postal_code": "10003",
 "state_code": "NY"
 }
 }
 ]
 }
 }
 }
 ]
 },
 "taxpayer_identifiers": {
 "taxpayer_identifier": [
 {
 "value": "111111111"
 }
 ]
 }
 }
 ]
 }
 }
 ]
 }
 }
 ]
 },
 "document_sets": {
 "document_set": [
 {
 "documents": {
 "document": [
 {
 "document_classification": {
 "document_classes": {
 "document_class": [
 {
 "staircase_type": "Staircase",
 "type": "BorrowerApproval"
 }
 ]
 }
 },
 "foreign_objects": {
 "foreign_object": [
 {
 "description": "BorrowerApproval",
 "mime_type_identifier": "application/pdf",
 "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
 "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
 }
 ]
 }
 }
 ]
 }
 }
 ]
 }
 }
}
```

<!--/source-->

##### Response

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

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

```
{
 "data": {
 "deal_sets": {
 "deal_set": [
 {
 "deals": {
 "deal": [
 {
 "parties": {
 "party": [
 {
 "customer_transaction_id": "111222333444",
 "individual": {
 "contact_points": {
 "contact_point": [
 {
 "contact_point_telephone": {
 "value": "+1234567890"
 },
 "contact_point_email": {
 "value": "test@test.com"
 }
 }
 ]
 }
 }
 }
 ]
 }
 },
 {
 "loans": {
 "loan": [
 {
 "loan_identifiers": {
 "loan_identifier": [
 {
 "identifier": "6f039329-3fd6-44c1-a460-9af546e798de",
 "name": {
 "first": "John",
 "last": "Jackson"
 }
 }
 ],
 "roles": {
 "role": [
 {
 "borrower": {
 "birth_date": "1984-01-01",
 "employers": {
 "employer": [
 {
 "legal_entity": {
 "full_name": "Amazing Community Pharmacy LLC"
 }
 }
 ]
 },
 "residences": {
 "residence": [
 {
 "address": {
 "additional_line_text": "None",
 "city": "NEW YORK",
 "country": "US",
 "line_text": "33 IRVING PLACE",
 "postal_code": "10003",
 "state_code": "NY"
 }
 }
 ]
 }
 },
 "party_type": "Borrower"
 }
 ]
 },
 "taxpayer_identifiers": {
 "taxpayer_identifier": [
 {
 "value": "317210001"
 }
 ]
 }
 }
 }
 ]
 },
 "services": {
 "service": [
 {
 "verification_of_income": {
 "verification_of_income_response": {
 "partner": "Wage",
 "partner_data_source_date": "2021-02-08"
 }
 }
 }
 ]
 }
 }
 ]
 }
 }
 ]
 },
 "document_sets": {
 "document_set": [
 {
 "documents": {
 "document": [
 {
 "document_classification": {
 "document_classes": {
 "document_class": [
 {
 "staircase_type": "Staircase",
 "type": "BorrowerApproval"
 }
 ]
 }
 },
 "foreign_objects": {
 "foreign_object": [
 {
 "description": "BorrowerApproval",
 "mime_type_identifier": "application/pdf",
 "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
 "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
 }
 ]
 }
 }
 ]
 }
 }
 ]
 }
 },
 "metadata": {
 "validation": false,
 "created_at": "03/04/2021, 1:18:35 PM EST"
 },
 "collection_id": "01F0KHKADN0HRFXMCQQXPA6AFZ",
 "transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB"
}
```

<!--/source-->

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

```
{
 "message": "Unable to create collection. Please check the collection data"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Unable to get collections of given transaction. Please check the transaction id"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | <!--source:api-specifications-->Staircase Transaction Identifier<!--/source--> |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Collection created successfully
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `data` | `object` | — |
| `deal_sets`required | `object` | — |
| `deal_set`required | `object[]` | — |
| `deals`required | `object` | — |
| `document_sets` | `object` | — |
| `document_set` | `object[]` | — |
| `documents` | `object` | — |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | — |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

`POST` `/`

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

#### Verify Income
<!--/source-->

`verifyIncome`

<!--source:api-specifications-->
Verify Income creates a verification request for provided transaction, collection and selected partner.

To better understand how to use this endpoint and how the entire income flow works check out the Overview Page and the detailed tutorial.

To invoke Income, you will need:

- a transaction_id, and
- a collection_id with valid data.

To get correct information from the income product, creating the request collection is extremely important. Hence, we heavily recommend looking at Create Collection documentation before this one.

Show the rest

#### Verification options

Manual Verification parameter

The manual_verification option enables you to add or remove partners that perform manual income verifications. When manual_verification=false, Income will exclude all partners performing manual VOI. This limits the search for partners performing VOI, and also reduces the time it takes to complete a VOI.

Exclude Borrower parameter

The exclude_borrower option enables you to remove the borrower from the VOI loop. When exclude_borrower=false, the borrower must provide credentials for Income verification prior to the partner performing the VOI. This increases borrower interaction, and also increases the chance that the VOI will be successfully completed.

The borrower needs to authorize the verification by entering payroll provider or bank credentials to the URL (widget_url) provided in the verification response. Call Retrieve Partners to retrieve test credentials for partners that have the borrower in the loop.

Instant Verification parameter

The instant_verification option enables you to add or remove partners that perform instant verifications. When instant_verification=true, Income will use all partners performing instant verification. This can limit the search for partners performing VOI, and also reduces the time it takes to complete a VOI.

Partner name parameter

The partner_name option enables you to select a preferred partner, or use "default" as the value. If you use "default" as the partner_name, Income will find the best match and use that partner for verification process. If you want to use a specific partner, call Retrieve Partners to see all income verification partners.

Callback URL parameter

The callback_url option enables you to send a URL with the request. This URL will be used to send a callback when the verification process status changes, including changes in status of underlying service invocations.

Send SMS parameter

The send_sms option enables you to send an SMS to the borrower when an authorization for the verification is needed. The default SMS text is "Lender has provided verification link to your E-mail address, please open link in browser, and finish verification process", if you wish to change the default SMS text you can send an optional sms_text parameter with your custom text message.

Send Email parameter

The send_email option enables you to email the borrower when an authorization for the verification is needed. The Email will be sent to the email address specified in the input collection. The Email uses the standard email template voi_email_template, if you wish to update the template please refer to the Update Email Template documentation. Please note that the template takes in two passed variables, which are the applet URL and employer_name, and those are required variables and should not be altered, for more info check the Email Product section.

Redirect URL parameter

Providing the redirect_url is optional and allows you to redirect the borrower to a URL of your choosing after linking the borrower's income verification. If left empty or no options parameter is passed, this URL defaults to the Staircase homepage.

If the waterfall feature is enabled, partner is selected based on the partner ordering.

To use the waterfall feature set the partner name to default. This way verification will be executed following the ordering for all available data partners. Use Update Partners Ordering and Retrieve Partners Ordering to set and get the orderings. If two data partners share the same legal entity full name the verification will be done based on the ordering of data partners.

Verify Income returns, as a synchronous acknowledgement, a new collection_id. The new collection_id represents an empty container which will hold the partner's response once processing has completed.

Some Partners require the borrower to authenticate, if the response contains the `url` property then the URL should be forwarded to the borrower and authenticated. The url is valid until the `expiration_time` which is denoted in EST.

Use the newly returned collection_id together with transaction_id in Retrieve Collection to get verification result.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
 "collection_id": "01F0KHKADN0HRFXMCQQXPA6AFZ",
 "partner_name": "Partner",
 "callback_url": "https://webhook.site/1234",
 "options": {
 "manual_verification": true,
 "exclude_borrower": false,
 "instant_verification": true,
 "send_sms": false
 }
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
200400 MissingTransactionID400 MissingCollectionID400 MissingPartnerName400 InvalidPartnerName400 InvalidJSONBody403404422 InvalidTransactionIDFormat422 InvalidCollectionIDFormat
<!--/source-->

<!--source:api-specifications-->
application/json Copy Request for Verification of Income created successfully. Please take the contained widget_url and forward it to the borrower. The url is valid until the `expiration_time`. The `expiration_time` is denoted in EST.

```
{
 "collection_id": "01F0KHKADN0HRFXMCQQXPA6AFZ",
 "url": "www.staircase.co",
 "expiration_time": "2021-04-22T12:51:25-04:00"
}
```

<!--/source-->

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

```
{
 "message": "Please make sure your body contains transaction_id."
}
```

<!--/source-->

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

```
{
 "message": "Please make sure your body contains collection_id"
}
```

<!--/source-->

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

```
{
 "message": "Please make sure your body contains partner_name"
}
```

<!--/source-->

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

```
{
 "message": "Please provide a valid partner name. To get available partners, you can use /partners endpoint."
}
```

<!--/source-->

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

```
{
 "message": "Request body had invalid format. Please provide a valid JSON"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Unable to get collection. Please check input collection id"
}
```

<!--/source-->

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

```
{
 "message": "transaction_id value had non-alphanumeric characters. Please check transaction id"
}
```

<!--/source-->

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

```
{
 "message": "collection_id value had non-alphanumeric characters. Please check collection id"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string (ulid)` | <!--source:api-specifications-->Staircase Transaction Identifier<!--/source-->Example `01F0KHK7DN3H5JZ4QJKMYAM6GB` |
| `collection_id`required | `string (ulid)` | <!--source:api-specifications-->Staircase Collection Identifier<!--/source-->Example `01F0KHKADN0HRFXMCQQXPA6AFZ` |
| `partner_name` | `string` | <!--source:api-specifications-->To get available partners, you can use /partners endpoint<!--/source--> |
| `callback_url` | `string` | <!--source:api-specifications-->Callback URL - will be used by product to send a callback when the invocation status changes.<!--/source--> |
| `options` | `object` | <!--source:api-specifications-->You can use options to customize the verification<!--/source--> |
| `manual_verification` | `boolean` | <!--source:api-specifications-->This option allows us to add partners that perform manual verification to your search list while finding the most suitable partner for you. This option takes a longer time and gives you a broader search.<!--/source--> |
| `exclude_borrower` | `boolean` | <!--source:api-specifications-->Some of our partners include borrowers in the loop while executing the verification. Income is verified by requesting information from borrower. If you want to exclude the borrower from the process, you must select *exclude_borrower* = *true* in options.<!--/source--> |
| `instant_verification` | `boolean` | <!--source:api-specifications-->This option allows us to add partners that perform instant verification to the search list while finding the most suitable partner for VOI.<!--/source--> |
| `send_sms` | `boolean` | <!--source:api-specifications-->This option allows us to send SMS to the borrower when an authorization for the verification is needed. The SMS text is "Lender has provided verification link to your E-mail address, please open link in browser, and finish verify process"<!--/source--> |
| `send_email` | `boolean` | <!--source:api-specifications-->If set to True, product will email the borrower when an authorization for the verification is needed. The Email will contain the URL to the authorization and the Company name.<!--/source--> |

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

<!--source:api-specifications-->
3 fields
<!--/source-->
<!--source:api-specifications-->
Request for Verification of Income created successfully. Please take the contained widget_url and forward it to the borrower. The url is valid until the `expiration_time`. The `expiration_time` is denoted in EST.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `collection_id` | `string (ulid)` | <!--source:api-specifications-->Staircase Collection Identifier<!--/source-->Example `01F0KHKADN0HRFXMCQQXPA6AFZ` |
| `url` | `string` | <!--source:api-specifications-->URL that needs to be sent to the borrower<!--/source--> |
| `expiration_time` | `string (date-time)` | <!--source:api-specifications-->Expiration time in EST. The operation will result in failure after this date has passed.<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
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-->
Unprocessable Entity
<!--/source-->

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

##### Other responses

`400`

`POST` `/cancel-verification`

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

#### Cancel Income Verification
<!--/source-->

`cancel-income-verification`

<!--source:api-specifications-->
Cancel Income Verification invokes a partner to cancel an income verification request that is already started. This feature is currently only available from Truework.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "transaction_id": "42u3784-324123-41234-21234",
 "collection_id": "42u3784-324123-41234-21234"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Bad gateway.

```
{
 "message": "Internal server error."
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string (ulid)` | <!--source:api-specifications-->Staircase Transaction Identifier<!--/source-->Example `01F0KHK7DN3H5JZ4QJKMYAM6GB` |
| `collection_id`required | `string (ulid)` | <!--source:api-specifications-->Staircase Collection Identifier<!--/source-->Example `01F0KHKADN0HRFXMCQQXPA6AFZ` |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Cancel income verification triggered
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Example `Cancel income verification request is successfully taken` |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

##### Response `502``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Bad gateway.
<!--/source-->

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

##### Other responses

`400`

`GET` `/products/income/invocations/{invocation_id}`

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

#### Retrieve Income Verification Status
<!--/source-->

`RetrieveProductFlowInvocationStatus`

<!--source:api-specifications-->
Retrieves the status of running Product flow invocation.

A more detailed explanation as to why something failed or timed out can be found by retrieving the collection and checking the `data` object.

<!--/source-->

##### Response

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

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

```
{
 "status": "COMPLETED",
 "message": "Verification is completed, please check response collection to see verification data",
 "updated_at": "2021-06-25T09:32:13.272871-04:00"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Unable to get status. Please check the given ids"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `invocation_id` required | `string (ulid)` path | `01FFMHWSGMBJDSXTEX09M3EYJ9` | <!--source:api-specifications-->Product flow invocation identifier<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | <!--source:api-specifications-->'Potential status responses: ''WAITING_FOR_RESPONSE'', ''COMPLETED'', ''FAILED'', ''TIME_OUT'', ''CANCELLED'''<!--/source-->`CANCELLED``COMPLETED``FAILED``TIME_OUT``WAITING_FOR_RESPONSE` |
| `message` | `string` | <!--source:api-specifications-->Additional information for status<!--/source--> |
| `updated_at` | `string` | <!--source:api-specifications-->Last updated time<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

##### Other responses

`400`

`GET` `/status/{transaction_id}/{collection_id}`

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

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

`retrieveStatus`

<!--source:api-specifications-->
'Retrieve Status determines if a partner has completed income verification.'

Status Descriptions:

- REQUEST_MADE: Indicates that execution has started
- WAITING_FOR_RESPONSE: Indicates that execution is being processed
- COMPLETED: Indicates execution has been successfully finished. Response collection can be retrieved.
- TIME_OUT: Indicates execution has timed out.
- CANCELLED: Indicates execution has cancelled
- FAILED: Indicates execution has failed

A more detailed explanation as to why something failed or timed out can be found by retrieving the collection and checking the `data` object.

<!--/source-->

##### Response

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

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

```
{
 "status": "COMPLETED",
 "message": "Verification is completed, please check response collection to see verification data",
 "updated_at": "2021-06-25T09:32:13.272871-04:00"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Unable to get status. Please check the given ids"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | <!--source:api-specifications-->Staircase Transaction Identifier<!--/source--> |
| `collection_id` required | `string (ulid)` path | `01F0KHKADN0HRFXMCQQXPA6AFZ` | <!--source:api-specifications-->Staircase collection_id<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `status` | `string` | <!--source:api-specifications-->'Potential status responses: ''WAITING_FOR_RESPONSE'', ''COMPLETED'', ''FAILED'', ''TIME_OUT'', ''CANCELLED'''<!--/source-->`CANCELLED``COMPLETED``FAILED``TIME_OUT``WAITING_FOR_RESPONSE` |
| `message` | `string` | <!--source:api-specifications-->Additional information for status<!--/source--> |
| `updated_at` | `string` | <!--source:api-specifications-->Last updated time<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

##### Other responses

`400`

`GET` `/transactions/{transaction_id}/collections/{collection_id}`

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

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

`retrieveCollection`

<!--source:api-specifications-->
Retrieve Collection returns an Income collection. If income process still continues (i.e. partner hasn't returned any data yet) this endpoint returns `IN_PROGRESS` in `metadata.status` field.

For example:

```
{
 "metadata": {
 "created_at": "2021-08-05T03:53:06.180163-04:00",
 "results": {
 "product": "Income",
 "status": "IN_PROGRESS"
 },
 "validation": false
 }
}
```

Continue to ping this endpoint until `metadata.status` field returns `COMPLETED`.

```
{
 "metadata": {
 "created_at": "2021-08-05T03:53:06.180163-04:00",
 "results": {
 "product": "Income",
 "status": "COMPLETED"
 },
 "validation": false
 }
}
```

Once the status is `COMPLETED` you will be able to access the full partner response in the `{"data"}` property of the response collection

<!--/source-->

##### Response

<!--source:api-specifications-->
200 Example staircase-graph (v2)200 Example staircase-graph (v2) Failed200 Example staircase-limited (v0)403404 GetCollectionError404 GetCollectionsError500
<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully Retrieved Collection

```
{
 "collection_id": "01G4CSWKK6HRABWRZNM0J6BEXK",
 "data": {
 "addresses": [
 {
 "@id": "01G0F11KE743JYDTZK6JSJSZUY",
 "@type": "residential_address",
 "has_address_line_1_text": {
 "has_value": "33 IRVING PLACE"
 },
 "has_city_name": {
 "has_value": "NEW YORK"
 },
 "has_country_name": {
 "has_value": "US"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_state_code": {
 "has_value": "NY"
 }
 },
 {
 "@id": "01G4CSY8CJ30N1ZWNH3W4TEF9H",
 "@type": "business_address",
 "has_address_line_1_text": {
 "has_value": "1313 Mockingbird Lane"
 },
 "has_city_name": {
 "has_value": "Olympia"
 },
 "has_country_name": {
 "has_value": "US"
 },
 "has_postal_code": {
 "has_value": "82943-9302"
 },
 "has_state_code": {
 "has_value": "NY"
 }
 }
 ],
 "contact_information": [
 {
 "@id": "01G0F11KE743JYDTZK6JSJSYCR",
 "@type": "contact_information",
 "has_email_address": {
 "has_value": "test@test.com"
 },
 "has_phone_number": {
 "has_value": "+123456789"
 }
 }
 ],
 "documents": [
 {
 "@id": "01G4CSYSAREBF6Y4GY2MNPJBEG",
 "@type": "verification_of_income",
 "has_document_description": {
 "has_value": "Income Verification Report prepared by Staircase"
 },
 "has_document_mime_type": {
 "has_value": "application/pdf"
 },
 "has_document_name": {
 "has_value": "01G4CSYKZQKZN4PCRZHQD0XNJB.pdf"
 },
 "has_staircase_blob_identifier": {
 "has_value": "01G4CSYKZQKZN4PCRZHQD0XNJB"
 },
 "has_staircase_document_category_type": {
 "has_value": "staircase"
 }
 },
 {
 "@id": "01G0EX4VT41ZF22QWXH1QBTZPF",
 "@type": "verification_of_income",
 "has_document_description": {
 "has_value": "Income Verification Report prepared by Partner"
 },
 "has_document_mime_type": {
 "has_value": "application/pdf"
 },
 "has_document_name": {
 "has_value": "01G0EX4VT41ZF22QWXH1QBTZPF.pdf"
 },
 "has_staircase_blob_identifier": {
 "has_value": "01G0EX4VT41ZF22QWXH1QBTZPF"
 },
 "has_staircase_document_category_type": {
 "has_value": "partner"
 }
 }
 ],
 "employment": [
 {
 "@id": "01G0F11KE743JYDTZK6JSJSPOQ",
 "@type": "employment",
 "has_current_employment_indicator": {
 "has_value": true
 },
 "has_employment_monthly_income_amount": {
 "has_value": 7000
 },
 "has_employment_position_description": {
 "has_value": "HR ADMININSTRATOR"
 },
 "has_employment_start_date": {
 "has_value": "2014-01-01"
 },
 "provided_by": [
 "01G0F11KE743JYDTZK6JSJSTIY"
 ]
 }
 ],
 "income": [
 {
 "@id": "01G4CSY8CK4K120TWKECZXHGGA",
 "@type": "employment_income",
 "earned_from": [
 "01G4CSY8CJXPA8R5SFVSTEQ188"
 ],
 "has_bonus_income_amount": {
 "has_value": 0
 },
 "has_income_amount": {
 "has_value": 22615.38
 },
 "has_income_pay_frequency_type": {
 "has_value": "monthly"
 },
 "has_income_year": {
 "has_value": "2022"
 },
 "has_other_income_amount": {
 "has_value": 0
 },
 "has_overtime_income_amount": {
 "has_value": 0
 }
 },
 {
 "@id": "01G4CSY8CKKBSYGQXA5D5KY8A9",
 "@type": "employment_income",
 "earned_from": [
 "01G4CSY8CJXPA8R5SFVSTEQ188"
 ],
 "has_bonus_income_amount": {
 "has_value": 0
 },
 "has_income_amount": {
 "has_value": 84000
 },
 "has_income_pay_frequency_type": {
 "has_value": "monthly"
 },
 "has_income_year": {
 "has_value": "2021"
 },
 "has_other_income_amount": {
 "has_value": 0
 },
 "has_overtime_income_amount": {
 "has_value": 0
 }
 },
 {
 "@id": "01G4CSY8CK3RJAF6WP0XQN2JQW",
 "@type": "employment_income",
 "earned_from": [
 "01G4CSY8CJXPA8R5SFVSTEQ188"
 ],
 "has_bonus_income_amount": {
 "has_value": 0
 },
 "has_income_amount": {
 "has_value": 80000
 },
 "has_income_pay_frequency_type": {
 "has_value": "monthly"
 },
 "has_income_year": {
 "has_value": "2020"
 },
 "has_other_income_amount": {
 "has_value": 0
 },
 "has_overtime_income_amount": {
 "has_value": 0
 }
 }
 ],
 "mortgage_products": [
 {
 "@id": "01G4CSYB2B2JZW01E660FHJED5",
 "@type": "income",
 "has_partner_name": {
 "has_value": "Partner"
 },
 "has_service_response_date": {
 "has_value": "2022-05-31"
 }
 }
 ],
 "loans": [
 {
 "@id": "01G3B5DKRT27W61Y3ZK57JSGBE",
 "@type": "loan",
 "has_day_1_certainty_indicator": {
 "has_value": "123456789"
 }
 }
 ],
 "organizations": [
 {
 "@id": "01G0F11KE743JYDTZK6JSJSTIY",
 "@type": "organization",
 "has_organization_name": {
 "has_value": "Amazon"
 },
 "with_address": [
 "01G4CSY8CJ30N1ZWNH3W4TEF9H"
 ]
 }
 ],
 "people": [
 {
 "@id": "01G4CSY8CJ5X9MPA2VR5AH97YB",
 "@type": "borrower",
 "contact_at": [
 "01G0F11KE743JYDTZK6JSJSYCR"
 ],
 "earns": [
 "01G4CSY8CKKBSYGQXA5D5KY8A9",
 "01G4CSY8CK3RJAF6WP0XQN2JQW",
 "01G4CSY8CK4K120TWKECZXHGGA"
 ],
 "employed_as": [
 "01G0F11KE743JYDTZK6JSJSPOQ"
 ],
 "has_birth_date": {
 "has_value": "1973-01-01"
 },
 "has_first_name": {
 "has_value": "Happy"
 },
 "has_last_name": {
 "has_value": "Traveler"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "666991238"
 },
 "with_address": [
 "01G4CSY8CJ30N1ZWNH3W4TEF9H",
 "01G0F11KE743JYDTZK6JSJSZUY"
 ],
 "works_for": [
 "01G0F11KE743JYDTZK6JSJSTIY"
 ]
 }
 ]
 },
 "metadata": {
 "created_at": "2022-05-31T06:16:54.118103-04:00",
 "invocation_status": "COMPLETED",
 "last_updated_at": "2022-05-31T06:18:22.606643-04:00",
 "partner_language": "income-equifax-output",
 "product_name": "income",
 "report_download_urls": {
 "income_report": {
 "blob_id": "01G4CSYKZQKZN4PCRZHQD0XNJB",
 "download_url": "https://dev-data-manager-blobs-bucket-us-east-1-026452950730.s3.amazonaws.com/01G4CSYKZQKZN4PCRZHQD0XNJB.pdf?response-content-type=application%2Fpdf&AWSAccessKeyId=<redacted>&Signature=<redacted>&x-amz-security-token=<redacted>&Expires=1653995880",
 "status": "Succeeded"
 }
 },
 "service_invocation": {
 "Connector": {
 "connector_flow_name": "income",
 "debug_config": {
 "dry_run": true
 },
 "invocation_id": "1f15fe83-7b8a-4123-b645-c62e0d922612",
 "status": "COMPLETED"
 },
 "Language": {
 "input": {
 "from_language": "staircase-graph",
 "invocation_id": "01G4CSX1GYCSCHYYEZCXT1DPYQ",
 "status": "COMPLETED",
 "to_language": "income-input"
 },
 "output": {
 "from_language": "income-equifax-output",
 "invocation_id": "01G4CSY55AZ4TH9X29ZE4YQAB0",
 "status": "COMPLETED",
 "to_language": "staircase-graph"
 }
 },
 "report_mapping": {
 "invocation_id": "01G4CSYMQ5QXV05P70CB6ZH92E",
 "language_name": "income-report-mapping",
 "status": "COMPLETED"
 }
 },
 "staircase_language_version": 2,
 "validation": false,
 "version": 2
 },
 "transaction_id": "01G4CSWCBM2QE3QXTDEM4AEPBK"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully Retrieved Collection

```
{
 "collection_id": "01G4YST3F7CJ550QHX6MKKBK27",
 "data": {
 "Cause": {
 "errorMessage": "Wrong SSN or Company used for mock invocation. Please check the documentation for more details on mock responses.",
 "errorType": "FailStateError",
 "requestId": "0878acbe-bac6-411d-b49e-e1b1ec44e4c0"
 },
 "Error": "FailStateError"
 },
 "metadata": {
 "created_at": "2022-06-07T06:01:51.847596-04:00",
 "invocation_status": "FAILED",
 "last_updated_at": "2022-06-07T06:02:07.557950-04:00",
 "partner_language": "income-atomic-output",
 "product_name": "income",
 "results": {
 "product_name": "income",
 "status": "FAILED"
 },
 "service_invocation": {
 "Connector": {
 "connector_flow_name": "income",
 "invocation_id": "616a8b01-a0f2-4168-b2b3-0b6167561624",
 "status": "FAILED"
 },
 "Language": {
 "input": {
 "from_language": "staircase-graph",
 "invocation_id": "01G4YST5NJ3NQ7KP5N8KPY5M9P",
 "status": "COMPLETED",
 "to_language": "income-input"
 }
 }
 },
 "staircase_language_version": 2,
 "validation": false,
 "version": 2
 },
 "transaction_id": "01G4YSSWYFXCHXNKHWXDC5TGCV"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully Retrieved Collection

```
{
 "collection_id": "01F5BEJKKQ8NNXM54YTK8NKY23",
 "data": {
 "deal_sets": {
 "deal_set": [
 {
 "deals": {
 "deal": [
 {
 "parties": {
 "party": [
 {
 "customer_transaction_id": "6f039329-3fd6-44c1-a460-9af546e798de",
 "individual": {
 "contact_points": {
 "contact_point": [
 {
 "contact_point_telephone": {
 "value": "+1234567890"
 },
 "contact_point_email": {
 "value": "test@test.com"
 }
 }
 ]
 },
 "name": {
 "first": "John",
 "last": "Jackson"
 }
 },
 "roles": {
 "role": [
 {
 "borrower": {
 "birth_date": "1984-01-01",
 "current_income": {
 "current_income_items": {
 "current_income_item": [
 {
 "income_documentations": {
 "income_documentation": [
 {
 "type": "VerificationOfIncome"
 }
 ]
 },
 "other_period_description": 2021,
 "other_period_total": 12692.31,
 "type": "Gross"
 },
 {
 "income_documentations": {
 "income_documentation": [
 {
 "type": "VerificationOfIncome"
 }
 ]
 },
 "other_period_description": 2021,
 "other_period_total": 7825.98,
 "type": "Net"
 },
 {
 "income_documentations": {
 "income_documentation": [
 {
 "type": "VerificationOfIncome"
 }
 ]
 },
 "other_period_description": 2020,
 "other_period_total": 38169.53,
 "type": "Gross"
 },
 {
 "income_documentations": {
 "income_documentation": [
 {
 "type": "VerificationOfIncome"
 }
 ]
 },
 "other_period_description": 2020,
 "other_period_total": 23586.51,
 "type": "Net"
 },
 {
 "income_documentations": {
 "income_documentation": [
 {
 "type": "VerificationOfIncome"
 }
 ]
 },
 "other_period_description": 2020,
 "other_period_total": 16727.54,
 "type": "Bonus"
 },
 {
 "income_documentations": {
 "income_documentation": [
 {
 "type": "VerificationOfIncome"
 }
 ]
 },
 "other_period_description": 2020,
 "other_period_total": 288.16,
 "type": "Other"
 },
 {
 "income_documentations": {
 "income_documentation": [
 {
 "type": "Paystubs"
 }
 ]
 },
 "other_period_description": "2021-02-08",
 "other_period_total": 4230.77,
 "type": "Gross"
 },
 {
 "income_documentations": {
 "income_documentation": [
 {
 "type": "Paystubs"
 }
 ]
 },
 "other_period_description": "2021-02-08",
 "other_period_total": 2608.65,
 "type": "Net"
 },
 {
 "income_documentations": {
 "income_documentation": [
 {
 "type": "Paystubs"
 }
 ]
 },
 "other_period_description": "2021-01-25",
 "other_period_total": 4230.77,
 "type": "Gross"
 },
 {
 "income_documentations": {
 "income_documentation": [
 {
 "type": "Paystubs"
 }
 ]
 },
 "other_period_description": "2021-01-25",
 "other_period_total": 2608.66,
 "type": "Net"
 }
 ]
 }
 },
 "employers": {
 "employer": [
 {
 "legal_entity": {
 "full_name": "Amazing Community Pharmacy LLC"
 },
 "payment_frequency": "biweekly"
 }
 ]
 },
 "residences": {
 "residence": [
 {
 "address": {
 "additional_line_text": "None",
 "city": "NEW YORK",
 "country": "US",
 "line_text": "33 IRVING PLACE",
 "postal_code": "10003",
 "state_code": "NY"
 }
 }
 ]
 }
 },
 "party_type": "Borrower"
 }
 ]
 },
 "taxpayer_identifiers": {
 "taxpayer_identifier": [
 {
 "value": "317210001"
 }
 ]
 }
 }
 ]
 },
 "services": {
 "service": [
 {
 "verification_of_income": {
 "verification_of_income_response": {
 "partner": "Wage",
 "partner_data_source_date": "2021-02-08"
 }
 }
 }
 ]
 }
 }
 ]
 }
 }
 ]
 },
 "document_sets": {
 "document_set": [
 {
 "documents": {
 "document": [
 {
 "foreign_objects": {
 "foreign_object": [
 {
 "description": "Income Verification Report prepared by Staircase",
 "mime_type_identifier": "application/pdf",
 "name": "01F5BEK8YPGESS80J2TZSTXYAG.pdf",
 "staircase_blob_id": "01F5BEK8YPGESS80J2TZSTXYAG"
 }
 ]
 }
 }
 ]
 }
 }
 ]
 }
 },
 "metadata": {
 "created_at": "2021-05-10T11:33:21.143455-04:00",
 "partner_language": "partner_language_name",
 "product_name": "income",
 "report_download_urls": {
 "income_report": {
 "blob_id": "123142ASDLKNASLD123",
 "download_url": "https://link.to.report.com",
 "status": "Succeeded"
 }
 },
 "service_invocation": {
 "Connector": {
 "connector_flow_name": "income",
 "invocation_id": "3b12jk3b-0-897uioj-908uihj-sdadsad",
 "status": "COMPLETED"
 },
 "Language": {
 "input": {
 "from_language": "staircase-graph",
 "invocation_id": "01G2A292A9N9A87BWY98VX6TB6",
 "status": "COMPLETED",
 "to_language": "income-input"
 },
 "output": {
 "from_language": "income-partner-output",
 "invocation_id": "02G2A292A8N8A87BWY98VX6TB7",
 "status": "COMPLETED",
 "to_language": "staircase-graph"
 }
 }
 },
 "dry_run": false,
 "exclude_borrower": false,
 "last_updated_at": "2021-05-10T11:33:43.384435-04:00",
 "manual_verification": true,
 "send_sms": false,
 "partner_name": "Partner_X",
 "results": {
 "status": "COMPLETED"
 },
 "staircase_language_version": "staircase-language-v0",
 "validation": false,
 "verification_state": "COMPLETED"
 },
 "transaction_id": "01F5BEH37YSEBXB9MD8654A72K"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Unable to get collection. Please check the given ids"
}
```

<!--/source-->

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

```
{
 "message": "Unable to get collections of given transaction. Please check the transaction id"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | <!--source:api-specifications-->Staircase Transaction Identifier<!--/source--> |
| `collection_id` required | `string (ulid)` path | `01F0KHKADN0HRFXMCQQXPA6AFZ` | <!--source:api-specifications-->Staircase collection_id<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

##### Other responses

`200``400`

`GET` `/blobs/{blob_id}/presigned-urls/{action}`

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

#### Create Report Download URL
<!--/source-->

`createPresignedUrl`

<!--source:api-specifications-->
Create Report Download URL creates a presigned URL in Staircase. It expires one hour after creation.

If partner provides a report in the documents, you can generate a download url using staircase blob ID.

<!--/source-->

##### Response

<!--source:api-specifications-->
200 ExampleUpload200 ExampleDownload403
<!--/source-->

<!--source:api-specifications-->
application/json Copy Presigned URL created successfully.

```
{
 "upload": {
 "url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS"
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Presigned URL created successfully.

```
{
 "download": {
 "url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS"
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `blob_id` required | `string` path | `01EZY9J8SEFM2JKDJ1Q3YX65HS` | <!--source:api-specifications-->Blob identifier<!--/source--> |
| `action` required | `string` path | `upload` | <!--source:api-specifications-->Action, one of one of ['upload', 'download']<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Presigned URL created successfully.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `upload` | `object` | <!--source:api-specifications-->Action<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->Presigned_url<!--/source--> |
| `download` | `object` | <!--source:api-specifications-->Action<!--/source--> |
| `url` | `string` | <!--source:api-specifications-->Presigned_url<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Other responses

`400``404`

`GET` `/report/{blob_id}`

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

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

`retrieveReport`

<!--source:api-specifications-->
Retrieve Report retrieves a PDF report from a successful verification. This endpoint takes in one path parameter, the blob ID, which can be found in the response collection of a successful verification.

<!--/source-->

##### Response

<!--source:api-specifications-->
200400 BadRequestResp400 NoReportFound403500
<!--/source-->

<!--source:api-specifications-->
application/json Copy Report URL retrieved successfully

```
{
 "url": "www.domain.com/reportURL"
}
```

<!--/source-->

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

```
{
 "message": "Blod ID is not valid or not provided"
}
```

<!--/source-->

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

```
{
 "message": "No report found for this blob_id"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `blob_id` required | `string` path | `01FVFBXHVD5WT2MJAGG96CPBJD` | <!--source:api-specifications-->Blob ID for report that needs to retrieved.<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Report URL retrieved successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

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

### Verification
<!--/source-->

`POST` `/verification`

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

#### Verify Income
<!--/source-->

`InvokeIncomeVerificationFlow`

<!--source:api-specifications-->
The `Verify Income API` facilitates the retrieval of income and employment details for the income and employment product offered by partners based on provided borrower information.

#### API Input

In order to run `Verify Income` below data is required in the request payload:

- `partner_name`, supported partners:

- truework-instant

Show the rest
- `request_data`: You need to provide `people`, `addresses` and `contact_information` classes in your request collection. Below is detailed explaination for the `request_data` attributes.

People
- `@id` - (string) - Unique identifier for the person object.
- `@type` - (string) - Label that explains the type of person. Values: borrower
- `has_first_name/has_value` - (string) - The person's first name.
- `has_last_name/has_value` - (string) - The person's last name.
- `has_birth_date/has_value` - (string) - The person's birth date.
- `has_taxpayer_identifier_value/has_value` - (string) - The person's tax payer identifier (SSN).
- `with_address` - (array) - List of ID's that should connect the person object with the corresponding `address` object.
- `contact_at` - (array) - List of ID's that should connect the person object with the corresponding `contact_information` object.

Address
- `@id` - (string) - Unique identifier for the address object.
- `@type` - (string) - Label that explains the type of address. Values: address, business_address
- `has_address_line_1_text/has_value` - (string) - The address line text.
- `has_address_line_2_text/has_value` - (string) - The address line text, for additional information.
- `has_city_name/has_value` - (string) - The address city name.
- `has_state_code/has_value` - (string) - The address stat code.
- `has_postal_code/has_value` - (string) - The address postal code.
- `has_country_name/has_value` - (string) - The address country name.

Contact Information
- `@id` - (string) - Unique identifier for the contact information object.

- `@type` - (string) - Label that explains the type of contact information. Values: contact_information

- `has_email_address/has_value` - (string) - The email address.

- `has_phone_number/has_value` - (string) - The phone number.

- `callback_url`: If you don't want to continuously poll the result, you can provide a callback_url in request body. Once the invocation is completed, response content will be posted to this endpoint.

Note: All relationships between classes need to be defined and present. If this is not the case the API may encounter issues getting the correct income verification.

#### Running Verify Income API

API can be run in two modes:

- Real Call: In the case of a Real Partner Call, an actual call will be made to the partner. Prior to making this call, it is necessary to call Setup Partner Configurations API through this link. Please note that Staircase and Partners may apply charges for this service.

- Mock Call: The API will return a mock partner response without making a real call in the case of a mock scenario. To return the corresponding response for each scenario, the API will use the `people[*].has_taxpayer_identifier_value/has_value` field. However, if any other SSN values are used in the call, the API will switch to Real Partner Call Mode.

###### Mock Scenarios Examples

If you want to test the system and see possible income and employment results without invoking partners you can do mock request instead. Create payload as described in Request Payload section above but add `has_taxpayer_identifier_value/has_value` field to the person with following values:

| SSN | Partner Name | Mock Scenario |
| --- | --- | --- |
| 990000001 | truework-instant | Standard VOIE response |

#### API Response

- Once `Verify Income` results are available, the results will be returned on the webhook URL with the status and response_data, below are the details of the `response_data` from the `Verify Income` API.

People
- `@id` - (string) - Unique identifier for the person object.
- `@type` - (string) - Label that explains the type of person. Values: borrower
- `has_first_name/has_value` - (string) - The person's first name.
- `has_last_name/has_value` - (string) - The person's last name.
- `has_birth_date/has_value` - (string) - The person's birth date.
- `has_taxpayer_identifier_value/has_value` - (string) - The person's tax payer identifier (SSN).
- `with_address` - (array) - List of ID's that should connect the person object with the corresponding `address` object.
- `earns` - (array) - List of ID's that should connect the person object with the corresponding `income` object.
- `works_for` - (array) - List of ID's that should connect the person object with the corresponding `organization` object.
- `with_contact_point` - (array) - List of ID's that should connect the person object with the corresponding `contact_information` object.

Income
- `@id` - (string) - Unique identifier for the income object.
- `@type` - (string) - Label that explains the type of income. Values: employment_income
- `has_income_year/has_value` - (string) - The income year.
- `has_income_pay_frequency_type/has_value` - (string) - The income pay frequency type.
- `has_base_income_amount/has_value` - (string) - The income base amount.
- `has_income_amount/has_value` - (string) - The income amount.
- `has_overtime_income_amount/has_value` - (string) - The income overtime amount.
- `has_commission_income_amount/has_value` - (string) - The income commission amount.
- `has_bonus_income_amount` - (string) - The income bonus amount.
- `earned_from` - (array) - List of ID's that should connect the income object with the corresponding `employment` object.

Employment
- `@id` - (string) - Unique identifier for the employment object.
- `@type` - (string) - Label that explains the type of employment. Values: employment
- `has_current_employment_indicator/has_value` - (boolean) - Wheter the borrower is currently employed.
- `has_employment_start_date/has_value` - (string) - The employment start date.
- `has_employment_end_date/has_value` - (string) - The employment end date.
- `has_employment_type/has_value` - (string) - The employment type.
- `has_employment_position_description/has_value` - (string) - The employment position description.
- `provided_by` - (array) - List of ID's that should connect the employment object with the corresponding `organization` object.
- `earns` - (array) - List of ID's that should connect the employment object with the corresponding `income` object.

Employer
- `@id` - (string) - Unique identifier for the employer object.
- `@type` - (string) - Label that explains the type of employer. Values: employer
- `with_verification` - (array) - List of ID's that should connect the employer object with the corresponding `verification` object.
- `with_employment` - (array) - List of ID's that should connect the employer object with the corresponding `employment` object.

Verification
- `@id` - (string) - Unique identifier for the verification object.
- `@type` - (string) - Label that explains the type of verification. Values: verification
- `has_verification_report_identifier/has_value` - (string) - The verification report identifier. Each employer record should have it's own verification report identifier.

Address
- `@id` - (string) - Unique identifier for the address object.
- `@type` - (string) - Label that explains the type of address. Values: address, business_address
- `has_address_line_1_text/has_value` - (string) - The address line text.
- `has_address_line_2_text/has_value` - (string) - The address line text, for additional information.
- `has_city_name/has_value` - (string) - The address city name.
- `has_state_code/has_value` - (string) - The address stat code.
- `has_postal_code/has_value` - (string) - The address postal code.
- `has_country_name/has_value` - (string) - The address country name.

Organization
- `@id` - (string) - Unique identifier for the organization object.
- `@type` - (string) - Label that explains the type of organization. Values: organization
- `has_organization_name/has_value` - (string) - The organization name.

Mortgage Product
- `@id` - (string) - Unique identifier for the mortgage product object.
- `@type` - (string) - Label that explains the type of mortgage product. Values: mortgage_product
- `has_partner_product_name/has_value` - (string) - The partner product name.
- `has_response_datetime/has_value` - (string) - The product response datetime.
- `has_request_datetime/has_value` - (string) - The product request datetime.
- `has_partner_transaction_identifier/has_value` - (string) - The partner product transaction identifier, the verification identifier.
- `has_partner_name/has_value` - (string) - The partner name.

Contact Point
- `@id` - (string) - Unique identifier for the contact point object.
- `@type` - (string) - Label that explains the type of contact point. Values: contact_point
- `with_contact_point_email` - (string) - List of ID's that should connect the contact point with the corresponding `contact_point_emails` object.

Contact Point Email
- `@id` - (string) - Unique identifier for the contact point email object.
- `@type` - (string) - Label that explains the type of contact point email. Values: contact_point_emails
- `has_contact_point_email_value/has_value` - (string) - The email address.

Statuses
- `@id` - (string) - Unique identifier for the status object.
- `@type` - (string) - Label that explains the type of status. Values: status
- `has_status_code/has_value` - (string) - The status code.
- `has_status_name/has_value` - (string) - The status name.

Any warning, errors or unwanted behavior will be shown in the error objects:

Error Message
- `@id` - (string) - Unique identifier for the error message object.
- `@type` - (string) - Label that explains the type of error message. Values: error_message
- `has_error_message_text/has_value` - (string) - The error message.

Moreover, the system provides an API to get the status, you can use it using this link to get the data at any time.

<!--/source-->

##### Request

<!--source:api-specifications-->
Mock Request ExampleTruework Example 1Truework Example 2Truework Example 3Truework Example 4Truework Example 5Truework Example 6Truework Example 7Truework Example (Canceled) 8
<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "partner_name": "truework-instant",
 "callback_url": "callback.url",
 "request_data": {
 "people": [
 {
 "@id": "01FD6ZNGJADZ0RB1H96FSE8CEC",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "Mock"
 },
 "has_last_name": {
 "has_value": "Mocker"
 },
 "has_birth_date": {
 "has_value": "1973-01-01"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "990000001"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "33 IRVING PLACE"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "NEW YORK"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "test@test.com"
 },
 "has_phone_number": {
 "has_value": "+123456789"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "partner_name": "truework-instant",
 "callback_url": "callback.url",
 "request_data": {
 "people": [
 {
 "@id": "01FD6ZNGJADZ0RB1H96FSE8CEC",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "First"
 },
 "has_last_name": {
 "has_value": "Last"
 },
 "has_birth_date": {
 "has_value": "1992-12-05"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "000000000"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "123 Street"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "New York"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "some@email.com"
 },
 "has_phone_number": {
 "has_value": "+0099887766"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "partner_name": "truework-instant",
 "callback_url": "callback.url",
 "request_data": {
 "people": [
 {
 "@id": "01FD6ZNGJADZ0RB1H96FSE8CEC",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "First"
 },
 "has_last_name": {
 "has_value": "Last"
 },
 "has_birth_date": {
 "has_value": "1992-12-05"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "000000001"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "123 Street"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "New York"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "some@email.com"
 },
 "has_phone_number": {
 "has_value": "+0099887766"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "partner_name": "truework-instant",
 "callback_url": "callback.url",
 "request_data": {
 "people": [
 {
 "@id": "01FD6ZNGJADZ0RB1H96FSE8CEC",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "First"
 },
 "has_last_name": {
 "has_value": "Last"
 },
 "has_birth_date": {
 "has_value": "1992-12-05"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "000000002"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "123 Street"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "New York"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "some@email.com"
 },
 "has_phone_number": {
 "has_value": "+0099887766"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "partner_name": "truework-instant",
 "callback_url": "callback.url",
 "request_data": {
 "people": [
 {
 "@id": "01FD6ZNGJADZ0RB1H96FSE8CEC",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "First"
 },
 "has_last_name": {
 "has_value": "Last"
 },
 "has_birth_date": {
 "has_value": "1992-12-05"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "000000003"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "123 Street"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "New York"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "some@email.com"
 },
 "has_phone_number": {
 "has_value": "+0099887766"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "partner_name": "truework-instant",
 "callback_url": "callback.url",
 "request_data": {
 "people": [
 {
 "@id": "01FD6ZNGJADZ0RB1H96FSE8CEC",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "First"
 },
 "has_last_name": {
 "has_value": "Last"
 },
 "has_birth_date": {
 "has_value": "1992-12-05"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "000000004"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "123 Street"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "New York"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "some@email.com"
 },
 "has_phone_number": {
 "has_value": "+0099887766"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "partner_name": "truework-instant",
 "callback_url": "callback.url",
 "request_data": {
 "people": [
 {
 "@id": "01FD6ZNGJADZ0RB1H96FSE8CEC",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "First"
 },
 "has_last_name": {
 "has_value": "Last"
 },
 "has_birth_date": {
 "has_value": "1992-12-05"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "000000005"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "123 Street"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "New York"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "some@email.com"
 },
 "has_phone_number": {
 "has_value": "+0099887766"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "partner_name": "truework-instant",
 "callback_url": "callback.url",
 "request_data": {
 "people": [
 {
 "@id": "01FD6ZNGJADZ0RB1H96FSE8CEC",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "First"
 },
 "has_last_name": {
 "has_value": "Last"
 },
 "has_birth_date": {
 "has_value": "1992-12-05"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "000000007"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "123 Street"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "New York"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "some@email.com"
 },
 "has_phone_number": {
 "has_value": "+0099887766"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "partner_name": "truework-instant",
 "callback_url": "callback.url",
 "request_data": {
 "people": [
 {
 "@id": "01FD6ZNGJADZ0RB1H96FSE8CEC",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "First"
 },
 "has_last_name": {
 "has_value": "Last"
 },
 "has_birth_date": {
 "has_value": "1992-12-05"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "000010000"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "123 Street"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "New York"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "some@email.com"
 },
 "has_phone_number": {
 "has_value": "+0099887766"
 }
 }
 ]
 }
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Successfully started flow invocation.

```
{
 "response_id": "01F6NAQ4894HPMCBGB4P0G78HG"
}
```

<!--/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 403 invalid error

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
text/html Copy Resource not found

```
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Internal server error

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Environment API Key.<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `partner_name`required | `string` | <!--source:api-specifications-->Partner name.<!--/source-->Example `optimalBlue` |
| `callback_url` | `string` | <!--source:api-specifications-->Callback url<!--/source-->Example `callback.url` |
| `request_data`required | `object` | <!--source:api-specifications-->Request data for Income.<!--/source--> |
| `people`required | `object[]` | <!--source:api-specifications-->List of persons.<!--/source--> |
| `@type`required | `string` | <!--source:api-specifications-->Persons type.<!--/source--> |
| `@id`required | `string` | <!--source:api-specifications-->Persons id.<!--/source--> |
| `has_first_name`required | `object` | <!--source:api-specifications-->Persons first name.<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Persons first name.<!--/source--> |
| `has_last_name`required | `object` | <!--source:api-specifications-->Persons last name.<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Persons last name.<!--/source--> |
| `has_birth_date`required | `object` | <!--source:api-specifications-->Persons date of birth.<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Persons date of birth.<!--/source--> |
| `has_taxpayer_identifier_value`required | `object` | <!--source:api-specifications-->Persons taxpayer identifier.<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Persons taxpayer identifier.<!--/source--> |
| `with_address`required | `string[]` | <!--source:api-specifications-->ID's that point to the corresponding address object.<!--/source--> |
| `contact_at`required | `string[]` | <!--source:api-specifications-->ID's that point to the corresponding contact_information object.<!--/source--> |
| `addresses`required | `object[]` | <!--source:api-specifications-->Addresses class.<!--/source--> |
| `@type`required | `string` | <!--source:api-specifications-->Address type.<!--/source--> |
| `@id`required | `string` | <!--source:api-specifications-->Address id.<!--/source--> |
| `has_address_line_1_text`required | `object` | <!--source:api-specifications-->Address line 1.<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Address line 1 text.<!--/source--> |
| `has_city_name`required | `object` | <!--source:api-specifications-->Address city name.<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Address city name.<!--/source--> |
| `has_state_code`required | `object` | <!--source:api-specifications-->Address state code.<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Address state code.<!--/source--> |
| `has_postal_code`required | `object` | <!--source:api-specifications-->Address postal code.<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Address postal code.<!--/source--> |
| `contact_information`required | `object[]` | <!--source:api-specifications-->Contact Information class.<!--/source--> |
| `@type`required | `string` | <!--source:api-specifications-->Contact Information type.<!--/source--> |
| `@id`required | `string` | <!--source:api-specifications-->Contact Information id.<!--/source--> |
| `has_email_address`required | `object` | <!--source:api-specifications-->Email address.<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Email address.<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Successfully started flow invocation.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `response_id`required | `string` | <!--source:api-specifications-->Response collection ID.<!--/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-->
2 fields
<!--/source-->
<!--source:api-specifications-->
403 invalid error
<!--/source-->

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

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Internal server error
<!--/source-->

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

`GET` `/verification/{id}`

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

#### Retrieve Income Verification Status
<!--/source-->

`RetrieveIncomeVerificationFlowInvocationStatus`

<!--source:api-specifications-->
Retrieves the result of running Income Verification process.

The status of the process can be found in `metadata` `invocation_status` once the status is `COMPLETED` the Income and Employment data will be stored in the `data` object.

If something fails an error message with further details will be stored in the `data` object.

##### Response Payload

#### API Response

This endpoint returns the following response object:

Show the rest People
- `@id` - (string) - Unique identifier for the person object.
- `@type` - (string) - Label that explains the type of person. Values: borrower
- `has_first_name/has_value` - (string) - The person's first name.
- `has_last_name/has_value` - (string) - The person's last name.
- `has_birth_date/has_value` - (string) - The person's birth date.
- `has_taxpayer_identifier_value/has_value` - (string) - The person's tax payer identifier (SSN).
- `with_address` - (array) - List of ID's that should connect the person object with the corresponding `address` object.
- `earns` - (array) - List of ID's that should connect the person object with the corresponding `income` object.
- `works_for` - (array) - List of ID's that should connect the person object with the corresponding `organization` object.
- `with_contact_point` - (array) - List of ID's that should connect the person object with the corresponding `contact_information` object.

Income
- `@id` - (string) - Unique identifier for the income object.
- `@type` - (string) - Label that explains the type of income. Values: employment_income
- `has_income_year/has_value` - (string) - The income year.
- `has_income_pay_frequency_type/has_value` - (string) - The income pay frequency type.
- `has_base_income_amount/has_value` - (string) - The income base amount.
- `has_income_amount/has_value` - (string) - The income amount.
- `has_overtime_income_amount/has_value` - (string) - The income overtime amount.
- `has_commission_income_amount/has_value` - (string) - The income commission amount.
- `has_bonus_income_amount` - (string) - The income bonus amount.
- `earned_from` - (array) - List of ID's that should connect the income object with the corresponding `employment` object.

Employment
- `@id` - (string) - Unique identifier for the employment object.
- `@type` - (string) - Label that explains the type of employment. Values: employment
- `has_current_employment_indicator/has_value` - (boolean) - Wheter the borrower is currently employed.
- `has_employment_start_date/has_value` - (string) - The employment start date.
- `has_employment_end_date/has_value` - (string) - The employment end date.
- `has_employment_type/has_value` - (string) - The employment type.
- `has_employment_position_description/has_value` - (string) - The employment position description.
- `provided_by` - (array) - List of ID's that should connect the employment object with the corresponding `organization` object.
- `earns` - (array) - List of ID's that should connect the employment object with the corresponding `income` object.

Employer
- `@id` - (string) - Unique identifier for the employer object.
- `@type` - (string) - Label that explains the type of employer. Values: employer
- `with_verification` - (array) - List of ID's that should connect the employer object with the corresponding `verification` object.
- `with_employment` - (array) - List of ID's that should connect the employer object with the corresponding `employment` object.

Verification
- `@id` - (string) - Unique identifier for the verification object.
- `@type` - (string) - Label that explains the type of verification. Values: verification
- `has_verification_report_identifier/has_value` - (string) - The verification report identifier. Each employer record should have it's own verification report identifier.

Address
- `@id` - (string) - Unique identifier for the address object.
- `@type` - (string) - Label that explains the type of address. Values: address, business_address
- `has_address_line_1_text/has_value` - (string) - The address line text.
- `has_address_line_2_text/has_value` - (string) - The address line text, for additional information.
- `has_city_name/has_value` - (string) - The address city name.
- `has_state_code/has_value` - (string) - The address stat code.
- `has_postal_code/has_value` - (string) - The address postal code.
- `has_country_name/has_value` - (string) - The address country name.

Organization
- `@id` - (string) - Unique identifier for the organization object.
- `@type` - (string) - Label that explains the type of organization. Values: organization
- `has_organization_name/has_value` - (string) - The organization name.

Mortgage Product
- `@id` - (string) - Unique identifier for the mortgage product object.
- `@type` - (string) - Label that explains the type of mortgage product. Values: mortgage_product
- `has_partner_product_name/has_value` - (string) - The partner product name.
- `has_response_datetime/has_value` - (string) - The product response datetime.
- `has_request_datetime/has_value` - (string) - The product request datetime.
- `has_partner_transaction_identifier/has_value` - (string) - The partner product transaction identifier, the verification identifier.
- `has_partner_name/has_value` - (string) - The partner name.

Contact Point
- `@id` - (string) - Unique identifier for the contact point object.
- `@type` - (string) - Label that explains the type of contact point. Values: contact_point
- `with_contact_point_email` - (string) - List of ID's that should connect the contact point with the corresponding `contact_point_emails` object.

Contact Point Email
- `@id` - (string) - Unique identifier for the contact point email object.
- `@type` - (string) - Label that explains the type of contact point email. Values: contact_point_emails
- `has_contact_point_email_value/has_value` - (string) - The email address.

Statuses
- `@id` - (string) - Unique identifier for the status object.
- `@type` - (string) - Label that explains the type of status. Values: status
- `has_status_code/has_value` - (string) - The status code.
- `has_status_name/has_value` - (string) - The status name.

Any warning, errors or unwanted behavior will be shown in the error objects:

Error Message
- `@id` - (string) - Unique identifier for the error message object.
- `@type` - (string) - Label that explains the type of error message. Values: error_message
- `has_error_message_text/has_value` - (string) - The error message.

<!--/source-->

##### Response

<!--source:api-specifications-->
200 Success Status Example200 Error Status Example200 Failed Status Examlpe400403404500
<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully returned result of the Income Verification.

```
{
 "transaction_id": "01GT91JJRFRV60T4TTEMXFZMWE",
 "collection_id": "01GT91JJZRZ5ZNP7Y6V63527T7",
 "metadata": {
 "validation": false,
 "serialise_to_graph": false,
 "created_at": "2023-03-27T11:14:48.118327-04:00",
 "invocation_status": "COMPLETED",
 "last_updated_at": "2023-03-27T11:14:51.943421-04:00",
 "partner_name": "truework-instant",
 "product_invocation_id": "01GWHT5PNPJA3JE0BT1DY3H24H",
 "product_name": "income"
 },
 "data": {
 "income": [
 {
 "has_income_year": {
 "has_value": "2023"
 },
 "has_income_pay_frequency_type": {
 "has_value": "hourly"
 },
 "has_base_income_amount": {
 "has_value": 11700
 },
 "@type": "employment_income",
 "@id": "01H14SCKEG11HTXK6RE0D36QKE",
 "has_income_amount": {
 "has_value": 17349.38
 },
 "has_overtime_income_amount": {
 "has_value": 5649.38
 },
 "has_bonus_income_amount": {
 "has_value": 0
 },
 "earned_from": [
 "01H14SCKEGTTW42HVP124G89Y8"
 ],
 "has_commission_income_amount": {
 "has_value": 0
 }
 },
 {
 "has_income_year": {
 "has_value": "2022"
 },
 "has_income_pay_frequency_type": {
 "has_value": "hourly"
 },
 "has_base_income_amount": {
 "has_value": 31200
 },
 "@type": "employment_income",
 "@id": "01H14SCKEG31158MXP266XHQ69",
 "has_income_amount": {
 "has_value": 44020
 },
 "has_overtime_income_amount": {
 "has_value": 10820
 },
 "has_bonus_income_amount": {
 "has_value": 2000
 },
 "earned_from": [
 "01H14SCKEGTTW42HVP124G89Y8"
 ],
 "has_commission_income_amount": {
 "has_value": 0
 }
 }
 ],
 "contact_point_emails": [
 {
 "@type": "contact_point_email",
 "@id": "01H14SCKEGYK7KM0SD6BHR0TRP",
 "has_contact_point_email_value": {
 "has_value": "test@test.com"
 }
 }
 ],
 "employers": [
 {
 "with_verification": [
 "01H14SCKEGADZWNJ1MN6ARBSK4"
 ],
 "with_employment": [
 "01H14SCKEGTTW42HVP124G89Y8"
 ],
 "@id": "01H14SCKEGTGPTFZEJ1JESD1YG",
 "@type": "employer"
 }
 ],
 "addresses": [
 {
 "@type": "business_address",
 "has_country_name": {
 "has_value": "US"
 },
 "@id": "01H14SCKEX6STTM90HNQEDRVSP"
 }
 ],
 "contact_points": [
 {
 "with_contact_point_email": [
 "01H14SCKEGYK7KM0SD6BHR0TRP"
 ],
 "@type": "contact_point",
 "@id": "01H14SCKEX0H1YDD8X48EMD3P5"
 }
 ],
 "organizations": [
 {
 "has_organization_name": {
 "has_value": "Fake Company"
 },
 "@type": "organization",
 "@id": "01H14SCKEXV76WE03DJBKDDVX7"
 }
 ],
 "mortgage_products": [
 {
 "has_partner_product_name": {
 "has_value": "employment-income"
 },
 "has_response_datetime": {
 "has_value": "2023-05-23 17:09:24.709727+00:00"
 },
 "@type": "mortgage_product",
 "has_request_datetime": {
 "has_value": "2023-05-23 17:09:23.664080+00:00"
 },
 "has_partner_transaction_identifier": {
 "has_value": "AAAAAAAGxL0ABwNlUkhIDmI5qVwPSM5AdbIgWZfzfAsPMkGBHbH83-9T"
 },
 "@id": "01H14SCKEXHGHAH3D1TR1FZ4J2",
 "has_partner_name": {
 "has_value": "Truework-Instant"
 }
 }
 ],
 "employment": [
 {
 "has_current_employment_indicator": {
 "has_value": true
 },
 "has_employment_start_date": {
 "has_value": "2022-05-19"
 },
 "has_employment_type": {
 "has_value": "employed"
 },
 "@type": "employment",
 "earns": [
 "01H14SCKEG11HTXK6RE0D36QKE"
 ],
 "has_employment_position_description": {
 "has_value": "Customer Service Representative"
 },
 "provided_by": [
 "01H14SCKEXV76WE03DJBKDDVX7"
 ],
 "@id": "01H14SCKEGTTW42HVP124G89Y8"
 }
 ],
 "verifications": [
 {
 "has_verification_report_identifier": {
 "has_value": "AAAAAAADh_8AC7bZquqdW-RPCi-iLBVMgEXFNgSm0_kmWpyB2lDGmNGc"
 },
 "@type": "verification",
 "@id": "01H14SCKEGADZWNJ1MN6ARBSK4"
 }
 ],
 "people": [
 {
 "has_taxpayer_identifier_value": {
 "has_value": "***-**-0004"
 },
 "@type": "borrower",
 "earns": [
 "01H14SCKEG31158MXP266XHQ69",
 "01H14SCKEG11HTXK6RE0D36QKE"
 ],
 "has_birth_date": {
 "has_value": "1973-01-01"
 },
 "has_last_name": {
 "has_value": "Jackson"
 },
 "@id": "01H14SCKEX8SWVYQ9GYKNKFGHW",
 "with_contact_point": [
 "01H14SCKEX0H1YDD8X48EMD3P5"
 ],
 "works_for": [
 "01H14SCKEXV76WE03DJBKDDVX7"
 ],
 "has_first_name": {
 "has_value": "John"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully returned result of the Income Verification.

```
{
 "transaction_id": "01GT91JJRFRV60T4TTEMXFZMWE",
 "collection_id": "01GT91JJZRZ5ZNP7Y6V63527T7",
 "metadata": {
 "validation": false,
 "serialise_to_graph": false,
 "created_at": "2023-03-27T11:14:48.118327-04:00",
 "invocation_status": "COMPLETED",
 "last_updated_at": "2023-03-27T11:14:51.943421-04:00",
 "partner_name": "truework-instant",
 "product_invocation_id": "01GWHT5PNPJA3JE0BT1DY3H24H",
 "product_name": "income"
 },
 "data": {
 "statuses": [
 {
 "has_status_name": {
 "has_value": "Failed"
 },
 "has_status_code": {
 "has_value": "400"
 },
 "@id": "01H0FQRJGZHQAQHEXS4K5NXE68",
 "@type": "status"
 }
 ],
 "mortgage_products": [
 {
 "has_partner_product_name": {
 "has_value": "employment-income"
 },
 "@id": "01H0FQRJGZ9NN9KBKEYB9PFSNB",
 "has_partner_name": {
 "has_value": "Truework-Instant"
 },
 "@type": "mortgage_product"
 }
 ],
 "people": [
 {
 "@type": "borrower",
 "@id": "01H0FQRJCEQ01KK61KR55G3435"
 }
 ],
 "error_messages": [
 {
 "has_error_message_text": {
 "has_value": "Invalid field values provided"
 },
 "@type": "error_message",
 "@id": "01H0FQRJGZ0PYJGKH80Q751MRT"
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully returned result of the Income Verification.

```
{
 "transaction_id": "01GT91JJRFRV60T4TTEMXFZMWE",
 "collection_id": "01GT91JJZRZ5ZNP7Y6V63527T7",
 "metadata": {
 "validation": false,
 "serialise_to_graph": false,
 "created_at": "2023-03-27T11:14:48.118327-04:00",
 "invocation_status": "COMPLETED",
 "last_updated_at": "2023-03-27T11:14:51.943421-04:00",
 "partner_name": "truework-instant",
 "product_invocation_id": "01GWHT5PNPJA3JE0BT1DY3H24H",
 "product_name": "income"
 },
 "data": {
 "statuses": [
 {
 "has_status_name": {
 "has_value": "Failed"
 },
 "has_status_code": {
 "has_value": "500"
 },
 "@id": "01H0FQRJGZHQAQHEXS4K5NXE68",
 "@type": "status"
 }
 ],
 "mortgage_products": [
 {
 "has_partner_product_name": {
 "has_value": "employment-income"
 },
 "@id": "01H0FQRJGZ9NN9KBKEYB9PFSNB",
 "has_partner_name": {
 "has_value": "Truework-Instant"
 },
 "@type": "mortgage_product"
 }
 ],
 "people": [
 {
 "@type": "borrower",
 "@id": "01H0FQRJCEQ01KK61KR55G3435"
 }
 ],
 "error_messages": [
 {
 "has_error_message_text": {
 "has_value": "Something went wrong!"
 },
 "@type": "error_message",
 "@id": "01H0FQRJGZ0PYJGKH80Q751MRT"
 }
 ]
 }
}
```

<!--/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 403 invalid error

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
text/html Copy Resource not found

```
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Internal server error

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Environment API Key.<!--/source--> |
| `id` required | `string (Staircase Response Collection Identifier)` path | `01FFMHWSS346W9V6HZVGSEZPQ` | <!--source:api-specifications-->Income ID<!--/source--> |

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

<!--source:api-specifications-->
4 fields
<!--/source-->
<!--source:api-specifications-->
Successfully returned result of the Income Verification.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string (ulid)` | <!--source:api-specifications-->Transaction ID.<!--/source-->Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `collection_id` | `string (ulid)` | <!--source:api-specifications-->Collection ID.<!--/source-->Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `data` | `object` | <!--source:api-specifications-->Income Data in Staircase lexicon schema.<!--/source--> |
| `metadata` | `object` | <!--source:api-specifications-->Metadata about collection, f.e version of used Staircase schema.<!--/source--> |
| `product_name` | `string` | <!--source:api-specifications-->Product name<!--/source-->Example `income` |
| `partner_name` | `string` | <!--source:api-specifications-->Partner name<!--/source-->Example `truework-instant` |
| `created_at` | `string` | <!--source:api-specifications-->Time of creation<!--/source--> |
| `last_updated_at` | `string` | <!--source:api-specifications-->Time of last update<!--/source--> |
| `invocation_status` | `string` | <!--source:api-specifications-->Status of the Income Verification.<!--/source-->`COMPLETED``FAILED``RUNNING``STARTED` |

##### 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-->
2 fields
<!--/source-->
<!--source:api-specifications-->
403 invalid error
<!--/source-->

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

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Internal server error
<!--/source-->

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

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

### Setup
<!--/source-->

`POST` `/argyle/credentials`

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

#### Set Argyle Credentials
<!--/source-->

`setArgyleCredentials`

<!--source:api-specifications-->
By using Set Argyle Credentials API we allow our customers to configure Argyle in customer environment.

If you want to use your own Argyle contract for verification , please check Request body Schema example for required values from partner side and run Set Argyle Credentials API

You can check the partner status by calling the Retrieve Partners endpoint

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "client_id": "--------",
 "client_secret": "<redacted>",
 "link_key": "--------",
 "contract": "BYOC",
 "type": "test"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `client_id`required | `string` | <!--source:api-specifications-->Argyle client ID value<!--/source--> |
| `client_secret`required | `string` | <!--source:api-specifications-->Argyle client secret value<!--/source--> |
| `link_key`required | `string` | <!--source:api-specifications-->Argyle link key<!--/source--> |
| `contract` | `string` | <!--source:api-specifications-->Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/atomic/credentials`

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

#### Set Atomic Credentials
<!--/source-->

`setAtomicCredentials`

<!--source:api-specifications-->
By using Set Atomic Credentials API we allow our customers to configure Atomic partner in customer environment.

If you want to use your own Atomic contract for verification , please check Request body Schema example for required values from partner side and run Set Atomic Credentials API

Below is a step-by-step guide on how to add the webhook on partner dashboard.

Show the rest If you don't add webhook on partner dashboard, verification will be triggered, but response of the verification will not be available, and you can be charged for verification.

Adding webhook workflow:

1. Login to your Atomic Dashboard using your username and password.

1. In the navigation menu browse to Settings.

1. Under Webhooks, click the Add endpoint button.

1. Add the following URL to the Endpoint URL input field:

NOTE: Change SUBDOMAIN value with your actual domain name

1. Add Task status updates to the Events input field.

1. Click on Add endpoint.

Please check Request body Schema example for required values from partner side.

You can check the partner status by calling the Retrieve Partners endpoint

You are now ready to use the partner integration.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "client_key": "--------",
 "client_secret": "<redacted>",
 "username": "test@test.com",
 "password": "<redacted>",
 "contract": "SC",
 "type": "test"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `client_key` | `string` | <!--source:api-specifications-->Atomic client key<!--/source--> |
| `client_secret`required | `string` | <!--source:api-specifications-->Atomic client secret<!--/source--> |
| `username`required | `string` | <!--source:api-specifications-->Atomic username<!--/source--> |
| `password`required | `string` | <!--source:api-specifications-->Atomic password<!--/source--> |
| `contract` | `string` | <!--source:api-specifications-->Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/equifax/credentials`

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

#### Set Equifax Credentials
<!--/source-->

`setEquifaxCredentials`

<!--source:api-specifications-->
By using Set Equifax Credentials API we allow our customers to configure Equifax partner in customer environment.

If you want to use your own Equifax contract for verification , please check Request body Schema example for required values from partner side and run Set Equifax Credentials API.

To enable partner Equifax for verification you need to:

Setting credentials

Show the rest Add all key values for your Equifax, TheWorkNumber Account : "twn_username", "twn_password" , "pfx_certificate_password" and "type" in request body.

Please check request body schema example.

PFX certificate

In addition to setting credentials for Equifax you need to upload a PFX certificate. Use Upload Equifax Certificate API to upload certificate to your environment. PFX Certificate needs to be provided by Equifax. If you don't have it, you will not be able to use Equifax as partner for verification.

If this is the case please contact your Equifax Account Manager, and get PFX certificate and password for certificate.

You can check the partner status by calling the Retrieve Partners endpoint

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "twn_username": "UserNameIntgTEST@5005",
 "twn_password": "I_9087POK",
 "pfx_certificate_password": "9huoiqhiokopj9iu",
 "contract": "SC",
 "type": "production"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `twn_username`required | `string` | <!--source:api-specifications-->Equifax The Work Number username<!--/source--> |
| `twn_password`required | `string` | <!--source:api-specifications-->Equifax The Work Number password<!--/source--> |
| `pfx_certificate_password` | `string` | <!--source:api-specifications-->Equifax PFX Certificate password<!--/source--> |
| `contract` | `string` | <!--source:api-specifications-->Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/equifax/certificate`

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

#### Upload Equifax Certificate
<!--/source-->

`uploadEquifaxCertificate`

<!--source:api-specifications-->
Upload Equifax Certificate For uploading Equifax PFX Certificate you will need to issue a POST request to this endpoint. Upload Equifax Certificate uploads a .pfx document to our services. You can upload the certificate using HTML Request Maker Try It Out. Place your api_key in the request header, please make sure Content-Type is set to application/x-pkcs12. Set the request body to binary and browse to your PFX Certificate. Click Send to upload your certificate. To upload a certificate programmatically, use the upload example below. After you get a successful response, you can start using the Equifax integration.

```
import requests
url = ""
payload = open("certificate.pfx", "rb")
headers = {
 'x-api-key': 'API_KEY',
 'Content-Type': 'application/x-pkcs12'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
Select option 'binary' in order to upload file
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Certificate uploaded and saved successfully"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/truework/credentials`

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

#### Set Truework Credentials
<!--/source-->

`setTrueworkCredentials`

<!--source:api-specifications-->
By using Set Truework Credentials API we allow our customers to configure Truework partner in customer environment.

If you want to use your own Truework contract for verification , please check Request body Schema example for required values from partner side and run Set Truework Credentials API

Below is a step-by-step guide on how to add the webhook on partner dashboard:

Show the rest If you don't add webhook on partner dashboard, verification will be triggered, but response of the verification will not be available, and you can be charged for verification.

1. Login to your Truework Dashboard using your username and password.

1. In the navigation menu browse to Developer.

1. Under API Settings, Production Webhooks click the Edit button.

1. Under the Add Production Webhook section click the Event input and select "Verification Request Status Changed"

1. Select the Target input and add the following URL:

NOTE: Change SUBDOMAIN value with your actual domain name

1. Click on Create.

Please check Request body Schema example for required values from partner side.

You can check the partner status by calling the Retrieve Partners endpoint

You are now ready to use the partner integration.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "token": "<redacted>",
 "username": "test@test.com",
 "password": "<redacted>",
 "contract": "BYOC",
 "type": "test"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `token`required | `string` | <!--source:api-specifications-->Truework token for API<!--/source--> |
| `username` | `string` | <!--source:api-specifications-->Truework username<!--/source--> |
| `password` | `string` | <!--source:api-specifications-->Truework password<!--/source--> |
| `contract` | `string` | <!--source:api-specifications-->Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/truework-instant/credentials`

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

#### Set Truework Instant Credentials
<!--/source-->

`setTrueworkInstantCredentials`

<!--source:api-specifications-->
Set Truework-Instant Credentials
<!--/source-->

<!--source:api-specifications-->
By using Set Truework-instant Credentials API we allow our customers to configure Truework Instant partner in customer environment for instant verifications.

If you want to use your own Truework contract for verification, please check Request body Schema example for required values from partner side and run Set Truework Instant Credentials API

Please check Request body Schema example for required values from partner side.

You can check the partner status by calling the Retrieve Partners endpoint

You are now ready to use the partner integration.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "token": "<redacted>",
 "type": "test"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `token`required | `string` | <!--source:api-specifications-->Truework-Instant token for API<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/pinwheel/credentials`

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

#### Set Pinwheel Credentials
<!--/source-->

`setPinwheelCredentials`

<!--source:api-specifications-->
By using Set Pinwheel Credentials API we allow our customers to configure Pinwheel partner in customer environment.

If you want to use your own Pinwheel contract for verification , please check Request body Schema example for required values from partner side and run Set Pinwheel Credentials API.

You can check the partner status by calling the Retrieve Partners endpoint

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "x_api_secret": "--------",
 "contract": "SC",
 "type": "test"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `x_api_secret`required | `string` | <!--source:api-specifications-->Pinwheel API secret<!--/source--> |
| `contract` | `string` | <!--source:api-specifications-->Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/plaid/credentials`

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

#### Set Plaid Credentials
<!--/source-->

`setPlaidCredentials`

<!--source:api-specifications-->
By using Set Plaid Credentials API we allow our customers to configure Plaid partner in customer environment.

If you want to use your own Plaid contract for verification , please check Request body Schema example for required values from partner side and run Set Plaid Credentials API.

You can check the partner status by calling the Retrieve Partners endpoint

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "client_id": "90876sad58908dsd6890",
 "client_secret": "<redacted>",
 "contract": "BYOC",
 "type": "production"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `client_id`required | `string` | <!--source:api-specifications-->Plaid client ID<!--/source--> |
| `client_secret`required | `string` | <!--source:api-specifications-->Plaid client secret<!--/source--> |
| `contract` | `string` | <!--source:api-specifications-->Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/meridian/credentials`

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

#### Set Meridian Credentials
<!--/source-->

`setMeridianCredentials`

<!--source:api-specifications-->
By using Set Meridian Credentials API we allow our customers to configure Meridian in customer environment.

If you want to use your own Meridian contract for verification, please check Request body Schema example for required values from partner side and run Set Meridian Credentials API.

We currently can't provide Staircase contract for Meridian.

You can check the partner status by calling the Retrieve Partners endpoint

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "client_id": "--------",
 "client_secret": "<redacted>",
 "domain": "example.domain.com",
 "mcl": "--------",
 "contract": "BYOC",
 "type": "test"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `client_id`required | `string` | <!--source:api-specifications-->Meridian client ID<!--/source--> |
| `client_secret`required | `string` | <!--source:api-specifications-->Meridian client secret<!--/source--> |
| `domain`required | `string` | <!--source:api-specifications-->Meridian domain<!--/source--> |
| `mcl`required | `string` | <!--source:api-specifications-->Meridian MCL schema<!--/source--> |
| `contract` | `string` | <!--source:api-specifications-->Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC<!--/source--> |
| `type` | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/truv/credentials`

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

#### Set Truv Credentials
<!--/source-->

`setTruvCredentials`

<!--source:api-specifications-->
By using Set Truv Credentials API we allow our customers to configure Meridian in customer environment.

If you want to use your own Truv contract for verification , please check Request body Schema example for required values from partner side and run Set Truv Credentials API.

We currently can't provide Staircase contract for Truv.

You can check the partner status by calling the Retrieve Partners endpoint

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "client_id": "--------",
 "client_secret": "<redacted>",
 "type": "test"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `client_id`required | `string` | <!--source:api-specifications-->Truv client ID<!--/source--> |
| `client_secret`required | `string` | <!--source:api-specifications-->Truv client secret<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source-->`production``test` |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/experian/credentials`

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

#### Set Experian Credentials
<!--/source-->

`setExperianCredentials`

<!--source:api-specifications-->
By using Set Experian Credentials API we allow our customers to configure Experian in customer environment.

If you want to use your own Experian contract for verification, please check Request body Schema example for required values from partner side and run Set Experian Credentials API.

You can check the partner status by calling the Retrieve Partners endpoint.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "client_id": "--------",
 "client_secret": "<redacted>",
 "username": "--------",
 "password": "<redacted>",
 "contract": "BYOC",
 "type": "test"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `client_id`required | `string` | <!--source:api-specifications-->Experian client ID<!--/source--> |
| `client_secret`required | `string` | <!--source:api-specifications-->Experian client secret<!--/source--> |
| `username`required | `string` | <!--source:api-specifications-->Experian username<!--/source--> |
| `password`required | `string` | <!--source:api-specifications-->Experian password<!--/source--> |
| `contract` | `string` | <!--source:api-specifications-->Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source-->`production``test` |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

`POST` `/finicity/credentials`

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

#### Set Finicity Credentials
<!--/source-->

`setFinicityCredentials`

<!--source:api-specifications-->
By using Set Finicity Credentials API we allow our customers to configure Finicity partner in customer environment.

If you want to use your own Finicity contract for verification , please check Request body Schema example for required values from partner side and run Set Finicity Credentials API.

You can check the partner status by calling the Retrieve Partners endpoint

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "partnerId": "--------",
 "partnerSecret": "--------",
 "apiKey": "<redacted>",
 "contract": "SC",
 "type": "test"
}
```

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Setup API Triggered Successfully

```
{
 "message": "Credentials are saved and verified"
}
```

<!--/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 Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Invalid request body",
 "error": "[object has missing required properties ([\"client_secret\"])]"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error

```
{
 "message": "The product has encountered an internal server error"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Environment API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `partnerId`required | `string` | <!--source:api-specifications-->Finicity partner ID<!--/source--> |
| `partnerSecret`required | `string` | <!--source:api-specifications-->Finicity partner secret<!--/source--> |
| `apiKey`required | `string` | <!--source:api-specifications-->Finicity API key<!--/source--> |
| `contract` | `string` | <!--source:api-specifications-->Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC<!--/source--> |
| `type`required | `string` | <!--source:api-specifications-->Type of credentials, can be either test or production<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Setup API Triggered Successfully
<!--/source-->

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

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error
<!--/source-->

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

##### Other responses

`404`

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

### Platform
<!--/source-->

`GET` `/products/income/request-schema`

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

#### Retrieve Example Schema
<!--/source-->

`retrieveSchema`

<!--source:api-specifications-->
Retrieve Schema retrieves a JSON schema for the request and the response returned by the product. It can also return an example of a json object defined with schema.

#### Testing Income:

If you want an example collection:

- In the query parameters set `return_examples` to `true`

You can directly pass an example returned by the `/request-schema` endpoint into the Create Collection endpoint as a request body.

<!--/source-->

##### Response

<!--source:api-specifications-->
200 Example V0 Schema200 Example V2 Schema400 InvalidDataObject400 InvalidVersionValue400 MissingVersionParameter400 InvalidReturnExamplesValue403
<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully returned the list of elements needed for Income.

```
{
 "$schema": "http://json-schema.org/draft-04/schema#",
 "type": "object",
 "properties": {
 "deal_sets": {
 "type": "object",
 "properties": {
 "deal_set": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "deals": {
 "type": "object",
 "properties": {
 "deal": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "parties": {
 "type": "object",
 "properties": {
 "party": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "customer_transaction_ID": {
 "type": "string"
 },
 "individual": {
 "type": "object",
 "properties": {
 "contact_points": {
 "type": "object",
 "properties": {
 "contact_point": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "contact_point_telephone": {
 "type": "object",
 "properties": {
 "value": {
 "type": "string"
 }
 },
 "required": [
 "value"
 ]
 },
 "contact_point_email": {
 "type": "object",
 "properties": {
 "value": {
 "type": "string"
 }
 },
 "required": [
 "value"
 ]
 }
 },
 "required": [
 "contact_point_telephone",
 "contact_point_email"
 ]
 }
 }
 },
 "required": [
 "contact_point"
 ]
 },
 "name": {
 "type": "object",
 "properties": {
 "first": {
 "type": "string"
 },
 "last": {
 "type": "string"
 }
 },
 "required": [
 "first",
 "last"
 ]
 }
 },
 "required": [
 "contact_points",
 "name"
 ]
 },
 "roles": {
 "type": "object",
 "properties": {
 "role": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "borrower": {
 "type": "object",
 "properties": {
 "birth_date": {
 "type": "string"
 },
 "employers": {
 "type": "object",
 "properties": {
 "employer": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "legal_entity": {
 "type": "object",
 "properties": {
 "full_name": {
 "type": "string"
 }
 },
 "required": [
 "full_name"
 ]
 }
 },
 "required": [
 "legal_entity"
 ]
 }
 }
 },
 "required": [
 "employer"
 ]
 },
 "residences": {
 "type": "object",
 "properties": {
 "residence": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "address": {
 "type": "object",
 "properties": {
 "additional_line_text": {
 "type": "string"
 },
 "city": {
 "type": "string"
 },
 "country": {
 "type": "string"
 },
 "line_text": {
 "type": "string"
 },
 "postal_code": {
 "type": "string"
 },
 "state_code": {
 "type": "string"
 }
 },
 "required": [
 "additional_line_text",
 "city",
 "country",
 "line_text",
 "postal_code",
 "state_code"
 ]
 }
 },
 "required": [
 "address"
 ]
 }
 }
 },
 "required": [
 "residence"
 ]
 }
 },
 "required": [
 "birth_date",
 "employers",
 "residences"
 ]
 }
 },
 "required": [
 "borrower"
 ]
 }
 }
 },
 "required": [
 "role"
 ]
 },
 "taxpayer_identifiers": {
 "type": "object",
 "properties": {
 "taxpayer_identifier": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "value": {
 "type": "string"
 }
 },
 "required": [
 "value"
 ]
 }
 }
 },
 "required": [
 "taxpayer_identifier"
 ]
 }
 },
 "required": [
 "customer_transaction_ID",
 "individual",
 "roles",
 "taxpayer_identifiers"
 ]
 }
 }
 },
 "required": [
 "party"
 ]
 }
 },
 "required": [
 "parties"
 ]
 }
 }
 },
 "required": [
 "deal"
 ]
 }
 },
 "required": [
 "deals"
 ]
 }
 }
 },
 "required": [
 "deal_set"
 ]
 },
 "document_sets": {
 "type": "object",
 "properties": {
 "document_set": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "documents": {
 "type": "object",
 "properties": {
 "document": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "document_classification": {
 "type": "object",
 "properties": {
 "document_classes": {
 "type": "object",
 "properties": {
 "document_class": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "staircase_type": {
 "type": "string"
 },
 "type": {
 "type": "string"
 }
 }
 }
 }
 }
 }
 }
 },
 "foreign_objects": {
 "type": "object",
 "properties": {
 "foreign_object": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "description": {
 "type": "string"
 },
 "mime_type_identifier": {
 "type": "string"
 },
 "name": {
 "type": "string"
 },
 "staircase_blob_id": {
 "type": "string"
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 },
 "required": [
 "deal_sets"
 ]
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully returned the list of elements needed for Income.

```
{
 "type": "object",
 "properties": {
 "people": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "has_first_name": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_last_name": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_birth_date": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_taxpayer_identifier_value": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "with_address": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "@type": {
 "type": "string"
 },
 "has_address_line_1_text": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_address_line_2_text": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_city_name": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_state_code": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_postal_code": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_country_name": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 }
 },
 "required": [
 "@type",
 "has_address_line_1_text",
 "has_address_line_2_text",
 "has_city_name",
 "has_state_code",
 "has_postal_code",
 "has_country_name"
 ]
 }
 },
 "contact_at": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "@type": {
 "type": "string"
 },
 "has_email_address": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_phone_number": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 }
 },
 "required": [
 "@type",
 "has_email_address",
 "has_phone_number"
 ]
 }
 },
 "works_for": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "@type": {
 "type": "string"
 },
 "has_organization_name": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 }
 },
 "required": [
 "@type",
 "has_organization_name"
 ]
 }
 }
 },
 "required": [
 "has_first_name",
 "has_last_name",
 "has_birth_date",
 "has_taxpayer_identifier_value",
 "with_address",
 "contact_at",
 "works_for"
 ]
 }
 }
 },
 "required": [
 "people"
 ]
}
```

<!--/source-->

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

```
{
 "message": "Please provide one of valid data object values: request, response"
}
```

<!--/source-->

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

```
{
 "message": "Please provide one of valid version values: v0"
}
```

<!--/source-->

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

```
{
 "message": "Please make sure your query parameters contains version parameter."
}
```

<!--/source-->

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

```
{
 "message": "Please provide one of valid return examples values: true, false"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `return_examples` | `boolean` query | `false` | <!--source:api-specifications-->If included and set to `true`, returns one or more pre-filled examples that conform to the schema. Default to `false`<!--/source--> |

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Other responses

`200`

`GET` `/schema/{data_object}`

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

#### Retrieve Example Schema
<!--/source-->

`retrieveSchema`

<!--source:api-specifications-->
Retrieve Schema retrieves a JSON schema for the request and the response returned by the product. It can also return an example of a json object defined with schema.

#### Testing Income:

If you want an example collection:

- To path parameter `data_object` add `request`
- In the query parameters set `return_examples` to `true`
- Based on the language version you want to use you can set the query parameter `version` to either `v0` or `v2`. The default value is `v2`

You can directly pass an example returned by the `/schema` endpoint into the Create Collection endpoint as a request body.

<!--/source-->

##### Response

<!--source:api-specifications-->
200 Example V0 Schema200 Example V2 Schema400 InvalidDataObject400 InvalidVersionValue400 MissingVersionParameter400 InvalidReturnExamplesValue403
<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully returned the list of elements needed for Income.

```
{
 "$schema": "http://json-schema.org/draft-04/schema#",
 "type": "object",
 "properties": {
 "deal_sets": {
 "type": "object",
 "properties": {
 "deal_set": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "deals": {
 "type": "object",
 "properties": {
 "deal": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "parties": {
 "type": "object",
 "properties": {
 "party": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "customer_transaction_ID": {
 "type": "string"
 },
 "individual": {
 "type": "object",
 "properties": {
 "contact_points": {
 "type": "object",
 "properties": {
 "contact_point": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "contact_point_telephone": {
 "type": "object",
 "properties": {
 "value": {
 "type": "string"
 }
 },
 "required": [
 "value"
 ]
 },
 "contact_point_email": {
 "type": "object",
 "properties": {
 "value": {
 "type": "string"
 }
 },
 "required": [
 "value"
 ]
 }
 },
 "required": [
 "contact_point_telephone",
 "contact_point_email"
 ]
 }
 }
 },
 "required": [
 "contact_point"
 ]
 },
 "name": {
 "type": "object",
 "properties": {
 "first": {
 "type": "string"
 },
 "last": {
 "type": "string"
 }
 },
 "required": [
 "first",
 "last"
 ]
 }
 },
 "required": [
 "contact_points",
 "name"
 ]
 },
 "roles": {
 "type": "object",
 "properties": {
 "role": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "borrower": {
 "type": "object",
 "properties": {
 "birth_date": {
 "type": "string"
 },
 "employers": {
 "type": "object",
 "properties": {
 "employer": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "legal_entity": {
 "type": "object",
 "properties": {
 "full_name": {
 "type": "string"
 }
 },
 "required": [
 "full_name"
 ]
 }
 },
 "required": [
 "legal_entity"
 ]
 }
 }
 },
 "required": [
 "employer"
 ]
 },
 "residences": {
 "type": "object",
 "properties": {
 "residence": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "address": {
 "type": "object",
 "properties": {
 "additional_line_text": {
 "type": "string"
 },
 "city": {
 "type": "string"
 },
 "country": {
 "type": "string"
 },
 "line_text": {
 "type": "string"
 },
 "postal_code": {
 "type": "string"
 },
 "state_code": {
 "type": "string"
 }
 },
 "required": [
 "additional_line_text",
 "city",
 "country",
 "line_text",
 "postal_code",
 "state_code"
 ]
 }
 },
 "required": [
 "address"
 ]
 }
 }
 },
 "required": [
 "residence"
 ]
 }
 },
 "required": [
 "birth_date",
 "employers",
 "residences"
 ]
 }
 },
 "required": [
 "borrower"
 ]
 }
 }
 },
 "required": [
 "role"
 ]
 },
 "taxpayer_identifiers": {
 "type": "object",
 "properties": {
 "taxpayer_identifier": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "value": {
 "type": "string"
 }
 },
 "required": [
 "value"
 ]
 }
 }
 },
 "required": [
 "taxpayer_identifier"
 ]
 }
 },
 "required": [
 "customer_transaction_ID",
 "individual",
 "roles",
 "taxpayer_identifiers"
 ]
 }
 }
 },
 "required": [
 "party"
 ]
 }
 },
 "required": [
 "parties"
 ]
 }
 }
 },
 "required": [
 "deal"
 ]
 }
 },
 "required": [
 "deals"
 ]
 }
 }
 },
 "required": [
 "deal_set"
 ]
 },
 "document_sets": {
 "type": "object",
 "properties": {
 "document_set": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "documents": {
 "type": "object",
 "properties": {
 "document": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "document_classification": {
 "type": "object",
 "properties": {
 "document_classes": {
 "type": "object",
 "properties": {
 "document_class": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "staircase_type": {
 "type": "string"
 },
 "type": {
 "type": "string"
 }
 }
 }
 }
 }
 }
 }
 },
 "foreign_objects": {
 "type": "object",
 "properties": {
 "foreign_object": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "description": {
 "type": "string"
 },
 "mime_type_identifier": {
 "type": "string"
 },
 "name": {
 "type": "string"
 },
 "staircase_blob_id": {
 "type": "string"
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 }
 },
 "required": [
 "deal_sets"
 ]
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Successfully returned the list of elements needed for Income.

```
{
 "type": "object",
 "properties": {
 "people": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "has_first_name": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_last_name": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_birth_date": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_taxpayer_identifier_value": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "with_address": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "@type": {
 "type": "string"
 },
 "has_address_line_1_text": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_address_line_2_text": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_city_name": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_state_code": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_postal_code": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_country_name": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 }
 },
 "required": [
 "@type",
 "has_address_line_1_text",
 "has_address_line_2_text",
 "has_city_name",
 "has_state_code",
 "has_postal_code",
 "has_country_name"
 ]
 }
 },
 "contact_at": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "@type": {
 "type": "string"
 },
 "has_email_address": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 },
 "has_phone_number": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 }
 },
 "required": [
 "@type",
 "has_email_address",
 "has_phone_number"
 ]
 }
 },
 "works_for": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "@type": {
 "type": "string"
 },
 "has_organization_name": {
 "type": "object",
 "properties": {
 "has_value": {
 "type": "string"
 }
 },
 "required": [
 "has_value"
 ]
 }
 },
 "required": [
 "@type",
 "has_organization_name"
 ]
 }
 }
 },
 "required": [
 "has_first_name",
 "has_last_name",
 "has_birth_date",
 "has_taxpayer_identifier_value",
 "with_address",
 "contact_at",
 "works_for"
 ]
 }
 }
 },
 "required": [
 "people"
 ]
}
```

<!--/source-->

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

```
{
 "message": "Please provide one of valid data object values: request, response"
}
```

<!--/source-->

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

```
{
 "message": "Please provide one of valid version values: v0"
}
```

<!--/source-->

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

```
{
 "message": "Please make sure your query parameters contains version parameter."
}
```

<!--/source-->

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

```
{
 "message": "Please provide one of valid return examples values: true, false"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `data_object` required | `string` path | `request` | <!--source:api-specifications-->Describes the particular data object you are getting a schema for. Can be either request or response.<!--/source--> |
| `return_examples` | `boolean` query | `false` | <!--source:api-specifications-->If included and set to `true`, returns one or more pre-filled examples that conform to the schema. Default to `false`<!--/source--> |
| `version` | `string` query | `v2` | <!--source:api-specifications-->Defines the version of the Staircase language you want the JSON to return in. Can be either v0 or v2.<!--/source--> |

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

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

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

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

##### Other responses

`200`

`GET` `/transactions/{transaction_id}/collections`

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

#### Retrieve Transaction Collections
<!--/source-->

`RetrieveTransactionCollections`

<!--source:api-specifications-->
Retrieve Transaction Collections retrieves a list of all collections associated with a transaction.

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Transaction collection retrieved successfully

```
{
 "collection_id": "01G4CSWKK6HRABWRZNM0J6BEXK",
 "data": {
 "addresses": [
 {
 "@id": "01G0F11KE743JYDTZK6JSJSZUY",
 "@type": "residential_address",
 "has_address_line_1_text": {
 "has_value": "33 IRVING PLACE"
 },
 "has_city_name": {
 "has_value": "NEW YORK"
 },
 "has_country_name": {
 "has_value": "US"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_state_code": {
 "has_value": "NY"
 }
 },
 {
 "@id": "01G4CSY8CJ30N1ZWNH3W4TEF9H",
 "@type": "business_address",
 "has_address_line_1_text": {
 "has_value": "1313 Mockingbird Lane"
 },
 "has_city_name": {
 "has_value": "Olympia"
 },
 "has_country_name": {
 "has_value": "US"
 },
 "has_postal_code": {
 "has_value": "82943-9302"
 },
 "has_state_code": {
 "has_value": "NY"
 }
 }
 ],
 "contact_information": [
 {
 "@id": "01G0F11KE743JYDTZK6JSJSYCR",
 "@type": "contact_information",
 "has_email_address": {
 "has_value": "test@test.com"
 },
 "has_phone_number": {
 "has_value": "+123456789"
 }
 }
 ],
 "documents": [
 {
 "@id": "01G4CSYSAREBF6Y4GY2MNPJBEG",
 "@type": "verification_of_income",
 "has_document_description": {
 "has_value": "Income Verification Report prepared by Staircase"
 },
 "has_document_mime_type": {
 "has_value": "application/pdf"
 },
 "has_document_name": {
 "has_value": "01G4CSYKZQKZN4PCRZHQD0XNJB.pdf"
 },
 "has_staircase_blob_identifier": {
 "has_value": "01G4CSYKZQKZN4PCRZHQD0XNJB"
 },
 "has_staircase_document_category_type": {
 "has_value": "staircase"
 }
 },
 {
 "@id": "01G0EX4VT41ZF22QWXH1QBTZPF",
 "@type": "verification_of_income",
 "has_document_description": {
 "has_value": "Income Verification Report prepared by Partner"
 },
 "has_document_mime_type": {
 "has_value": "application/pdf"
 },
 "has_document_name": {
 "has_value": "01G0EX4VT41ZF22QWXH1QBTZPF.pdf"
 },
 "has_staircase_blob_identifier": {
 "has_value": "01G0EX4VT41ZF22QWXH1QBTZPF"
 },
 "has_staircase_document_category_type": {
 "has_value": "partner"
 }
 }
 ],
 "employment": [
 {
 "@id": "01G0F11KE743JYDTZK6JSJSPOQ",
 "@type": "employment",
 "has_current_employment_indicator": {
 "has_value": true
 },
 "has_employment_monthly_income_amount": {
 "has_value": 7000
 },
 "has_employment_position_description": {
 "has_value": "HR ADMININSTRATOR"
 },
 "has_employment_start_date": {
 "has_value": "2014-01-01"
 },
 "provided_by": [
 "01G0F11KE743JYDTZK6JSJSTIY"
 ]
 }
 ],
 "income": [
 {
 "@id": "01G4CSY8CK4K120TWKECZXHGGA",
 "@type": "employment_income",
 "earned_from": [
 "01G4CSY8CJXPA8R5SFVSTEQ188"
 ],
 "has_bonus_income_amount": {
 "has_value": 0
 },
 "has_income_amount": {
 "has_value": 22615.38
 },
 "has_income_pay_frequency_type": {
 "has_value": "monthly"
 },
 "has_income_year": {
 "has_value": "2022"
 },
 "has_other_income_amount": {
 "has_value": 0
 },
 "has_overtime_income_amount": {
 "has_value": 0
 }
 },
 {
 "@id": "01G4CSY8CKKBSYGQXA5D5KY8A9",
 "@type": "employment_income",
 "earned_from": [
 "01G4CSY8CJXPA8R5SFVSTEQ188"
 ],
 "has_bonus_income_amount": {
 "has_value": 0
 },
 "has_income_amount": {
 "has_value": 84000
 },
 "has_income_pay_frequency_type": {
 "has_value": "monthly"
 },
 "has_income_year": {
 "has_value": "2021"
 },
 "has_other_income_amount": {
 "has_value": 0
 },
 "has_overtime_income_amount": {
 "has_value": 0
 }
 },
 {
 "@id": "01G4CSY8CK3RJAF6WP0XQN2JQW",
 "@type": "employment_income",
 "earned_from": [
 "01G4CSY8CJXPA8R5SFVSTEQ188"
 ],
 "has_bonus_income_amount": {
 "has_value": 0
 },
 "has_income_amount": {
 "has_value": 80000
 },
 "has_income_pay_frequency_type": {
 "has_value": "monthly"
 },
 "has_income_year": {
 "has_value": "2020"
 },
 "has_other_income_amount": {
 "has_value": 0
 },
 "has_overtime_income_amount": {
 "has_value": 0
 }
 }
 ],
 "mortgage_products": [
 {
 "@id": "01G4CSYB2B2JZW01E660FHJED5",
 "@type": "income",
 "has_partner_name": {
 "has_value": "Partner"
 },
 "has_service_response_date": {
 "has_value": "2022-05-31"
 }
 }
 ],
 "loans": [
 {
 "@id": "01G3B5DKRT27W61Y3ZK57JSGBE",
 "@type": "loan",
 "has_day_1_certainty_indicator": {
 "has_value": "123456789"
 }
 }
 ],
 "organizations": [
 {
 "@id": "01G0F11KE743JYDTZK6JSJSTIY",
 "@type": "organization",
 "has_organization_name": {
 "has_value": "Amazon"
 },
 "with_address": [
 "01G4CSY8CJ30N1ZWNH3W4TEF9H"
 ]
 }
 ],
 "people": [
 {
 "@id": "01G4CSY8CJ5X9MPA2VR5AH97YB",
 "@type": "borrower",
 "contact_at": [
 "01G0F11KE743JYDTZK6JSJSYCR"
 ],
 "earns": [
 "01G4CSY8CKKBSYGQXA5D5KY8A9",
 "01G4CSY8CK3RJAF6WP0XQN2JQW",
 "01G4CSY8CK4K120TWKECZXHGGA"
 ],
 "employed_as": [
 "01G0F11KE743JYDTZK6JSJSPOQ"
 ],
 "has_birth_date": {
 "has_value": "1973-01-01"
 },
 "has_first_name": {
 "has_value": "Happy"
 },
 "has_last_name": {
 "has_value": "Traveler"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "666991238"
 },
 "with_address": [
 "01G4CSY8CJ30N1ZWNH3W4TEF9H",
 "01G0F11KE743JYDTZK6JSJSZUY"
 ],
 "works_for": [
 "01G0F11KE743JYDTZK6JSJSTIY"
 ]
 }
 ]
 },
 "metadata": {
 "created_at": "2022-05-31T06:16:54.118103-04:00",
 "invocation_status": "COMPLETED",
 "last_updated_at": "2022-05-31T06:18:22.606643-04:00",
 "partner_language": "income-equifax-output",
 "product_name": "income",
 "report_download_urls": {
 "income_report": {
 "blob_id": "01G4CSYKZQKZN4PCRZHQD0XNJB",
 "download_url": "https://dev-data-manager-blobs-bucket-us-east-1-026452950730.s3.amazonaws.com/01G4CSYKZQKZN4PCRZHQD0XNJB.pdf?response-content-type=application%2Fpdf&AWSAccessKeyId=<redacted>&Signature=<redacted>&x-amz-security-token=<redacted>&Expires=1653995880",
 "status": "Succeeded"
 }
 },
 "service_invocation": {
 "Connector": {
 "connector_flow_name": "income",
 "debug_config": {
 "dry_run": true
 },
 "invocation_id": "1f15fe83-7b8a-4123-b645-c62e0d922612",
 "status": "COMPLETED"
 },
 "Language": {
 "input": {
 "from_language": "staircase-graph",
 "invocation_id": "01G4CSX1GYCSCHYYEZCXT1DPYQ",
 "status": "COMPLETED",
 "to_language": "income-input"
 },
 "output": {
 "from_language": "income-equifax-output",
 "invocation_id": "01G4CSY55AZ4TH9X29ZE4YQAB0",
 "status": "COMPLETED",
 "to_language": "staircase-graph"
 }
 },
 "report_mapping": {
 "invocation_id": "01G4CSYMQ5QXV05P70CB6ZH92E",
 "language_name": "income-report-mapping",
 "status": "COMPLETED"
 }
 },
 "staircase_language_version": 2,
 "validation": false,
 "version": 2
 },
 "transaction_id": "01G4CSWCBM2QE3QXTDEM4AEPBK"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Invalid key for service

```
{
 "message": "Please check the key you used to call this service",
 "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```

<!--/source-->

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

```
{
 "message": "Unable to get collections of given transaction. Please check the transaction id"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.

```
{
 "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |
| `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | <!--source:api-specifications-->Staircase Transaction Identifier<!--/source--> |

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

<!--source:api-specifications-->
5 fields
<!--/source-->
<!--source:api-specifications-->
Transaction collection retrieved successfully
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `people`required | `object[]` | <!--source:api-specifications-->Borrower - People array<!--/source--> |
| `@type`required | `string` | <!--source:api-specifications-->People type - can be borrower, co-borrower etc.<!--/source--> |
| `@id`required | `string` | <!--source:api-specifications-->People object ID<!--/source--> |
| `has_first_name`required | `object` | <!--source:api-specifications-->Borrower first name<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Borrower first name value<!--/source--> |
| `has_last_name`required | `object` | <!--source:api-specifications-->Borrower last name<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Borrower last name value<!--/source--> |
| `has_birth_date`required | `object` | <!--source:api-specifications-->Borrower birthdate<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Borrower birthdate value - (yyyy-MM-dd)<!--/source--> |
| `has_taxpayer_identifier_value`required | `object` | <!--source:api-specifications-->Borrower taxpayer identifier (SSN)<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Borrower taxpayer identifier (SSN) - (XXXXXXXXX)<!--/source--> |
| `with_address`required | `string[]` | <!--source:api-specifications-->ID referencing the address array<!--/source--> |
| `contact_at`required | `string[]` | <!--source:api-specifications-->ID referencing the contact information array<!--/source--> |
| `works_for`required | `string[]` | <!--source:api-specifications-->ID referencing the organizations array<!--/source--> |
| `addresses` | `object[]` | <!--source:api-specifications-->Borrower address array<!--/source--> |
| `@type` | `string` | <!--source:api-specifications-->Borrower address type - can be residential_address, business_address etc.<!--/source--> |
| `@id` | `string` | <!--source:api-specifications-->Borrower address object ID<!--/source--> |
| `has_address_line_1_text` | `object` | <!--source:api-specifications-->Address line text<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Address line text value<!--/source--> |
| `has_address_line_2_text` | `object` | <!--source:api-specifications-->Address line text<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Address line text value<!--/source--> |
| `has_city_name` | `object` | <!--source:api-specifications-->Address city name<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Address city name value<!--/source--> |
| `has_state_code` | `object` | <!--source:api-specifications-->Address state code<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Address state code value<!--/source--> |
| `has_postal_code` | `object` | <!--source:api-specifications-->Address postal code<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Address postal code value<!--/source--> |
| `has_country_name` | `object` | <!--source:api-specifications-->Address country name<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Address country name value<!--/source--> |
| `contact_information`required | `object[]` | <!--source:api-specifications-->Borrower - contact information array<!--/source--> |
| `@type`required | `string` | <!--source:api-specifications-->Borrower contact information type<!--/source--> |
| `@id`required | `string` | <!--source:api-specifications-->Borrower contact information ID<!--/source--> |
| `has_email_address`required | `object` | <!--source:api-specifications-->Borrower email address<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Borrower email address value<!--/source--> |
| `has_phone_number`required | `object` | <!--source:api-specifications-->Borrower phone number<!--/source--> |
| `has_value`required | `string` | <!--source:api-specifications-->Borrower phone number value<!--/source--> |
| `organizations`required | `array` | <!--source:api-specifications-->Organizations information<!--/source--> |
| `loans` | `object[]` | <!--source:api-specifications-->Loan information<!--/source--> |
| `@type` | `string` | <!--source:api-specifications-->Borrower loan information type<!--/source--> |
| `@id` | `string` | <!--source:api-specifications-->Borrower loan information ID<!--/source--> |
| `has_day_1_certainty_indicator` | `object` | <!--source:api-specifications-->Day-1 Certainty indicator<!--/source--> |
| `has_value` | `string` | <!--source:api-specifications-->Day-1 Certainty indicator value<!--/source--> |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Invalid key for service
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |

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

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

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

##### Response `500``application/json`

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |

##### Other responses

`400`

`POST` `/request-elements/complete`

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

#### Validate Collection
<!--/source-->

`post-income-collection-complete`

<!--source:api-specifications-->
Validate Collection verifies that a collection contains all the elements needed to invoke a partner for income verification.

<!--/source-->

##### Request

<!--source:api-specifications-->
Example staircase-graph (v2)Example staircase-limited (v0)
<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "data": {
 "people": [
 {
 "@type": "borrower",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8ABC",
 "has_first_name": {
 "has_value": "FirstName"
 },
 "has_last_name": {
 "has_value": "LastName"
 },
 "has_birth_date": {
 "has_value": "1993-01-11"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "111223333"
 },
 "with_address": [
 "01FD6ZNGJADZ0RB1H96FSE8BAB"
 ],
 "contact_at": [
 "01FD6ZNGJW9X96WGWX2BD37CFY"
 ],
 "works_for": [
 "01FD6ZNGNFKY3B7CX0YN6NH56E"
 ]
 }
 ],
 "addresses": [
 {
 "@type": "address",
 "@id": "01FD6ZNGJADZ0RB1H96FSE8BAB",
 "has_address_line_1_text": {
 "has_value": "33 IRVING PLACE"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "NEW YORK"
 },
 "has_state_code": {
 "has_value": "NY"
 },
 "has_postal_code": {
 "has_value": "10003"
 },
 "has_country_name": {
 "has_value": "US"
 }
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FD6ZNGJW9X96WGWX2BD37CFY",
 "has_email_address": {
 "has_value": "test@test.com"
 },
 "has_phone_number": {
 "has_value": "+123456789"
 }
 }
 ],
 "organizations": [
 {
 "@id": "01FD6ZNGNFKY3B7CX0YN6NH56E",
 "has_organization_name": {
 "has_value": "Company Name"
 }
 }
 ],
 "loans": [
 {
 "@id": "01G3B5DKRT27W61Y3ZK57JSGBE",
 "has_day_1_certainty_indicator": {
 "has_value": "123456789"
 }
 }
 ]
 }
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy
```
{
 "deal_sets": {
 "deal_set": [
 {
 "deals": {
 "deal": [
 {
 "parties": {
 "party": [
 {
 "customer_transaction_id": "6f039329-3fd6-44c1-a460-9af546e798de",
 "individual": {
 "contact_points": {
 "contact_point": [
 {
 "contact_point_telephone": {
 "value": "+1234567890"
 },
 "contact_point_email": {
 "value": "test@test.com"
 }
 }
 ]
 },
 "name": {
 "first": "John",
 "last": "Deere"
 }
 },
 "roles": {
 "role": [
 {
 "borrower": {
 "birth_date": "1993-01-01",
 "employers": {
 "employer": [
 {
 "legal_entity": {
 "full_name": "Uber"
 }
 }
 ]
 },
 "residences": {
 "residence": [
 {
 "address": {
 "additional_line_text": "None",
 "city": "NEW YORK",
 "country": "US",
 "line_text": "33 IRVING PLACE",
 "postal_code": "10003",
 "state_code": "NY"
 }
 }
 ]
 }
 }
 }
 ]
 },
 "taxpayer_identifiers": {
 "taxpayer_identifier": [
 {
 "value": "123456789"
 }
 ]
 }
 }
 ]
 }
 }
 ]
 }
 }
 ]
 }
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
application/json Copy Collection is valid

```
{
 "message": "Collection is valid."
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Staircase Documentation Environment API Key<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Collection is valid
<!--/source-->

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

##### Other responses

`400``403`

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

### Operations
<!--/source-->

`POST` `/income`

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

#### Create Income
<!--/source-->

`post-income`

<!--source:api-specifications-->
Create Income creates, for a borrower, a complete profile of the borrower's income.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "transaction_id": "uhz6t54e-9d74-g17e-99ca-a36b30vdfd35",
 "collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
 "partner_name": "PartnerName"
}
```

<!--/source-->

##### Response

<!--source:api-specifications-->
application/json Copy Income request created successfully.

```
{
 "collection_id": "e4502ed2-8df8-4b8f-84bd-a1097e999a77",
 "message": "When ready, data will be available under the following collection_id. Use this new collection_id to get the execution status."
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Authorization key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string` | <!--source:api-specifications-->Transaction ID<!--/source--> |
| `collection_id`required | `string` | <!--source:api-specifications-->Collection ID<!--/source--> |
| `partner_name`required | `string` | — |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Income request created successfully.
<!--/source-->

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

## Providers

1. Argyle
1. Atomic
1. Equifax
1. Experian
1. Finicity
1. MeridianLink
1. Pinwheel
1. Plaid
1. Truework
1. Truework

Also integrated for this product, outside the committed ordering:

- Truv

## Field mapping

| Provider | Flow | Canonical in | Vendor in | Vendor out | Canonical out |
| --- | --- | --- | --- | --- | --- |
| Argyle | `income` | `staircase-graph` | `income-input` | `income-argyle-output` | `staircase-graph` |
| Plaid | `asset` | `staircase-graph` | `asset-input` | `asset-plaid-output` | `staircase-graph` |

## Errors

`400``403``404``422``500``502`

## More in Verification

- Previous product: Identity
- Next product: Tax