Suggested Actions

A suggested action isn't carried out immediately — it's a suggestion your organization creates for a customer to review and explicitly approve before it takes effect. In the API, this object is called an intent — you'll see it as the /intents endpoints, and as a specific type value such as paymentIntent (just one example of a supported suggestion type) throughout this reference. Use it whenever your org wants to propose something for a customer — the customer stays in control: they can approve the suggestion as-is, edit some of the details before approving, or decline it outright. Your organization gets a clear view of each suggestion's status through a set of APIs and webhook events, so you can reflect that status in your product.

Overview page with suggested actions surfaced to the customer

How it works

Your organization creates a suggested action, using your org API token. It sits in Created status, waiting on the customer to take action (approve/decline it).
The customer reviews the suggestion, using their own session token, and either:
- Approves — Approving is what triggers execution. Optionally, the customer edits some of the details needed to complete it (editable fields are action-dependent).
- Declines — Rejecting a suggestion is final.
Cancel — your organization can cancel the action at any point while it's still in Created status.
Once approved, Unit moves the action through Processing to Completed automatically as it executes. If it fails, the action moves to Failed and can be approved again to retry.

Lifecycle

Created --(customer approves)--> Approved → Processing → Completed
Created --(customer declines)--> Declined                               (terminal)
Created --(org cancels)--------> Cancelled                              (terminal)
Created --(60 days pass)-------> Expired                                (terminal)

Processing, Completed, and Failed are reached automatically once the underlying action executes — there's no endpoint to set them directly; they're a side effect of the customer approving it.

Expiry

A suggestion that has not been acted on automatically moves to Expired after 60 days in Created status. Expiry is terminal — the customer can no longer approve or decline the suggestion, and your organization can no longer cancel it. Create a new suggestion if the action is still needed.

Decline vs. Cancel

Both end the flow from Created, but from different sides. Decline is triggered by the customer — they've reviewed the org's suggestion and rejected it. Cancel is triggered by your organization — you're withdrawing a suggestion, typically before the customer has acted on it.

Supported Suggestion Types

Every suggestion — regardless of type — is created and approved through the type-specific endpoints below, and fetched, listed, declined, or cancelled through the generic endpoints at the bottom of this page. What changes per type is the type value in the JSON:API body and the attributes it accepts and returns. Today, Managed Banking supports one suggestion type, with more on the way:

Suggested Account Creation Coming Soon

A suggestion for your organization to propose opening a new account on the customer's behalf, which the customer reviews and approves before it's created. Not yet available — endpoints and attributes will be documented here once it ships.

Suggested Split Income Rule Coming Soon

A suggestion for your organization to propose automatically splitting incoming funds, which the customer reviews and approves before it takes effect. Not yet available — endpoints and attributes will be documented here once it ships.

Suggested Payment

Suggested payment is not a payment, it is a suggested payment request. Customers must review and approve before submitting. When your organization wants to propose a payment (rent, a bill, a scheduled transfer, etc.) without directly moving the customer's money, the customer stays in control: they can approve the suggestion as-is, edit some of the payment details before approving, or decline it outright. The organization will have a clear view of the payment status through a set of APIs allowing you to update data displayed in your product.

A suggested payment (type: paymentIntent) is created with an amount, a counterparty, and either a customer or account. When the customer approves it, they can edit the payment type and the counterparty's routing/account numbers — but not the title, description, or amount, which are set by your organization at creation.

Suggested payment review screen, as customers see it in the Managed Solution component

Create Payment Suggestion

Called by your organization (org API token), as a suggestion the customer must approve. Create a new payment suggestion - a payment suggestion that must be explicitly approved by the customer before it is submitted to a payment rail. Exactly one of customer or account must be provided.

Verb	`POST`
URL	`https://api.s.unit.sh/intents`
Required Scope	`intents-write`
Data Type	`paymentIntent`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
title Required	string	A short title for the suggestion (maximum of 20 characters).
description Required	string	A description of the suggestion (maximum of 60 characters).
amount Required	integer	The amount (in cents). Must be a positive number.
counterparty.name Required	string	The name of the counterparty (maximum of 50 characters).
counterparty.routingNumber Optional	string	The counterparty's routing number.
counterparty.accountNumber Optional	string	The counterparty's account number.
paymentType Optional	string	The type of payment. Currently only `Ach` is supported.
tags Optional	object	See Tags.
idempotencyKey Optional	string	See Idempotency.

