Suggested Actions Coming Soon

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"
            },
            "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.

200 OK

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

Attributes

Name	Type	Description
title Required	string	The title of the suggestion.
description Required	string	The description of the suggestion.
amount Required	integer	The amount (cents) of the suggestion.
counterparty Required	object	The counterparty of the suggestion.
paymentType Optional	string	The type of payment.
status Required	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 Required	string	The date the suggestion was created.
updatedAt Required	string	The date the suggestion was last updated.

Relationships

Name	Type	Description
customer Required	Optional, JSON:API Relationship	The Customer the suggestion belongs to.
account Required	Optional, JSON:API Relationship	The Deposit Account associated with the suggestion, once 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": "Created",
      "tags": {},
      "createdAt": "2023-10-20T10:15:22.123Z",
      "updatedAt": "2023-10-20T10:15:22.123Z"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10014"
        }
      }
    }
  }
}

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 with status Approved and approvedAt set.

Response is a JSON:API document.

200 OK

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

Attributes

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

Relationships

Name	Type	Description
customer Required	Optional, JSON:API Relationship	The Customer the suggestion belongs to.
account Required	JSON:API Relationship	The Deposit Account the payment will be made from.
payment Required	Optional, 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": "Approved",
      "approvedAt": "2023-10-20T11:02:47.552Z",
      "tags": {},
      "createdAt": "2023-10-20T10:15:22.123Z",
      "updatedAt": "2023-10-20T11:02:47.552Z"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10014"
        }
      },
      "account": {
        "data": {
          "type": "account",
          "id": "10004"
        }
      },
      "payment": {
        "data": {
          "type": "payment",
          "id": "20001"
        }
      }
    }
  }
}

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.

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 Required	string	Identifier of the suggestion resource.
type Required	string	Type of the suggestion resource — one of the supported suggestion types, e.g. `paymentIntent`.
attributes Required	JSON Object	JSON object representing the suggestion's data. Which fields are present depends on `type` — see note below.
relationships Required	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.

Attributes

Name	Type	Description
title Required	string	The title of the suggestion.
description Required	string	The description of the suggestion.
amount Required	integer	The amount (cents) of the suggestion.
counterparty Required	object	The counterparty of the suggestion.
paymentType Optional	string	The type of payment.
status Required	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 Required	string	The date the suggestion was created.
updatedAt Required	string	The date the suggestion was last updated.

Relationships

Name	Type	Description
customer Required	Optional, JSON:API Relationship	The Customer the suggestion belongs to.
account Required	Optional, JSON:API Relationship	The Deposit Account associated with the suggestion, once known.
payment Required	Optional, 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"
      },
      "status": "Created",
      "tags": {},
      "createdAt": "2023-10-20T10:15:22.123Z",
      "updatedAt": "2023-10-20T10:15:22.123Z"
    },
    "relationships": {
      "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.

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 Required	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"
        },
        "status": "Created",
        "tags": {},
        "createdAt": "2023-10-20T10:15:22.123Z",
        "updatedAt": "2023-10-20T10:15:22.123Z"
      },
      "relationships": {
        "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`
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": "paymentIntent",
        "attributes": {
            "idempotencyKey": "unique-idempotency-key"
        }
    }
}'

Note

The request's data.type must match the actual type of the suggestion at :intentId (paymentIntent in this example) — see Supported Suggestion Types.

Response

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

Response is a JSON:API document.

200 OK

Name	Type	Description
id Required	string	Identifier of the suggestion resource.
type Required	string	Type of the suggestion resource — one of the supported suggestion types, e.g. `paymentIntent`.
attributes Required	JSON Object	JSON object representing the suggestion's data. Which fields are present depends on `type` — see note below.
relationships Required	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 Required	string	The title of the suggestion.
description Required	string	The description of the suggestion.
amount Required	integer	The amount (cents) of the suggestion.
counterparty Required	object	The counterparty of the suggestion.
status Required	string	The status of the suggestion. Always `Declined` in this response.
declinedAt Required	string	The date the customer declined the suggestion.
tags Optional	object	See Tags.
createdAt Required	string	The date the suggestion was created.
updatedAt Required	string	The date the suggestion was last updated.

Relationships

Name	Type	Description
customer Required	Optional, JSON:API Relationship	The Customer the suggestion belongs to.

Example Response:

{
  "data": {
    "type": "paymentIntent",
    "id": "50001",
    "attributes": {
      "title": "Monthly rent",
      "description": "Rent for October",
      "amount": 100000,
      "counterparty": {
        "name": "Landlord LLC"
      },
      "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": {
      "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`
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": "paymentIntent",
        "attributes": {
            "idempotencyKey": "unique-idempotency-key"
        }
    }
}'

Note

The request's data.type must match the actual type of the suggestion at :intentId (paymentIntent in this example) — see Supported Suggestion Types.

Response

Returns the cancelled suggestion, with status Cancelled.

Response is a JSON:API document.

200 OK

Name	Type	Description
id Required	string	Identifier of the suggestion resource.
type Required	string	Type of the suggestion resource — one of the supported suggestion types, e.g. `paymentIntent`.
attributes Required	JSON Object	JSON object representing the suggestion's data. Which fields are present depends on `type` — see note below.
relationships Required	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 Required	string	The title of the suggestion.
description Required	string	The description of the suggestion.
amount Required	integer	The amount (cents) of the suggestion.
counterparty Required	object	The counterparty of the suggestion.
status Required	string	The status of the suggestion. Always `Cancelled` in this response.
tags Optional	object	See Tags.
createdAt Required	string	The date the suggestion was created.
updatedAt Required	string	The date the suggestion was last updated.

Relationships

Name	Type	Description
customer Required	Optional, JSON:API Relationship	The Customer the suggestion belongs to.

Example Response:

{
  "data": {
    "type": "paymentIntent",
    "id": "50001",
    "attributes": {
      "title": "Monthly rent",
      "description": "Rent for October",
      "amount": 100000,
      "counterparty": {
        "name": "Landlord LLC"
      },
      "status": "Cancelled",
      "tags": {},
      "createdAt": "2023-10-20T10:15:22.123Z",
      "updatedAt": "2023-10-20T11:02:47.552Z"
    },
    "relationships": {
      "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​

200 OK​

Attributes​

Relationships​

Approve Payment Suggestion​

Attributes​

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

200 OK

Attributes

Relationships

Approve Payment Suggestion

Attributes

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