Linked Accounts

The linked account resource represents an external account that is owned by the originating customer.

It is similar in nature to a counterparty, but with the guarantee that the originating account holder also owns the destination account.

When a customer is expected to send funds to his external account on multiple occasions he may create a linked-account resource and re-use it by creating an ACH payment to linked Account, instead of the customer typing the routing number and account number repeatedly.

When creating an API Token, Unit recommends not to select the payments-write and linked-accounts-write scopes. However, we do recommend selecting the payments-write-linked-account scope, which allows making payments to a linked account resource only.

When using the recommended scopes for API Token you would first need to Create a Customer Token (along with two-factor authentication) in order to create the linked account resource.

The linked account resource also allows you to make (automated) payments without creating a Customer Token or selecting sensitive scopes for the API Token, by using ACH payment to Linked Account and API Token with only payments-write-linked-account selected.

This adds another layer of security, because the API Token alone cannot make payments to linked accounts which are not created and approved by the customer.

Create Linked Account

Creates an ACH Linked Account for a specific customer.

Verb	`POST`
Url	`https://api.s.unit.sh/linked-accounts`
Required Scope	`linked-account-write`
Data Type	`achLinkedAccount`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
name	string	The account holder's name (whether an individual or a business).
plaidProcessorToken	string	Plaid integration token See Plaid processor token
type	string	Either `Business`, `Person` or `Unknown`.
tags	object	Optional. See Tags.
permissions	string	Optional, custom linked account permissions. Either `CreditOnly`, `DebitOnly`, `CreditAndDebit`. By default, linked accounts are assigned the `CreditAndDebit` permission.
idempotencyKey	string	Optional. See Idempotency.

Relationships

Name	Type	Description
customer	JSON:API Relationship	The customer that the linked account belongs to.
org	JSON:API Relationship	The org that the linked account belongs to.

Example Request:
curl -X POST 'https://api.s.unit.sh/linked-accounts'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "achLinkedAccount",
    "attributes": {
      "plaidProcessorToken": "processor-sandbox-0418b7a5-c9e6-423f-a59e-f0e24bfea6ab",
      "type": "Person",
      "permissions": "CreditOnly"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10006"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Field	Type	Description
data	ACH linked account	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "linkedAccount",
    "id": "15",
    "attributes": {
      "name": "Alberta Bobbeth Charleson",
      "bank": "Citizens Bank",
      "routingNumber": "011401533",
      "accountNumber": "1111222233330000",
      "accountType": "Checking",
      "counterpartyType": "Person",
      "permissions": "CreditOnly",
      "createdAt": "2023-02-07T15:24:51.179Z",
      "updatedAt": "2023-02-07T15:24:51.179Z",
      "status": "PendingReview",
      "tags": {}
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10007"
        }
      },
      "org": {
        "data": {
          "type": "org",
          "id": "1"
        }
      }
    }
  }
}

Approve

Approve a linked account resource by id.

Verb	`POST`
Url	`https://api.s.unit.sh/linked-accounts/{id}/approve`
Required Scope	`linked-accounts-write`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	ACH linked account	Linked Account resource.

curl -X POST 'https://api.s.unit.sh/linked-accounts/1/approve' \
-H "Authorization: Bearer ${TOKEN}"

Decline

Decline a linked account resource by id.

Verb	`POST`
Url	`https://api.s.unit.sh/linked-accounts/{id}/decline`
Required Scope	`linked-accounts-write`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	ACH linked account	Linked Account resource.

Example Request:
curl -X POST 'https://api.s.unit.sh/linked-accounts/{id}/decline'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "declineLinkedAccount",
    "attributes": {
      "reason": "potential fraud attempt"
    }
  }
}'

Delete

Delete a linked account resource by id.

Verb	`DELETE`
Url	`https://api.s.unit.sh/linked-accounts/{id}`
Required Scope	`linked-accounts-write`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	ACH linked account	Linked Account resource.

curl -X DELETE 'https://api.s.unit.sh/linked-accounts/1' \
-H "Authorization: Bearer ${TOKEN}"

Get by Id

Get a linked account resource by id.

Verb	`GET`
Url	`https://api.s.unit.sh/linked-accounts/{id}`
Required Scope	`linked-accounts`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	ACH linked account	Linked Account resource.

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

List

List linked accounts. Filtering and paging can be applied.

