Customer APIs

Note

Different bank partners may have different onboarding requirements. If your bank partner is Thread Bank, please refer to the Thread Customer APIs documentation.

Create Business Wallet Customer

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

Attributes

Name	Type	Description
bankName Required	string	The name of the bank partner this customer is about to create a wallet under.
businessName Required	string	The name of the business this customer represents.
address Required	Address	Address of the business.
ein Required	string	Business EIN (numbers only).
businessVertical Required	BusinessVertical	The business vertical of the business.
numberOfEmployees Required	NumberOfEmployees	The number of employees working for this business.
tags Optional	object	See Updating Tags.

Example Request:

curl -X POST 'https://api.s.unit.sh/customers'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "businessWalletCustomer",
    "attributes": {
      "bankName": "myBankName",
      "businessName": "Sirius & Snape Inc.",
      "address": {
        "street": "5230 Newell Rd",
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "ein": "123456789",
      "businessVertical": "TechnologyMediaOrTelecom",
      "numberOfEmployees": "Between10And50",
      "tags": {
        "purpose": "Sirius & Snape Inc."
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Name	Type	Description
data Required	BusinessWalletCustomer	The requested resource after the operation was completed.

Example Response:
{
  "data": {
    "type": "businessWalletCustomer",
    "id": "42",
    "attributes": {
      "bankName": "myBankName",
      "businessName": "Sirius & Snape Inc.",
      "address": {
        "street": "5230 Newell Rd",
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94303",
        "country": "US"
      },
      "ein": "123456789",
      "businessVertical": "TechnologyMediaOrTelecom",
      "numberOfEmployees": "Between10And50",
      "tags": {
        "purpose": "Sirius & Snape Inc."
      },
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb8"
    }
  }
}

Update Individual Customer

Update an IndividualCustomer. The Customer Updated webhook event will be fired.

Note

Changes to a customer's name, date of birth and SSN require the discretion of a compliance officer and therefore cannot be changed using this endpoint. To change any of these, please contact Unit support with the change details and required documents (if there are any) and our compliance team will process the request for you.

Verb	`PATCH`
URL	`https://api.s.unit.sh/customers/:customerId`
Required Scope	`customers-write` or `customer-tags-write`
Data Type	`individualCustomer`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
address Optional	Address	Address of the individual. To modify or add specify the new address.
phone Optional	Phone	Phone of the individual. To modify or add specify the new phone number.
email Optional	string	Email address of the individual. To modify or add specify the new email address.
dba Optional	string	If the individual is a sole proprietor who is doing business under a different name. To modify or add specify the new dba name.
numberOfEmployees Optional	NumberOfEmployees	Number of employees if the customer is a sole proprietor.
businessVertical Optional	BusinessVertical	Business vertical if the customer is a sole proprietor.
occupation Optional	Occupation	Occupation of the individual.
annualIncome Optional	AnnualIncome	Annual income of the individual.
annualRevenue Optional	AnnualRevenue	Annual revenue if the customer is a sole proprietor.
website Optional	string	Business's website if the customer is a sole proprietor.
sourceOfIncome Optional	SourceOfIncome	Source of income of the individual.
authorizedUsers Required	Optional. Array of AuthorizedUser	Array of authorized users. The provided array items will replace the existing ones.
tags Optional	object	See Updating Tags.
jwtSubject Optional	string	See this section for more information.

Response

Response is a JSON:API document.

200 OK

Name	Type	Description
data Required	IndividualCustomer	Customer resource.

Update an individual customer:

curl -X PATCH 'https://api.s.unit.sh/customers/:customerId'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "individualCustomer",
    "attributes": {
      "address": {
        "street": "5231 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94301",
        "country": "US"
      },
      "email": "richard@piedpiper.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "numberOfEmployees": "Between2And5",
      "businessVertical": "TechnologyMediaOrTelecom",
      "occupation": "ArchitectOrEngineer",
      "annualIncome": "Between50kAnd100k",
      "annualRevenue": "Between100kAnd200k",
      "website": "https://piedpiper.com",
      "sourceOfIncome": "EmploymentOrPayrollIncome",
      "authorizedUsers": [
        {
          "fullName": {
            "first": "Jared",
            "last": "Dunn"
          },
          "email": "jared@piedpiper.com",
          "phone": {
            "countryCode": "1",
            "number": "1555555590"
          },
          "canConnectWithAuthVendor": true
        }
      ]
    }
  }
}'

Update Business Customer

Update a BusinessCustomer. The Customer Updated webhook event will be fired.

Note

Verb	`PATCH`
URL	`https://api.s.unit.sh/customers/:customerId`
Required Scope	`customers-write` or `customer-tags-write`
Data Type	`businessCustomer`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
address Optional	Address	Address of the business. To modify specify the new address.
phone Optional	Phone	Phone of the business. To modify specify the new phone number.
contact Optional	BusinessContact	Primary contact of the business.
authorizedUsers Required	Optional. Array of AuthorizedUser	Array of authorized users. The provided array items will replace the existing ones.
dba Optional	string	To modify or add specify the new dba name.
businessVertical Optional	BusinessVertical	The business vertical of the business.
numberOfEmployees Optional	NumberOfEmployees	Number of employees of the business.
annualRevenue Optional	AnnualRevenue	Annual revenue of the business.
cashFlow Optional	CashFlow	Cash flow of the business.
countriesOfOperation Optional	Array of ISO31661-Alpha2 strings	Countries where the business operates.
website Optional	string	Business's website.
stockSymbol Optional	string	Stock symbol (ticker) of the business.
yearOfIncorporation Optional	Year string	Year of incorporation of the business.
operatingAddress Optional	Address	The operating address of the business.
tags Optional	object	See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Name	Type	Description
data Required	BusinessCustomer	Customer resource.

Update business customer:

curl -X PATCH 'https://api.s.unit.sh/customers/:customerId'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "businessCustomer",
    "attributes": {
      "address": {
        "street": "5231 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94301",
        "country": "US"
      },
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "contact": {
        "fullName": {
          "first": "Jone",
          "last": "Doe"
        },
        "email": "jone.doe@unit-finance.com",
        "phone": {
          "countryCode": "1",
          "number": "2025550108"
        }
      },
      "businessVertical": "TechnologyMediaOrTelecom",
      "numberOfEmployees": "Between50And100",
      "annualRevenue": "Between500kAnd1m",
      "cashFlow": "Predictable",
      "countriesOfOperation": [
        "US",
        "CA"
      ],
      "website": "https://piedpiper.com",
      "stockSymbol": "PPI",
      "yearOfIncorporation": "2014",
      "operatingAddress": {
        "street": "5231 Newell Rd",
        "street2": null,
        "city": "Palo Alto",
        "state": "CA",
        "postalCode": "94301",
        "country": "US"
      },
      "authorizedUsers": [
        {
          "fullName": {
            "first": "Jared",
            "last": "Dunn"
          },
          "email": "jared@piedpiper.com",
          "phone": {
            "countryCode": "1",
            "number": "1555555590"
          },
          "canConnectWithAuthVendor": true
        }
      ]
    }
  }
}'