Relationships

Name	Type	Description
customer	Optional, JSON:API Relationship	The Customer the payment is being suggested to. Required if `account` is not provided.
account	Optional, JSON:API Relationship	The Deposit Account the payment is being suggested for. Required if `customer` is not provided.

Note

Exactly one of customer or account must be provided — providing both or neither returns a 400 error.

Example Request:

curl -X POST 'https://api.s.unit.sh/intents' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer ${TOKEN}' \
  --data-raw '{
    "data": {
        "type": "paymentIntent",
        "attributes": {
            "title": "Monthly rent",
            "description": "Rent for October",
            "amount": 100000,
            "counterparty": {
                "name": "Landlord LLC",
                "routingNumber": "021000021",
                "accountNumber": "123456789"
            },
            "tags": {
                "invoiceNumber": "INV-0001"
            },
            "idempotencyKey": "unique-idempotency-key"
        },
        "relationships": {
            "customer": {
                "data": {
                    "type": "customer",
                    "id": "10014"
                }
            }
        }
    }
}'

Response

Returns the created payment suggestion, in Created status.

Response is a JSON:API document.

201 Created

Name	Type	Description
id	string	Identifier of the payment suggestion resource.
type	string	Type of the payment suggestion resource. The value is always `paymentIntent`.
attributes	JSON Object	JSON object representing the payment suggestion data.
relationships	JSON:API Relationships	Describes relationships between the payment suggestion resource and other resources.

Attributes

Name	Type	Description
title	string	The title of the suggestion.
description	string	The description of the suggestion.
amount	integer	The amount (cents) of the suggestion.
counterparty.name	string	The name of the counterparty.
counterparty.routingNumberLast4 Optional	string	Last 4 digits of the counterparty's routing number.
counterparty.accountNumberLast4 Optional	string	Last 4 digits of the counterparty's account number.
paymentType Optional	string	The type of payment.
status	string	The status of the suggestion. Always `Created` in this response.
tags Optional	object	See Tags.
createdAt	string	The date the suggestion was created.
updatedAt	string	The date the suggestion was last updated.

Counterparty account details

Create is called with an org API token. To avoid exposing sensitive bank details, the response omits counterparty.routingNumber and counterparty.accountNumber and returns counterparty.routingNumberLast4 and counterparty.accountNumberLast4 instead (when those numbers are set). A customer fetching the same suggestion with their session token receives the full routing and account numbers.

Relationships

Name	Type	Description
org	JSON:API Relationship	The organization the suggestion belongs to.
customer	JSON:API Relationship	The Customer the suggestion belongs to. Present when the suggestion is tied to a customer.
account	JSON:API Relationship	The Deposit Account associated with the suggestion. Present once the account is known.

Example Response:

{
	"data": {
		"type": "paymentIntent",
		"id": "50001",
		"attributes": {
			"title": "Monthly rent",
			"description": "Rent for October",
			"amount": 100000,
			"counterparty": {
				"name": "Landlord LLC",
				"routingNumberLast4": "0021",
				"accountNumberLast4": "6789"
			},
			"status": "Created",
			"tags": {
				"invoiceNumber": "INV-0001"
			},
			"createdAt": "2023-10-20T10:15:22.123Z",
			"updatedAt": "2023-10-20T10:15:22.123Z"
		},
		"relationships": {
			"org": {
				"data": {
					"type": "org",
					"id": "1"
				}
			},
			"customer": {
				"data": {
					"type": "customer",
					"id": "10014"
				}
			}
		}
	}
}

Create Payment Suggestion (existing counterparty)

Called by your organization (org API token), as a suggestion the customer must approve. First fetch counterparties with GET https://api.s.unit.sh/ready-to-launch/counterparties — you can filter by filter[customerId] or filter[userId] — then pass the chosen counterparty id in this request.

Verb	`POST`
URL	`https://api.s.unit.sh/intents`
Required Scope	`intents-write`
Data Type	`paymentIntent`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
title Required	string	A short title for the suggestion (maximum of 20 characters).
description Required	string	A description of the suggestion (maximum of 60 characters).
amount Required	integer	The amount (in cents). Must be a positive number.
paymentType Optional	string	The type of payment. Currently only `Ach` is supported.
tags Optional	object	See Tags.
idempotencyKey Optional	string	See Idempotency.

