Counterparty APIs

Create Counterparty

Creates an ACH counterparty for a specific customer.

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

Attributes

name

string

The account holder's name (whether an individual or a business, maximum of 50 characters).

routingNumber

string

Valid 9-digit ABA routing transit number.

accountNumber

string

Bank account number.

accountType

string

(defaults to checking). Either Checking, Savings or Loan.

type

string

Either Business, Person or Unknown.

tagsOptional

object

Optional. See Tags.

permissionsOptional

string

Optional, custom counterparty permissions. Only DebitOnly or CreditAndDebit are valid values when using the permissions' attribute. 'CreditOnly' will be assigned as default value when permissions attribute is not declared. If the account and rounting number of the counterparty belong to an account under your org on Unit, you may specify "CreditAndDebit" or "DebitOnly" permissions as well.

idempotencyKeyOptional

string

Optional. See Idempotency.

Suggestion

The 'accountType' field should be collected from the customer. If the accountType provided to Unit is incorrect, the payment might still be processed, or you may receive a return.

Relationships

customer

JSON:API Relationship

The customer that the counterparty belongs to.

Example Request:

curl -X POST 'https://api.s.unit.sh/counterparties'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "achCounterparty",
    "attributes": {
      "name": "Joe Doe",
      "routingNumber": "011000133",
      "accountNumber": "123",
      "accountType": "Checking",
      "type": "Person"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "111111"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

data

ACH Counterparty

The target resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "achCounterparty",
    "id": "8",
    "attributes": {
      "createdAt": "2020-05-13T09:07:47.645Z",
      "name": "Joe Doe",
      "routingNumber": "011000133",
      "bank": "Bank Of America",
      "accountNumber": "123",
      "accountType": "Checking",
      "type": "Person",
      "permissions": "CreditOnly"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "111111"
        }
      }
    }
  }
}

Create Counterparty with Plaid token

Creates a counterparty for a specific customer.

Suggestion

For more information on using Plaid, please read Unit's Plaid partnership guide

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

Attributes

type

string

Either Business, Person or Unknown

name

string

The account holder's name (whether an individual or a business).

plaidProcessorToken

string

Plaid integration token
See Plaid processor token

verifyNameOptional

boolean

Optional, default to false. Verify a match between the name of the counterparty and the name of the external account's owner as provided by Plaid. If the name verification fails the request will fail with code field set to NameVerificationFailed.

permissionsOptional

string

Optional, custom counterparty permissions. Either CreditOnly, DebitOnly, CreditAndDebit. Default is CreditAndDebit.

tagsOptional

object

Optional. See Tags.

idempotencyKeyOptional

string

Optional. See Idempotency.

Note

Unit is using a fuzzy name-match algorithm for name verification, which is not always accurate, because of that we include the counterparty account owners in the error returned under meta.owners. You can use that information to implement a manual review process.

Relationships

customer

JSON:API Relationship

The customer that the counterparty belongs to.

Example Request:

curl -X POST 'https://api.s.unit.sh/counterparties'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "achCounterparty",
    "attributes": {
      "name": "Sherlock Holmes",
      "plaidProcessorToken": "processor-5a62q307-ww0a-6737-f6db-pole26004556",
      "type": "Person",
      "permissions": "DebitOnly"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "111111"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

data

ACH Counterparty

The target resource after the operation was completed.

408 Request Timeout

The request to Plaid has timed-out, probably because of a technical issue with the counterparty bank. You might want to retry the request without the verifyName flag.

409 Conflict

The counterparty with specified Plaid token already exists. existingIds of the duplicate entries are specified in the response message.

Example Conflict Response:
{
  "errors": [
    {
      "title": "Already Exists",
      "status": "409",
      "details": "Counterparty with such name already exists",
      "detail": "Counterparty with such name already exists",
      "meta": {
        "existingIds": [
          "49",
          "51"
        ],
        "supportId": "b99998b8-aaaa-47467-b8c8-c14467777999"
      }
    }
  ]
}

Delete

Delete a counterparty resource by id.

Verb	`DELETE`
URL	`https://api.s.unit.sh/counterparties/{id}`
Required Scope	`counterparties`
Timeout (Seconds)	`5`

Response

204 No Content

curl -X DELETE 'https://api.s.unit.sh/counterparties/1'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'

Get by Id

Get a counterparty resource by id.

Verb	`GET`
URL	`https://api.s.unit.sh/counterparties/{id}`
Required Scope	`counterparties`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

data

ACH Counterparty

Counterparty resource.

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

Get Counterparty Balance By Id

Get a counterparty resource by id.

Note

Counterparty must be created with Plaid Processor token in order to run this request.
The external account balance will only be returned if customer is the owner of the counterparty account.

Verb	`GET`
URL	`https://api.s.unit.sh/counterparties/{id}/balance`
Required Scope	`counterparties`
Timeout (Seconds)	`120`

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

Response

Response is a JSON:API document.

200 OK

data

Counterparty Balance

Counterparty Balance resource.

Example Response:
{
  "data": {
    "type": "counterpartyBalance",
    "id": "123456",
    "attributes": {
      "balance": 11000,
      "available": 10000
    },
    "relationships": {
      "counterparty": {
        "data": {
          "type": "counterparty",
          "id": "123456"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "8"
        }
      }
    }
  }
}

List

List counterparties. Filtering and paging can be applied.

Verb	`GET`
URL	`https://api.s.unit.sh/counterparties`
Required Scope	`counterparties`
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[accountNumber]	string	(empty)	Optional. Filters the results by the specified account number.
filter[routingNumber]	string	(empty)	Optional. Filters the results by the specified routing number.
filter[tags]	Tags (JSON)	(empty)	Optional. Filter Counterparties by Tags.
filter[permissions][]	string	(empty)	Optional. Filters the results by the specified counterparty permissions either `CreditOnly`, `DebitOnly`, `CreditAndDebit`. Usage example: filter[permissions][0]=CreditOnly&filter[permissions][1]=CreditAndDebit
sort	string	`sort=createdAt`	Optional. `sort=createdAt` for ascending order or `sort=-createdAt` (leading minus sign) for descending order.

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

Response

Response is a JSON:API document.

200 OK

data

Array of ACH Counterparty

Array of counterparty resources.

Example Response:
{
  "data": [
    {
      "type": "achCounterparty",
      "id": "8",
      "attributes": {
        "createdAt": "2020-05-13T09:07:47.645Z",
        "name": "Joe Doe",
        "routingNumber": "123456789",
        "accountNumber": "123",
        "accountType": "Checking",
        "type": "Person",
        "permissions": "CreditOnly"
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "111111"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "limit": 20,
      "offset": 0
    }
  }
}

Update Counterparty

Update a Counterparty. Relink existing counterparty with a new Plaid processor token.

Verb	`PATCH`
URL	`https://api.s.unit.sh/counterparties/:counterpartyId`
Required Scope	`counterparties-write`
Timeout (Seconds)	`5`

Attributes

plaidProcessorTokenOptional

string

Optional, unless updating a Plaid counterparty. Plaid integration token
See Plaid processor token

verifyNameOptional

boolean

Optional, default to false. Verify the name of the counterparty, if the name verification fails the request will fail with code field set to NameVerificationFailed.

permissionsOptional

string

Optional, custom counterparty permissions. Either CreditOnly, DebitOnly, CreditAndDebit.

tagsOptional

object

Optional. See Tags.

Update a counterparty:

curl -X PATCH 'https://api.s.unit.sh/counterparties/:counterpartyId'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "counterparty",
    "attributes": {
      "plaidProcessorToken": "processor-sandbox-b14ad1fd-3398-46a8-a316-5bf574fc2459"
    },
    "permissions": "CreditOnly"
  }
}'

Response

Response is a JSON:API document.

200 OK

data

ACH Counterparty

The target resource after the operation was completed.

Counterparty APIs

Create Counterparty​

Attributes​

Relationships​

Response​

201 Created​

Create Counterparty with Plaid token​

Attributes​

Relationships​

Response​

201 Created​

408 Request Timeout​

409 Conflict​

Delete​

Response​

204 No Content​

Get by Id​

Response​

200 OK​

Get Counterparty Balance By Id​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Update Counterparty​

Attributes​

Response​

200 OK​

Create Counterparty

Attributes

Relationships

Response

201 Created

Create Counterparty with Plaid token

Attributes

Relationships

Response

201 Created

408 Request Timeout

409 Conflict

Delete

Response

204 No Content

Get by Id

Response

200 OK

Get Counterparty Balance By Id

Response

200 OK

List

Query Parameters

Response

200 OK

Update Counterparty

Attributes

Response

200 OK