Update Business Customer Officer

Update an officer of a business customer.

Verb	`PATCH`
URL	`https://api.s.unit.sh/customers/:customerId/officers/:officerId`
Required Scope	`customers-write`
Data Type	`officer`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
title Optional	OfficerTitle	Title of the officer.
occupation Optional	Occupation	Occupation of the officer.
annualIncome Optional	AnnualIncome	Annual income of the officer.
sourceOfIncome Optional	SourceOfIncome	Source of income of the officer.

Response

Response is a JSON:API document.

200 OK

Name	Type	Description
data Required	Officer	Updated officer resource.

Update business customer officer:

curl -X PATCH 'https://api.s.unit.sh/customers/:customerId/officers/:officerId'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "officer",
    "attributes": {
      "occupation": "ExecutiveOrManager",
      "annualIncome": "Between100kAnd250k",
      "sourceOfIncome": "EmploymentOrPayrollIncome",
      "title": "CEO"
    }
  }
}'

Archive Customer

Archive a customer. The Customer Archived webhook event will be fired.

Note

Archiving a Customer is a final action that cannot be undone.
Once a Customer has been archived, they become read-only and no changes can be made to anything associated with that customer.
You may only archive a customer after all their account have been closed.
In the future, if you would like to provide financial services to the same customer, they would have to submit a new Application

Verb	`POST`
URL	`https://api.s.unit.sh/customers/:customerId/archive`
Required Scope	`customers-write`
Data Type	`customerArchive`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
reason Required	string	The reason for archiving the customer. One of `Inactive`, `FraudACHActivity`, `FraudCardActivity`, `FraudCheckActivity`, `FraudApplicationHistory`, `FraudAccountActivity`, `FraudClientIdentified`, `FraudLinkedToFraudulentCustomer`, `ByBank`. This list is subject to change.

Response

Response is a JSON:API document.

200 OK

Name	Type	Description
data Required	BusinessCustomer or IndividualCustomer	Customer resource. be either business or individual, as indicated by the `type` field.

Archive Customer:

curl -X POST 'https://api.s.unit.sh/customer/10000/archive'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "archiveCustomer",
    "attributes": {
      "reason": "FraudCardActivity"
    }
  }
}'

Get by Id

Get a customer resource by id.

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

Query Parameters