Relationships

Name	Type	Description
customer	Optional, JSON:API Relationship	The Customer the payment is being suggested to. Required if `account` is not provided.
account	Optional, JSON:API Relationship	The Deposit Account the payment is being suggested for. Required if `customer` is not provided.
counterparty Required	JSON:API Relationship	The existing counterparty the payment is being suggested to. Use an id returned by `GET https://api.s.unit.sh/ready-to-launch/counterparties`.

Example Request:

curl -X POST 'https://api.s.unit.sh/intents' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer ${TOKEN}' \
  --data-raw '{
    "data": {
        "type": "paymentIntent",
        "attributes": {
            "title": "Monthly rent",
            "description": "Rent for October",
            "amount": 100000,
            "tags": {
                "invoiceNumber": "INV-0001"
            },
            "idempotencyKey": "unique-idempotency-key"
        },
        "relationships": {
            "customer": {
                "data": {
                    "type": "customer",
                    "id": "10014"
                }
            },
            "counterparty": {
                "data": {
                    "type": "counterparty",
                    "id": "4567"
                }
            }
        }
    }
}'

Response

Returns the created payment suggestion, in Created status.

Response is a JSON:API document.

201 Created

Name	Type	Description
id	string	Identifier of the payment suggestion resource.
type	string	Type of the payment suggestion resource. The value is always `paymentIntent`.
attributes	JSON Object	JSON object representing the payment suggestion data.
relationships	JSON:API Relationships	Describes relationships between the payment suggestion resource and other resources.

Attributes

Name	Type	Description
title	string	The title of the suggestion.
description	string	The description of the suggestion.
amount	integer	The amount (cents) of the suggestion.
paymentType Optional	string	The type of payment.
status	string	The status of the suggestion. Always `Created` in this response.
tags Optional	object	See Tags.
createdAt	string	The date the suggestion was created.
updatedAt	string	The date the suggestion was last updated.

Relationships

Name	Type	Description
org	JSON:API Relationship	The organization the suggestion belongs to.
customer	JSON:API Relationship	The Customer the suggestion belongs to. Present when the suggestion is tied to a customer.
account	JSON:API Relationship	The Deposit Account associated with the suggestion. Present once the account is known.
counterparty	JSON:API Relationship	The existing counterparty the payment is being suggested to.

Example Response:

{
	"data": {
		"type": "paymentIntent",
		"id": "50002",
		"attributes": {
			"title": "Monthly rent",
			"description": "Rent for October",
			"amount": 100000,
			"status": "Created",
			"tags": {
				"invoiceNumber": "INV-0001"
			},
			"createdAt": "2023-10-20T10:15:22.123Z",
			"updatedAt": "2023-10-20T10:15:22.123Z"
		},
		"relationships": {
			"org": {
				"data": {
					"type": "org",
					"id": "1"
				}
			},
			"customer": {
				"data": {
					"type": "customer",
					"id": "10014"
				}
			},
			"counterparty": {
				"data": {
					"type": "counterparty",
					"id": "4567"
				}
			}
		}
	}
}

Approve Payment Suggestion

Called by the customer, using their own session token, to accept a suggested payment — the customer can edit the payment type and counterparty's bank details here, but not the title, description, or amount set by the org. Only allowed while the suggestion is in Created status.

Verb	`POST`
URL	`https://api.s.unit.sh/intents/:intentId/approve`
Required Scope	`intents-write`
Data Type	`paymentIntent`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
account Required	string	The ID of the Deposit Account the customer wants to pay from.
paymentType Optional	string	Overrides the payment type set at creation. Currently only `Ach` is supported — approving with any other value returns a `400` error.
counterparty.routingNumber Optional	string	Overrides the counterparty's routing number set at creation.
counterparty.accountNumber Optional	string	Overrides the counterparty's account number set at creation.
idempotencyKey Optional	string	See Idempotency.

Note

For Ach payment suggestions, counterparty.routingNumber and counterparty.accountNumber must be resolvable — either set by the org at creation or supplied by the customer here — otherwise the request fails with a 400 error.

Example Request:

