<!-- https://staircase.co/products/integration/pos -->
# POS

# POS

The borrower-facing intake surface, and the integration that carries an application from it into the loan file.

The point of sale is where a borrower starts. What arrives from it is an application in the intake system's own shape, and the integration maps it into the canonical model so the verification and pricing products can run against it.

The borrower-facing flow built on top of it is the consumer application.

The operations below come from the adapter service that routes the origination system, the point of sale and the closing surface together — the three places a loan file crosses a system boundary, deliberately behind one contract.

## Operations

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

### Operations
<!--/source-->

`POST` `/pos`

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

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

`post-pos`

##### 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 POS 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-->
POS request created successfully.
<!--/source-->

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

`GET` `/pos/elements`

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

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

`get-pos-elements`

<!--source:api-specifications-->
Retrieve Elements provides a list of the elements needed to invoke a partner product.

<!--/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--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Elements needed for request.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `elements` | `object` | <!--source:api-specifications-->List of elements<!--/source--> |

`POST` `/pos/elements/complete`

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

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

`post-pos-collection-complete`

<!--source:api-specifications-->
Validate Collection validates that a collection contains all of the elements needed to invoke a partner product.

<!--/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-->
1 fields
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `collection`required | `object` | — |

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

<!--source:api-specifications-->
2 fields
<!--/source-->
<!--source:api-specifications-->
Collection is invalid.
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | <!--source:api-specifications-->Error message<!--/source--> |
| `errors` | `object` | <!--source:api-specifications-->List of elements that are missing<!--/source--> |

##### Other responses

`200`

`POST` `/pos/lexicon/elements`

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

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

<!--source:api-specifications-->
You can retrieve element structure by providing specific element names (XPaths).

<!--/source-->

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

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

| Field | Type | Description |
| --- | --- | --- |
| `elements` | `string[]` | <!--source:api-specifications-->An XPath to a valid staircase element<!--/source--> |

##### Other responses

`200`

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

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

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

`get-pos-status`

<!--source:api-specifications-->
Retrieve Status checks status of your request. Possible statuses:

- REQUEST_MADE
- REQUEST_ACCEPTED
- WAITING_FOR_RESPONSE
- COMPLETED

<!--/source-->

##### Response

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

<!--source:api-specifications-->
application/json Copy Statuses include: * REQUEST_MADE<p> * REQUEST_ACCEPTED<p> * WAITING_FOR_RESPONSE<p> * COMPLETED

```
{
 "status": "COMPLETED"
}
```

<!--/source-->

<!--source:api-specifications-->
application/json Copy Status is unavailable

```
{
 "error": "Request for specified transaction_id and collection_id was not found!"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string` path | `9u8z7t65-cb71-4f20-8e40-7a829b52e91e` | <!--source:api-specifications-->Transaction ID<!--/source--> |
| `collection_id` required | `string` path | `e4502ed2-8df8-4b8f-84bd-a1097e999a77` | <!--source:api-specifications-->Collection ID<!--/source--> |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Authorization key<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Statuses include: * REQUEST_MADE<p> * REQUEST_ACCEPTED<p> * WAITING_FOR_RESPONSE<p> * COMPLETED
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `status` | `object` | <!--source:api-specifications-->Current execution status<!--/source--> |

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

<!--source:api-specifications-->
1 fields
<!--/source-->
<!--source:api-specifications-->
Status is unavailable
<!--/source-->

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

`POST` `/pos/transactions`

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

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

`post-pos-transaction`

<!--source:api-specifications-->
Create Transaction creates a transaction in Staircase. A transaction in Staircase is an acknowledgement that you want to call a Staircase product. It's a container for everything associated with that product invocation, and is correlated with a collection related to the product (e.g. a document). You need to create a new transaction every time you want to connect with a Staircase product. Staircase then associates everything, from a data and API execution standpoint, to that transaction.

<!--/source-->

##### Response

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

```
{
 "transaction_id": "a34c40a6-3c02-44f9-a696-cd7388f506d3"
}
```

<!--/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--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | <!--source:api-specifications-->Transaction ID<!--/source--> |

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

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

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

`post-pos-collection`