Name	Type	Default	Description
include	string	(empty)	Optional. A comma-separated list of related resources to include in the response. Related resource include: `authorizedUser`. See Getting Related Resources

Response

Response is a JSON:API document.

200 OK

Name	Type	Description
data Required	BusinessCustomer or IndividualCustomer	Customer resource. Can be either business or individual, as indicated by the `type` field.
included Required	Array of AuthorizedUser	Array of resources requested by the include query parameter.

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

List

List customer resources. Paging can be applied.

Verb	`GET`
URL	`https://api.s.unit.sh/customers`
Required Scope	`customers`
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[query]	string	(empty)	Optional. Search term according to the Full-Text Search Rules.
filter[email]	string	(empty)	Optional. Filter customers by email address (case sensitive).
filter[tags]	Tags (JSON)	(empty)	Optional. Filter Customers by Tags.
filter[status][]	string	(empty)	Optional. Filter customers by status (`Active`, `Archived`). Usage example: *filter[status][0]=Active
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/customers?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Name	Type	Description
data Required	Array of BusinessCustomer or IndividualCustomer	Array of customer resources. Each resource can be either business or individual, as indicated by the `type` field.
meta Required	JSON object that contains pagination data	Pagination data includes offset, limit and total (estimated total items).

Example Response:
{
  "data": [
    {
      "type": "businessCustomer",
      "id": "1",
      "attributes": {
        "createdAt": "2020-05-10T12:28:37.698Z",
        "name": "Pied Piper",
        "address": {
          "street": "5230 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94303",
          "country": "US"
        },
        "phone": {
          "countryCode": "1",
          "number": "1555555566"
        },
        "stateOfIncorporation": "DE",
        "ein": "123456789",
        "entityType": "Corporation",
        "contact": {
          "fullName": {
            "first": "Richard",
            "last": "Hendricks"
          },
          "email": "richard@piedpiper.com",
          "phone": {
            "countryCode": "1",
            "number": "1555555566"
          }
        },
        "businessVertical": "TechnologyMediaOrTelecom",
        "numberOfEmployees": "Between50And100",
        "annualRevenue": "Between500kAnd1m",
        "cashFlow": "Predictable",
        "countriesOfOperation": [
          "US",
          "CA"
        ],
        "website": "https://piedpiper.com",
        "stockSymbol": "PPI",
        "yearOfIncorporation": "2014",
        "operatingAddress": {
          "street": "5231 Newell Rd",
          "street2": null,
          "city": "Palo Alto",
          "state": "CA",
          "postalCode": "94301",
          "country": "US"
        },
        "status": "Active"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        },
        "application": {
          "data": {
            "type": "businessApplication",
            "id": "1"
          }
        },
        "officer": {
          "data": {
            "type": "officer",
            "id": "12"
          }
        },
        "beneficialOwners": {
          "data": [
            {
              "type": "beneficialOwner",
              "id": "45"
            }
          ]
        }
      }
    },
    {
      "type": "individualCustomer",
      "id": "8",
      "attributes": {
        "createdAt": "2020-05-12T19:41:04.123Z",
        "fullName": {
          "first": "Peter",
          "last": "Parker"
        },
        "ssn": "721074426",
        "address": {
          "street": "20 Ingram St",
          "street2": null,
          "city": "Forest Hills",
          "state": "NY",
          "postalCode": "11375",
          "country": "US"
        },
        "dateOfBirth": "2001-08-10",
        "email": "peter@oscorp.com",
        "phone": {
          "countryCode": "1",
          "number": "1555555566"
        },
        "occupation": "ArchitectOrEngineer",
        "annualIncome": "Between50kAnd100k",
        "sourceOfIncome": "EmploymentOrPayrollIncome",
        "annualRevenue": "Between100kAnd200k",
        "numberOfEmployees": "Between2And5",
        "businessVertical": "TechnologyMediaOrTelecom",
        "website": "https://piedpiper.com",
        "status": "Active"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        },
        "application": {
          "data": {
            "type": "individualApplication",
            "id": "8"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "limit": 100,
      "offset": 0
    }
  }
}

Create Business Wallet Customer​

Attributes​

Response​

201 Created​

Update Individual Customer​

Attributes​

Response​

200 OK​

Update Business Customer​

Attributes​

Response​

200 OK​

Update Business Customer Officer​

Attributes​

Response​

200 OK​

Archive Customer​

Attributes​

Response​

200 OK​

Get by Id​

Query Parameters​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Create Business Wallet Customer

Attributes

Response

201 Created

Update Individual Customer

Attributes

Response

200 OK

Update Business Customer

Attributes

Response

200 OK

Update Business Customer Officer

Attributes

Response

200 OK

Archive Customer

Attributes

Response

200 OK

Get by Id

Query Parameters

Response

200 OK

List

Query Parameters

Response

200 OK