curl -X POST 'https://api.s.unit.sh/intents/50001/approve' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer ${TOKEN}' \
  --data-raw '{
    "data": {
        "type": "paymentIntent",
        "attributes": {
            "account": "10004",
            "paymentType": "Ach",
            "counterparty": {
                "routingNumber": "021000021",
                "accountNumber": "123456789"
            },
            "idempotencyKey": "unique-idempotency-key"
        }
    }
}'

Response

Returns the payment suggestion.

Response is a JSON:API document.

200 OK

Name	Type	Description
id	string	Identifier of the payment suggestion resource.
type	string	Type of the payment suggestion resource. The value is always `paymentIntent`.
attributes	JSON Object	JSON object representing the payment suggestion data.
relationships	JSON:API Relationships	Describes relationships between the payment suggestion resource and other resources.

Attributes

Name	Type	Description
title	string	The title of the suggestion.
description	string	The description of the suggestion.
amount	integer	The amount (cents) of the suggestion.
counterparty.name	string	The name of the counterparty.
counterparty.routingNumber	string	The counterparty's routing number.
counterparty.accountNumber	string	The counterparty's account number.
paymentType	string	The type of payment.
status	string	The status of the suggestion.
approvedAt	string	The date the customer approved the suggestion.
failureReason Optional	string	Present only when status is `Failed`.
tags Optional	object	See Tags.
createdAt	string	The date the suggestion was created.
updatedAt	string	The date the suggestion was last updated.

Relationships

Name	Type	Description
org	JSON:API Relationship	The organization the suggestion belongs to.
customer	JSON:API Relationship	The Customer the suggestion belongs to. Present when the suggestion is tied to a customer.
account	JSON:API Relationship	The Deposit Account the payment will be made from.
payment	JSON:API Relationship	The Payment created as a result of approving this suggestion. Present once the underlying payment has been created.

Example Response:

{
	"data": {
		"type": "paymentIntent",
		"id": "50001",
		"attributes": {
			"title": "Monthly rent",
			"description": "Rent for October",
			"amount": 100000,
			"counterparty": {
				"name": "Landlord LLC",
				"routingNumber": "021000021",
				"accountNumber": "123456789"
			},
			"paymentType": "Ach",
			"status": "Completed",
			"approvedAt": "2023-10-20T11:02:47.552Z",
			"tags": {},
			"createdAt": "2023-10-20T10:15:22.123Z",
			"updatedAt": "2023-10-20T11:02:47.552Z"
		},
		"relationships": {
			"org": {
				"data": {
					"type": "org",
					"id": "1"
				}
			},
			"customer": {
				"data": {
					"type": "customer",
					"id": "10014"
				}
			},
			"account": {
				"data": {
					"type": "account",
					"id": "10004"
				}
			},
			"payment": {
				"data": {
					"type": "payment",
					"id": "20001"
				}
			}
		}
	}
}

Approve Payment Suggestion (existing counterparty)

Called by the customer, using their own session token, to accept a suggested payment that references an existing counterparty. The customer can edit the payment type and which counterparty to pay, but not the title, description, or amount set by the org. Only allowed while the suggestion is in Created status.

Verb	`POST`
URL	`https://api.s.unit.sh/intents/:intentId/approve`
Required Scope	`intents-write`
Data Type	`paymentIntent`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
account Required	string	The ID of the Deposit Account the customer wants to pay from.
paymentType Optional	string	Overrides the payment type set at creation. Currently only `Ach` is supported — approving with any other value returns a `400` error.
idempotencyKey Optional	string	See Idempotency.

Relationships

Name	Type	Description
counterparty Optional	Optional, JSON:API Relationship	Overrides the existing Counterparty set at creation.

Note

For Ach payment suggestions, the existing counterparty must include routingNumber and accountNumber — otherwise the request fails with a 400 error.

Example Request:

curl -X POST 'https://api.s.unit.sh/intents/50002/approve' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer ${TOKEN}' \
  --data-raw '{
    "data": {
        "type": "paymentIntent",
        "attributes": {
            "account": "10004",
            "paymentType": "Ach",
            "idempotencyKey": "unique-idempotency-key"
        },
        "relationships": {
            "counterparty": {
                "data": {
                    "type": "counterparty",
                    "id": "4567"
                }
            }
        }
    }
}'

Response

Returns the payment suggestion.

Response is a JSON:API document.

200 OK