Verb	`GET`
Url	`https://api.s.unit.sh/linked-accounts`
Required Scope	`linked-accounts`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Optional. Number of resources to skip. See Pagination.
filter[customerId]	string	(empty)	Optional. Filters the results by the specified customer id.
filter[tags]	Tags (JSON)	(empty)	Optional. Filter Counterparties by Tags.

curl -X GET 'https://api.s.unit.sh/linked-accounts?page[limit]=20&page[offset]=0' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	Array of ACH Linked Account	Array of linked account resources.

Example Response:
{
  "data": [
    {
      "type": "linkedAccount",
      "id": "2",
      "attributes": {
        "name": "Alberta Bobbeth Charleson",
        "bank": "Citizens Bank",
        "routingNumber": "011401533",
        "accountNumber": "1111222233330000",
        "accountType": "Checking",
        "counterpartyType": "Person",
        "permissions": "CreditOnly",
        "createdAt": "2023-02-06T16:55:42.274Z",
        "updatedAt": "2023-02-06T16:58:25.454Z",
        "status": "Approved",
        "tags": {}
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10001"
          }
        },
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        }
      }
    },
    {
      "type": "linkedAccount",
      "id": "3",
      "attributes": {
        "name": "Alberta Bobbeth Charleson",
        "bank": "Citizens Bank",
        "routingNumber": "011401533",
        "accountNumber": "1111222233330000",
        "accountType": "Checking",
        "counterpartyType": "Person",
        "permissions": "CreditOnly",
        "createdAt": "2023-02-06T16:55:46.882Z",
        "updatedAt": "2023-02-06T17:00:59.972Z",
        "status": "Approved",
        "tags": {}
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10000"
          }
        },
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        }
      }
    }
  ]
}

Update Linked Account

Update a linked account. Relink existing linked account with a new Plaid processor token.

Verb	`PATCH`
Url	`https://api.s.unit.sh/linked-accounts/:linkedAccountId`
Required Scope	`linked-accounts-write`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
plaidProcessorToken	string	Plaid integration token See Plaid processor token
tags	object	Optional. See Tags.

Update a linked account:
curl -X PATCH 'https://api.s.unit.sh/linked-accounts/:linkedAccountId'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "patchAchLinkedAccount",
    "attributes": {
      "plaidProcessorToken": "processor-sandbox-74088127-ceff-4b5c-890e-1c0006ca0570",
      "tags": {
        "purpose": "tax",
        "my_account_id": "570"
      }
    }
  }
}'

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	ACH Linked Account	The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "linkedAccount",
    "id": "15",
    "attributes": {
      "name": "Alberta Bobbeth Charleson",
      "bank": "Citizens Bank",
      "routingNumber": "011401533",
      "accountNumber": "1111222233330000",
      "accountType": "Checking",
      "counterpartyType": "Person",
      "permissions": "CreditOnly",
      "createdAt": "2023-02-07T15:24:51.179Z",
      "updatedAt": "2023-02-07T15:24:51.179Z",
      "status": "PendingReview",
      "tags": {}
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10007"
        }
      },
      "org": {
        "data": {
          "type": "org",
          "id": "1"
        }
      }
    }
  }
}

Linked Account Statuses

The Linked Account resource can have the following statuses:

Status	Description
`PendingReview`	The linked account was created. Credit ACH payments can be processed using this linked account.
`Approved`	The linked account was approved by the client. Credit and Debit ACH payment can be processed using this linked account.
`Declined`	The linked account was declined by the client. This linked account cannot be used in ACH payment processing
`Deleted`	The linked account was deleted by the client. For all purposes, the linked account no longer exists

Account Funding

Account Funding - allowing a customer that just created an account to fund his new account using an external account (account within another bank or institution) owned by the customer.

Unit supports Account Funding by creating a linked account with Plaid Processor Token and then creating an ACH Debit Payment.

Important Info

You should deeply think about your Account Funding limits, per single payment, daily and monthly. Please consult Unit team on the matter.

How To Fund an Account

Use Plaid Link to allow the customer to provide the account for Account Funding.
Exchange the access token to Unit's processor token.
Create a linked account with the processor token.
Create an ACH Debit Payment, set the verifyCounterpartyBalance to true.
Wait for the payment to be cleared.

Create ACH payment to Linked Account

Originates an ACH payment to a Linked Account. The linked account should be created separately through Create Linked Account.