<!--source:api-specifications-->
Create Collection creates a collection of elements . The elements within the collection are required.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "sets": {
 "set": [
 {
 "elements": {
 "element": [
 {
 "property_entry": {
 "property_entries": {
 "datetime": "2020-08-25",
 "description": "Description of property",
 "event_type": "TestType"
 }
 },
 "property_class": {
 "property_clases": {
 "type": "STATEMENT"
 },
 "name": "Test",
 "period_start_date": "2020-07-01",
 "period_end_date": "2020-07-31"
 },
 "content": {
 "foreign_object": "7e62ce76-d93d-4f31-92d3-45c2cb8255ea"
 }
 }
 ]
 }
 }
 ]
 }
}
```

<!--/source-->

##### Response

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

```
{
 "collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
 "data": {
 "sets": {
 "set": [
 {
 "elements": {
 "element": [
 {
 "property_entry": {
 "property_entries": {
 "datetime": "2020-08-25",
 "description": "Description of property",
 "event_type": "TestType"
 }
 },
 "property_class": {
 "property_clases": {
 "type": "STATEMENT"
 },
 "name": "Test",
 "period_start_date": "2020-07-01",
 "period_end_date": "2020-07-31"
 },
 "content": {
 "foreign_object": "7e62ce76-d93d-4f31-92d3-45c2cb8255ea"
 }
 }
 ]
 }
 }
 ]
 }
 },
 "metadata": {},
 "transaction_id": "6t5r4wq1-9d74-g17e-99ca-a36b30vdfd35"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string` path | `3wet53r4-cb71-8u74-8e40-7a829b52e91e` | <!--source:api-specifications-->Transaction ID<!--/source--> |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->Authorization key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `data`required | `object` | — |
| `metadata` | `object` | — |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `object` | <!--source:api-specifications-->Transaction ID<!--/source--> |
| `collection_id` | `object` | <!--source:api-specifications-->Collection ID<!--/source--> |
| `data` | `object` | <!--source:api-specifications-->Data object<!--/source--> |
| `metadata` | `object` | <!--source:api-specifications-->Metadata object<!--/source--> |

`PUT` `/pos/transactions/{transaction_id}/collections/{collection_id}`

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

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

`put-pos-collection`

<!--source:api-specifications-->
Update Collection updates a collection of elements by new elements.

<!--/source-->

##### Request

<!--source:api-specifications-->
application/json Copy
```
{
 "sets": {
 "set": [
 {
 "properties": {
 "property": [
 {
 "propety_entry": {
 "propety_entries": {
 "datetime": "2020-05-05",
 "description": "Test Description",
 "event_type": "TestType"
 }
 },
 "propety_class": {
 "propety_classes": {
 "type": "TestType"
 },
 "name": "TestName",
 "period_start_date": "2019-01-01",
 "period_end_date": "2019-12-31"
 },
 "content": {
 "foreign_object": "7z6t5r4e-d93d-4f31-92d3-45c2cb8255ea"
 }
 }
 ]
 }
 }
 ]
 }
}
```

<!--/source-->

##### Response

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

```
{
 "collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
 "data": {
 "sets": {
 "set": [
 {
 "properties": {
 "property": [
 {
 "property_data": {
 "property_class": {
 "datetime": "2020-05-05",
 "description": "Info",
 "event_type": "TestEvent"
 }
 },
 "document_classification": {
 "document_classes": {
 "type": "TestType"
 },
 "name": "TestName",
 "period_start_date": "2019-01-01",
 "period_end_date": "2019-12-31"
 },
 "content": {
 "foreign_object": "7z6t5r4e-d93d-4f31-92d3-45c2cb8255ea"
 }
 }
 ]
 }
 }
 ]
 }
 },
 "metadata": {},
 "transaction_id": "6t5r4wq1-9d74-g17e-99ca-a36b30vdfd35"
}
```

<!--/source-->

##### Parameters

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

| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string` path | `3wet53r4-cb71-8u74-8e40-7a829b52e91e` | <!--source:api-specifications-->Transaction ID<!--/source--> |
| `collection_id` required | `string` path | `9u8z7t65-cb71-8u74-8e40-7a829b52e91e` | <!--source:api-specifications-->Transaction ID<!--/source--> |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | <!--source:api-specifications-->API Key<!--/source--> |

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

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

| Field | Type | Description |
| --- | --- | --- |
| `data`required | `object` | — |
| `metadata` | `object` | — |

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

<!--source:api-specifications-->
4 fields
<!--/source-->
<!--source:api-specifications-->
Collection successfully updated
<!--/source-->

| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `object` | <!--source:api-specifications-->Transaction ID<!--/source--> |
| `collection_id` | `object` | <!--source:api-specifications-->Collection ID<!--/source--> |
| `data` | `object` | <!--source:api-specifications-->Data object<!--/source--> |
| `metadata` | `object` | <!--source:api-specifications-->Metadata object<!--/source--> |

## Errors

`400`

## More in Integration

- Previous product: LOS
- Next product: Servicing