Name	Type	Description
id	string	Identifier of the payment suggestion resource.
type	string	Type of the payment suggestion resource. The value is always `paymentIntent`.
attributes	JSON Object	JSON object representing the payment suggestion data.
relationships	JSON:API Relationships	Describes relationships between the payment suggestion resource and other resources.

Attributes

Name	Type	Description
title	string	The title of the suggestion.
description	string	The description of the suggestion.
amount	integer	The amount (cents) of the suggestion.
counterparty.name	string	The name of the counterparty.
counterparty.routingNumber	string	The counterparty's routing number.
counterparty.accountNumber	string	The counterparty's account number.
paymentType	string	The type of payment.
status	string	The status of the suggestion.
approvedAt	string	The date the customer approved the suggestion.
failureReason Optional	string	Present only when status is `Failed`.
tags Optional	object	See Tags.
createdAt	string	The date the suggestion was created.
updatedAt	string	The date the suggestion was last updated.

Relationships

Name	Type	Description
org	JSON:API Relationship	The organization the suggestion belongs to.
customer	JSON:API Relationship	The Customer the suggestion belongs to. Present when the suggestion is tied to a customer.
account	JSON:API Relationship	The Deposit Account the payment will be made from.
counterparty	JSON:API Relationship	The existing Counterparty the payment will be made to.
payment	JSON:API Relationship	The Payment created as a result of approving this suggestion. Present once the underlying payment has been created.

Example Response:

{
	"data": {
		"type": "paymentIntent",
		"id": "50002",
		"attributes": {
			"title": "Monthly rent",
			"description": "Rent for October",
			"amount": 100000,
			"counterparty": {
				"name": "Landlord LLC",
				"routingNumber": "021000021",
				"accountNumber": "123456789"
			},
			"paymentType": "Ach",
			"status": "Completed",
			"approvedAt": "2023-10-20T11:02:47.552Z",
			"tags": {},
			"createdAt": "2023-10-20T10:15:22.123Z",
			"updatedAt": "2023-10-20T11:02:47.552Z"
		},
		"relationships": {
			"org": {
				"data": {
					"type": "org",
					"id": "1"
				}
			},
			"customer": {
				"data": {
					"type": "customer",
					"id": "10014"
				}
			},
			"account": {
				"data": {
					"type": "account",
					"id": "10004"
				}
			},
			"counterparty": {
				"data": {
					"type": "counterparty",
					"id": "4567"
				}
			},
			"payment": {
				"data": {
					"type": "payment",
					"id": "20002"
				}
			}
		}
	}
}

Generic Suggested Actions

Unlike Create and Approve above, getting, listing, declining, and cancelling a suggestion don't depend on the suggestion's type — they work the same way, through the same four endpoints, no matter which suggestion type is involved. Decline and Cancel request bodies use data.type of intent — not the suggestion's type (such as paymentIntent).

Get Suggestion

Get a specific suggestion by its ID. Can be called with either your org API token or the customer's own session token.

Verb	`GET`
URL	`https://api.s.unit.sh/intents/:intentId`
Required Scope	`intents`
Timeout (Seconds)	`5`

Example Request:

curl -X GET 'https://api.s.unit.sh/intents/50001' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns the suggestion details.

Response is a JSON:API document.

200 OK

Name	Type	Description
id	string	Identifier of the suggestion resource.
type	string	Type of the suggestion resource — one of the supported suggestion types, e.g. `paymentIntent`.
attributes	JSON Object	JSON object representing the suggestion's data. Which fields are present depends on `type` — see note below.
relationships	JSON:API Relationships	Describes relationships between the suggestion resource and other resources.

Attributes depend on suggestion type

title, description, status, approvedAt, declinedAt, failureReason, tags, createdAt, and updatedAt are present on every suggestion type. The remaining attributes below (amount, counterparty, paymentType) reflect paymentIntent, the only type available today — see Supported Suggestion Types for other types' attributes once they're available.

Fields can differ by caller

Some fields may change when you fetch a suggestion with an org API token versus a customer session token, to avoid exposing sensitive details. See Create Payment Suggestion for how counterparty account details are returned.

Attributes