Verb	`POST`
Url	`https://api.s.unit.sh/payments`
Required Scope	`payments-write-linkedAccount` or `payments-write`
Data Type	`achPayment`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
amount	integer	The amount (in cents).
direction	string	The direction in which the funds flow.
description	string	Payment description (maximum of 10 characters), also known as Company Entry Description, this will show up on statement of the counterparty.
addenda	string	Optional, additional payment description (maximum of 80 characters), not all institutions present that.
idempotencyKey	string	Optional. See Idempotency.
tags	object	Optional. See Tags. Tags that will be copied to any transaction that this payment creates (see Tag Inheritance).
verifyCounterpartyBalance	boolean	Optional, default is `false`. Verify the counterparty balance, if balance verification fails the payment will be rejected with reason set to `CounterpartyInsufficientFunds`.
sameDay	boolean	Optional, default is `false`. See Same Day ACH.
secCode	string	Optional. See Use a custom SEC Code.

Relationships

Name	Type	Description
account	JSON:API Relationship	The Deposit Account originating the payment.
linked account	JSON:API Relationship	The Linked Account the payment to be made to.

Example Request:
curl -X POST 'https://api.s.unit.sh/payments'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "achPayment",
    "attributes": {
      "amount": 10000,
      "direction": "Credit",
      "description": "Funding"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "555"
        }
      },
      "linkedAccount": {
        "data": {
          "type": "linkedAccount",
          "id": "4567"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

Example Response:
{
  "data": {
    "type": "achPayment",
    "id": "1",
    "attributes": {
      "createdAt": "2023-02-19T09:18:57.211Z",
      "amount": 100,
      "direction": "Debit",
      "description": "Testing #1",
      "counterparty": {
        "name": "Jon Jones",
        "routingNumber": "011401533",
        "accountNumber": "1111222233330000",
        "accountType": "Checking"
      },
      "status": "Pending",
      "settlementDate": "2023-02-28",
      "counterpartyVerificationMethod": "Plaid",
      "sameDay": false,
      "secCode": "WEB"
    },
    "relationships": {
      "linkedAccount": {
        "data": {
          "type": "linkedAccount",
          "id": "27"
        }
      },
      "account": {
        "data": {
          "type": "account",
          "id": "10000"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10000"
        }
      },
      "customers": {
        "data": [
          {
            "type": "customer",
            "id": "10000"
          }
        ]
      },
      "org": {
        "data": {
          "type": "org",
          "id": "1"
        }
      },
      "bank": {
        "data": {
          "type": "bank",
          "id": "1"
        }
      }
    }
  }
}

ACH Linked Account

Linked Account is a JSON:API resource, top-level fields:

Field	type	Description
id	string	Identifier of the ACH Linked Account resource.
type	string	Type of the ACH linked account resource.
attributes	JSON Object	JSON object representing the linked account resource.
relationships	JSON:API Relationships	Describes relationships between the ACH linked account and the originating customer.

Attributes

Name	Type	Description
name	string	The account holder's name (whether an individual or a business).
bank	string	Name of the bank.
routingNumber	string	Valid 9-digit ABA routing transit number.
accountNumber	string	Bank account number.
accountType	string	Either `Checking`, `Savings` or `Loan`.
counterpartyType	string	Either `Business`, `Person` or `Unknown`.
permissions	string	`DebitOnly`, `CreditOnly` or `CreditAndDebit`.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt	RFC3339 Date string	The date the resource was updated.
deletedAt	RFC3339 Date string	The date the resource was deleted.
status	string	One of `Pending Review`, `Approved`, `Declined`, `Deleted`. See Linked Account Statuses
tags	object	See Tags.

Relationships

Name	Type	Description
customer	JSON:API Relationship	The customer the linked account belongs to.
org	JSON:API Relationship	The org the linked account belongs to.

Example Linked Account resource:
{
  "data": {
    "type": "linkedAccount",
    "id": "13",
    "attributes": {
      "name": "Alberta Bobbeth Charleson",
      "bank": "Citizens Bank",
      "routingNumber": "011401533",
      "accountNumber": "1111222233330000",
      "accountType": "Checking",
      "counterpartyType": "Person",
      "permissions": "CreditOnly",
      "createdAt": "2023-02-07T09:38:45.636Z",
      "updatedAt": "2023-02-07T14:47:41.805Z",
      "deletedAt": "2023-02-07T14:47:41.805Z",
      "status": "Deleted",
      "tags": {}
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10005"
        }
      },
      "org": {
        "data": {
          "type": "org",
          "id": "1"
        }
      }
    }
  }
}

