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	Type	Description
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`.
tags Optional	object	Optional. See Tags.
permissions Optional	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.
idempotencyKey Optional	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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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
verifyName Optional	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`.
permissions Optional	string	Optional, custom counterparty permissions. Either `CreditOnly`, `DebitOnly`, `CreditAndDebit`. Default is `CreditAndDebit`.
tags Optional	object	Optional. See Tags.
idempotencyKey Optional	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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
plaidProcessorToken Optional	string	Optional, unless updating a Plaid counterparty. Plaid integration token See Plaid processor token
verifyName Optional	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`.
permissions Optional	string	Optional, custom counterparty permissions. Either `CreditOnly`, `DebitOnly`, `CreditAndDebit`.
tags Optional	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

Name	Type	Description
data	ACH Counterparty	The target resource after the operation was completed.
meta	JSON object that contains pagination data	Pagination data includes offset, limit and total (estimated total items).

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​

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