Name	Type	Description
title	string	The title of the suggestion.
description	string	The description of the suggestion.
amount	integer	The amount (cents) of the suggestion.
counterparty.name	string	The name of the counterparty.
counterparty.routingNumber Optional	string	The counterparty's routing number. Present when called with a customer session token.
counterparty.accountNumber Optional	string	The counterparty's account number. Present when called with a customer session token.
counterparty.routingNumberLast4 Optional	string	Last 4 digits of the counterparty's routing number. Present when called with an org API token, if a routing number is set.
counterparty.accountNumberLast4 Optional	string	Last 4 digits of the counterparty's account number. Present when called with an org API token, if an account number is set.
paymentType Optional	string	The type of payment.
status	string	The status of the suggestion. One of `Created`, `Approved`, `Declined`, `Cancelled`, `Processing`, `Completed`, `Failed`, `Expired`.
approvedAt Optional	string	The date the suggestion was approved. Present once status is `Approved` or later.
declinedAt Optional	string	The date the suggestion was declined. Present only when status is `Declined`.
failureReason Optional	string	Present only when status is `Failed`.
tags Optional	object	See Tags.
createdAt	string	The date the suggestion was created.
updatedAt	string	The date the suggestion was last updated.

The example below is an org API token response.

Relationships

Name	Type	Description
org	JSON:API Relationship	The organization the suggestion belongs to.
customer	JSON:API Relationship	The Customer the suggestion belongs to. Present when the suggestion is tied to a customer.
account	JSON:API Relationship	The Deposit Account associated with the suggestion. Present once the account is known.
payment	JSON:API Relationship	The Payment created once the suggestion completes. Absent until then.

Example Response:

{
	"data": {
		"type": "paymentIntent",
		"id": "50001",
		"attributes": {
			"title": "Monthly rent",
			"description": "Rent for October",
			"amount": 100000,
			"counterparty": {
				"name": "Landlord LLC",
				"routingNumberLast4": "0021",
				"accountNumberLast4": "6789"
			},
			"status": "Created",
			"tags": {},
			"createdAt": "2023-10-20T10:15:22.123Z",
			"updatedAt": "2023-10-20T10:15:22.123Z"
		},
		"relationships": {
			"org": {
				"data": {
					"type": "org",
					"id": "1"
				}
			},
			"customer": {
				"data": {
					"type": "customer",
					"id": "10014"
				}
			}
		}
	}
}

List Suggestions

List suggestions, with optional filtering and pagination. Can be called with either your org API token or the customer's own session token. Some fields may differ by caller — see Get Suggestion.

Verb	`GET`
URL	`https://api.s.unit.sh/intents`
Required Scope	`intents`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
filter[customerId]	string	(empty)	Optional. Filter suggestions by customer ID.
filter[status][]	string	(empty)	Optional. Filter by one or more statuses: `Created`, `Approved`, `Declined`, `Cancelled`, `Processing`, `Completed`, `Failed`, `Expired`. Usage example: filter[status][0]=Created&filter[status][1]=Approved.
sort	string	-createdAt	Optional. One of `createdAt`, `updatedAt`, `approvedAt`, `declinedAt`, `status` (ascending), or the same values prefixed with `-` for descending.
page[limit]	integer	100	Optional. Maximum number of resources to return.
page[offset]	integer	0	Optional. Number of resources to skip.

Example Request:

curl -X GET 'https://api.s.unit.sh/intents?filter[customerId]=10014&filter[status][]=Created' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns a paginated list of suggestions with their details.

Response is a JSON:API document.

200 OK

Name	Type	Description
data	Array of suggestions	Array of suggestion resources. Each item's `type` and `attributes` follow the same per-type rules as Get Suggestion.

Example Response:

{
	"data": [
		{
			"type": "paymentIntent",
			"id": "50001",
			"attributes": {
				"title": "Monthly rent",
				"description": "Rent for October",
				"amount": 100000,
				"counterparty": {
					"name": "Landlord LLC",
					"routingNumberLast4": "0021",
					"accountNumberLast4": "6789"
				},
				"status": "Created",
				"tags": {},
				"createdAt": "2023-10-20T10:15:22.123Z",
				"updatedAt": "2023-10-20T10:15:22.123Z"
			},
			"relationships": {
				"org": {
					"data": {
						"type": "org",
						"id": "1"
					}
				},
				"customer": {
					"data": {
						"type": "customer",
						"id": "10014"
					}
				}
			}
		}
	],
	"meta": {
		"pagination": {
			"total": 1,
			"limit": 100,
			"offset": 0
		}
	}
}

