Customers

Customers represent individuals or businesses that you may create financial products for.

You cannot create customer resources directly — they are automatically created once an application is approved.

A customer can either BusinessCustomer or IndividualCustomer.

info

We recommend listening to webhooks to be notified when a customer is created. Once you get notified, you may interact immediately with the customer resource to create financial products for them (e.g. deposit accounts).

Authorized Users

Authorized Users represent individuals that have full access to the Customer's financials - they are able to authenticate and create a Customer Token and initiate any activity on behalf of the customer. This feature is used mostly in Business customers and Sole Proprietors, where the customer is a Business that can have multiple individuals managing its financials.

note

For Individual customers, Authorized users should not be used, except for very specific use cases. Please consult Unit if you plan to use this feature for individuals.

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	string	The name of the bank partner this customer is about to create a wallet under.
businessName	string	The name of the business this customer represents.
address	Address	Address of the business.
ein	string	Business EIN (numbers only).
businessVertical	BusinessVertical	The business vertical of the business.
numberOfEmployees	NumberOfEmployees	The number of employees working for this business.
tags	object	Optional. 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

Field	Type	Description
data	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	Address	Optional. Address of the individual. To modify or add specify the new address.
phone	Phone	Optional. Phone of the individual. To modify or add specify the new phone number.
email	string	Optional. Email address of the individual. To modify or add specify the new email address.
dba	string	Optional. If the individual is a sole proprietor who is doing business under a different name. To modify or add specify the new dba name.
authorizedUsers	Optional. Array of AuthorizedUser	Array of authorized users. The provided array items will replace the existing ones.
tags	object	Optional. See Updating Tags.
jwtSubject	string	Optional. See this section for more information.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	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"
      },
      "authorizedUsers": [
        {
          "fullName": {
            "first": "Jared",
            "last": "Dunn"
          },
          "email": "jared@piedpiper.com",
          "phone": {
            "countryCode": "1",
            "number": "1555555590"
          }
        }
      ]
    }
  }
}'

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	Address	Optional. Address of the business. To modify specify the new address.
phone	Phone	Optional. Phone of the business. To modify specify the new phone number.
contact	BusinessContact	Optional. Primary contact of the business.
authorizedUsers	Optional. Array of AuthorizedUser	Array of authorized users. The provided array items will replace the existing ones.
dba	string	Optional. To modify or add specify the new dba name.
tags	object	Optional. See Updating Tags.

Response

Response is a JSON:API document.

200 OK

Field	Type	Description
data	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"
        }
      },
      "authorizedUsers": [
        {
          "fullName": {
            "first": "Jared",
            "last": "Dunn"
          },
          "email": "jared@piedpiper.com",
          "phone": {
            "countryCode": "1",
            "number": "1555555590"
          }
        }
      ]
    }
  }
}'

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`

Response

Response is a JSON:API document.

200 OK

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

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

Field	Type	Description
data	Array of BusinessCustomer or IndividualCustomer	Array of customer resources. Each resource can be either business or individual, as indicated by the `type` field.
meta	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"
          }
        },
        "status": "Active"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        },
        "application": {
          "data": {
            "type": "businessApplication",
            "id": "1"
          }
        }
      }
    },
    {
      "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"
        },
        "status": "Active"
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        },
        "application": {
          "data": {
            "type": "individualApplication",
            "id": "8"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "limit": 100,
      "offset": 0
    }
  }
}

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	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

Field	Type	Description
data	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"
    }
  }
}'

Add Authorized Users

Add authorized users for a customer. The Customer Update webhook event will be fired.

note

When adding an authorized user with the same Email as an existing authorized users of the customer, the existing authorized user info will be updated according to the info in the request.

Verb	`POST`
Url	`https://api.s.unit.sh/customers/:customerId/authorized-users`
Required Scope	`customers-write`
Data Type	`addAuthorizedUsers`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
authorizedUsers	Array of AuthorizedUser	Array of authorized users. The provided array items will be added to the existing ones.

Response

Response is a JSON:API document.

200 OK

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

Add Customer Authorized Users:
curl -X POST 'https://api.s.unit.sh/customers/10000/authorized-users'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "addAuthorizedUsers",
    "attributes": {
      "authorizedUsers": [
        {
          "fullName": {
            "first": "Erlich",
            "last": "Backman"
          },
          "email": "erlich@piedpiper.com",
          "phone": {
            "countryCode": "1",
            "number": "1234567890"
          }
        }
      ]
    }
  }
}'

Remove Authorized Users

Remove existing authorized users from a customer. The Customer Update webhook event will be fired.

note

Authorized users emails are unique, when removing an authorized user it is identified only by its email address

Verb	`DELETE`
Url	`https://api.s.unit.sh/customers/:customerId/authorized-users`
Required Scope	`customers-write`
Data Type	`removeAuthorizedUsers`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
authorizedUsersEmails	Array of emails (strings)	The list of authorized users emails to remove from the customer.

Response

Response is a JSON:API document.

200 OK

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

Remove Customer Authorized Users:
curl -X DELETE 'https://api.s.unit.sh/customer/10000/authorized-users'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "removeAuthorizedUsers",
    "attributes": {
      "authorizedUsersEmails": [
        "jared@piedpiper.com"
      ]
    }
  }
}'

Customers

Authorized Users​

Create Business Wallet Customer​

Attributes​

Response​

201 Created​

Update Individual Customer​

Attributes​

Response​

200 OK​

Update Business Customer​

Attributes​

Response​

200 OK​

Get by Id​

Response​

200 OK​

List​

Query Parameters​

Response​

200 OK​

Archive Customer​

Attributes​

Response​

200 OK​

Add Authorized Users​

Attributes​

Response​

200 OK​

Remove Authorized Users​

Attributes​

Response​

200 OK​

Authorized Users

Create Business Wallet Customer

Attributes

Response

201 Created

Update Individual Customer

Attributes

Response

200 OK

Update Business Customer

Attributes

Response

200 OK

Get by Id

Response

200 OK

List

Query Parameters

Response

200 OK

Archive Customer

Attributes

Response

200 OK

Add Authorized Users

Attributes

Response

200 OK

Remove Authorized Users

Attributes

Response

200 OK