linkedAccount.created

Occurs when a Linked Account is created.

Example linkedAccount.created payload:
{
  "data": [
    {
      "id": "437",
      "type": "linkedAccount.created",
      "attributes": {
        "createdAt": "2023-02-13T10:34:11.088Z",
        "tags": {}
      },
      "relationships": {
        "linkedAccount": {
          "data": {
            "id": "24",
            "type": "linkedAccount"
          }
        },
        "customer": {
          "data": {
            "id": "10014",
            "type": "customer"
          }
        }
      }
    }
  ]
}

linkedAccount.approved

Occurs when a Linked Account is approved.

Example linkedAccount.approved payload:
{
  "data": [
    {
      "id": "434",
      "type": "linkedAccount.approved",
      "attributes": {
        "createdAt": "2023-02-12T11:42:57.705Z",
        "tags": {}
      },
      "relationships": {
        "linkedAccount": {
          "data": {
            "id": "21",
            "type": "linkedAccount"
          }
        },
        "customer": {
          "data": {
            "id": "10012",
            "type": "customer"
          }
        }
      }
    }
  ]
}

linkedAccount.declined

Occurs when a Linked Account is declined.

Example linkedAccount.declined payload:
{
  "data": [
    {
      "id": "429",
      "type": "linkedAccount.declined",
      "attributes": {
        "createdAt": "2023-02-12T11:41:44.522Z",
        "tags": {}
      },
      "relationships": {
        "linkedAccount": {
          "data": {
            "id": "20",
            "type": "linkedAccount"
          }
        },
        "customer": {
          "data": {
            "id": "10011",
            "type": "customer"
          }
        }
      }
    }
  ]
}

linkedAccount.deleted

Occurs when a Linked Account is deleted.

Example linkedAccount.deleted payload:
{
  "data": [
    {
      "id": "430",
      "type": "linkedAccount.deleted",
      "attributes": {
        "createdAt": "2023-02-12T11:42:00.682Z",
        "tags": {}
      },
      "relationships": {
        "linkedAccount": {
          "data": {
            "id": "20",
            "type": "linkedAccount"
          }
        },
        "customer": {
          "data": {
            "id": "10011",
            "type": "customer"
          }
        }
      }
    }
  ]
}

linkedAccount.expired

Occurs when a plaid token associated with the Linked Account has expired.

Example linkedAccount.expired payload:
{
  "data": [
    {
      "id": "322",
      "type": "linkedAccount.expired",
      "attributes": {
        "createdAt": "2023-02-01T14:38:13.340Z",
        "tags": {}
      },
      "relationships": {
        "linkedAccount": {
          "data": {
            "id": "1",
            "type": "linkedAccount"
          }
        },
        "customer": {
          "data": {
            "id": "10002",
            "type": "customer"
          }
        }
      }
    }
  ]
}

Linked Accounts

Create Linked Account​

Attributes​

Relationships​

Response​

201 Created​

Approve​

Response​

200 OK​

Decline​

Response​

200 OK​

Delete​

Response​

200 OK​

Get by Id​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Update Linked Account​

Attributes​

Response​

200 OK​

Linked Account Statuses​

Account Funding​

How To Fund an Account​

Create ACH payment to Linked Account​

Attributes​

Relationships​

Response​

ACH Linked Account​

Attributes​

Relationships​

linkedAccount.created​

linkedAccount.approved​

linkedAccount.declined​

linkedAccount.deleted​

linkedAccount.expired​

Create Linked Account

Attributes

Relationships

Response

201 Created

Approve

Response

200 OK

Decline

Response

200 OK

Delete

Response

200 OK

Get by Id

Response

200 OK

List

Query Parameters

Response

200 OK

Update Linked Account

Attributes

Response

200 OK

Linked Account Statuses

Account Funding

How To Fund an Account

Create ACH payment to Linked Account

Attributes

Relationships

Response

ACH Linked Account

Attributes

Relationships

linkedAccount.created

linkedAccount.approved

linkedAccount.declined

linkedAccount.deleted

linkedAccount.expired