Decline Suggestion

Called by the customer, using their own session token, to reject a suggested action. Works the same way for every suggestion type. Only allowed while the suggestion is in Created status; declining is terminal. To have your organization withdraw a suggestion instead, use Cancel Suggestion.

Verb	`POST`
URL	`https://api.s.unit.sh/intents/:intentId/decline`
Required Scope	`intents-write`
Data Type	`intent`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Optional	string	See Idempotency.

Example Request:

curl -X POST 'https://api.s.unit.sh/intents/50001/decline' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer ${TOKEN}' \
  --data-raw '{
    "data": {
        "type": "intent",
        "attributes": {
            "idempotencyKey": "unique-idempotency-key"
        }
    }
}'

Note

Decline is a generic endpoint. The request's data.type must be intent, regardless of the suggestion's type (for example paymentIntent).

Response

Returns the declined suggestion, with status Declined and declinedAt set.

Response is a JSON:API document.

200 OK

Name	Type	Description
id	string	Identifier of the suggestion resource.
type	string	Type of the suggestion resource — one of the supported suggestion types, e.g. `paymentIntent`.
attributes	JSON Object	JSON object representing the suggestion's data. Which fields are present depends on `type` — see note below.
relationships	JSON:API Relationships	Describes relationships between the suggestion resource and other resources.

Attributes depend on suggestion type

title, description, status, declinedAt, tags, createdAt, and updatedAt are present on every suggestion type. The remaining attributes below (amount, counterparty) reflect paymentIntent, the only type available today — see Supported Suggestion Types for other types' attributes once they're available.

Attributes

Name	Type	Description
title	string	The title of the suggestion.
description	string	The description of the suggestion.
amount	integer	The amount (cents) of the suggestion.
counterparty.name	string	The name of the counterparty.
counterparty.routingNumber	string	The counterparty's routing number.
counterparty.accountNumber	string	The counterparty's account number.
status	string	The status of the suggestion. Always `Declined` in this response.
declinedAt	string	The date the customer declined the suggestion.
tags Optional	object	See Tags.
createdAt	string	The date the suggestion was created.
updatedAt	string	The date the suggestion was last updated.

Relationships

Name	Type	Description
org	JSON:API Relationship	The organization the suggestion belongs to.
customer	JSON:API Relationship	The Customer the suggestion belongs to. Present when the suggestion is tied to a customer.
account	JSON:API Relationship	The Deposit Account associated with the suggestion. Present once the account is known.

Example Response:

{
	"data": {
		"type": "paymentIntent",
		"id": "50001",
		"attributes": {
			"title": "Monthly rent",
			"description": "Rent for October",
			"amount": 100000,
			"counterparty": {
				"name": "Landlord LLC",
				"routingNumber": "021000021",
				"accountNumber": "123456789"
			},
			"status": "Declined",
			"declinedAt": "2023-10-20T11:02:47.552Z",
			"tags": {},
			"createdAt": "2023-10-20T10:15:22.123Z",
			"updatedAt": "2023-10-20T11:02:47.552Z"
		},
		"relationships": {
			"org": {
				"data": {
					"type": "org",
					"id": "1"
				}
			},
			"customer": {
				"data": {
					"type": "customer",
					"id": "10014"
				}
			}
		}
	}
}

Cancel Suggestion

Called by your organization, using your org API token, to withdraw a suggested action before the customer has acted on it. Works the same way for every suggestion type. Only allowed while the suggestion is in Created status; cancelling is terminal. To let the customer reject the suggestion themselves, see Decline Suggestion.

Verb	`POST`
URL	`https://api.s.unit.sh/intents/:intentId/cancel`
Required Scope	`intents-write`
Data Type	`intent`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Optional	string	See Idempotency.

Example Request:

curl -X POST 'https://api.s.unit.sh/intents/50001/cancel' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer ${TOKEN}' \
  --data-raw '{
    "data": {
        "type": "intent",
        "attributes": {
            "idempotencyKey": "unique-idempotency-key"
        }
    }
}'

Note

Cancel is a generic endpoint. The request's data.type must be intent, regardless of the suggestion's type (for example paymentIntent).

Response

Returns the cancelled suggestion, with status Cancelled.

Response is a JSON:API document.

200 OK

Name	Type	Description
id	string	Identifier of the suggestion resource.
type	string	Type of the suggestion resource — one of the supported suggestion types, e.g. `paymentIntent`.
attributes	JSON Object	JSON object representing the suggestion's data. Which fields are present depends on `type` — see note below.
relationships	JSON:API Relationships	Describes relationships between the suggestion resource and other resources.

Attributes depend on suggestion type

title, description, status, tags, createdAt, and updatedAt are present on every suggestion type. The remaining attributes below (amount, counterparty) reflect paymentIntent, the only type available today — see Supported Suggestion Types for other types' attributes once they're available.

Attributes

Name	Type	Description
title	string	The title of the suggestion.
description	string	The description of the suggestion.
amount	integer	The amount (cents) of the suggestion.
counterparty.name	string	The name of the counterparty.
counterparty.routingNumberLast4 Optional	string	Last 4 digits of the counterparty's routing number.
counterparty.accountNumberLast4 Optional	string	Last 4 digits of the counterparty's account number.
status	string	The status of the suggestion. Always `Cancelled` in this response.
tags Optional	object	See Tags.
createdAt	string	The date the suggestion was created.
updatedAt	string	The date the suggestion was last updated.

Relationships

Name	Type	Description
org	JSON:API Relationship	The organization the suggestion belongs to.
customer	JSON:API Relationship	The Customer the suggestion belongs to. Present when the suggestion is tied to a customer.
account	JSON:API Relationship	The Deposit Account associated with the suggestion. Present once the account is known.

Example Response:

{
	"data": {
		"type": "paymentIntent",
		"id": "50001",
		"attributes": {
			"title": "Monthly rent",
			"description": "Rent for October",
			"amount": 100000,
			"counterparty": {
				"name": "Landlord LLC",
				"routingNumberLast4": "0021",
				"accountNumberLast4": "6789"
			},
			"status": "Cancelled",
			"tags": {},
			"createdAt": "2023-10-20T10:15:22.123Z",
			"updatedAt": "2023-10-20T11:02:47.552Z"
		},
		"relationships": {
			"org": {
				"data": {
					"type": "org",
					"id": "1"
				}
			},
			"customer": {
				"data": {
					"type": "customer",
					"id": "10014"
				}
			}
		}
	}
}

How it works​

Lifecycle​

Supported Suggestion Types​

Suggested Account Creation Coming Soon​

Suggested Split Income Rule Coming Soon​

Suggested Payment​

Create Payment Suggestion​

Attributes​

Relationships​

Response​

201 Created​

Attributes​

Relationships​

Create Payment Suggestion (existing counterparty)​

Attributes​

Relationships​

Response​

201 Created​

Attributes​

Relationships​

Approve Payment Suggestion​

Attributes​

Response​

200 OK​

Attributes​

Relationships​

Approve Payment Suggestion (existing counterparty)​

Attributes​

Relationships​

Response​

200 OK​

Attributes​

Relationships​

Generic Suggested Actions​

Get Suggestion​

Response​

200 OK​

Attributes​

Relationships​

List Suggestions​

Query Parameters​

Response​

200 OK​

Decline Suggestion​

Attributes​

Response​

200 OK​

Attributes​

Relationships​

Cancel Suggestion​

Attributes​

Response​

200 OK​

Attributes​

Relationships​

How it works

Lifecycle

Supported Suggestion Types

Suggested Account Creation Coming Soon

Suggested Split Income Rule Coming Soon

Suggested Payment

Create Payment Suggestion

Attributes

Relationships

Response

201 Created

Attributes

Relationships

Create Payment Suggestion (existing counterparty)

Attributes

Relationships

Response

201 Created

Attributes

Relationships

Approve Payment Suggestion

Attributes

Response

200 OK

Attributes

Relationships

Approve Payment Suggestion (existing counterparty)

Attributes

Relationships

Response

200 OK

Attributes

Relationships

Generic Suggested Actions

Get Suggestion

Response

200 OK

Attributes

Relationships

List Suggestions

Query Parameters

Response

200 OK

Decline Suggestion

Attributes

Response

200 OK

Attributes

Relationships

Cancel Suggestion

Attributes

Response

200 OK

Attributes

Relationships