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 be one of BusinessCustomer, IndividualCustomer or TrustCustomer
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 UsersAuthorized 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.
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 |
#
AttributesName | 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. |
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. |
#
ResponseResponse is a JSON:API document.
#
200 OKField | Type | Description |
---|---|---|
data | IndividualCustomer | Customer resource. |
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
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 | businessCustomer |
Timeout (Seconds) | 5 |
#
AttributesName | 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. |
#
ResponseResponse is a JSON:API document.
#
200 OKField | Type | Description |
---|---|---|
data | BusinessCustomer | Customer resource. |
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" } } ] } }}'
Update Trust Customer#
Update an TrustCustomer. 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 | trustCustomer |
Timeout (Seconds) | 5 |
#
AttributesName | Type | Description |
---|---|---|
contact | BusinessContact | Optional. Primary contact of the trust. |
authorizedUsers | Optional. Array of AuthorizedUser | Array of authorized users. The provided array items will replace the existing ones. |
tags | object | Optional. See Updating Tags. |
#
ResponseResponse is a JSON:API document.
#
200 OKField | Type | Description |
---|---|---|
data | TrustCustomer | Customer resource. |
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": "trustCustomer", "attributes": { "contact": { "fullName": { "first": "Jone", "last": "Doe" }, "email": "jone.doe@unit-finance.com", "phone": { "countryCode": "1", "number": "2025550108" }, "address": { "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" } } ] } }}'
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 |
#
ResponseResponse is a JSON:API document.
#
200 OKField | Type | Description |
---|---|---|
data | BusinessCustomer, IndividualCustomer or TrustCustomer | Customer resource. Can be one of business, individual or trust, 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 ParametersName | 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}"
#
ResponseResponse is a JSON:API document.
#
200 OKField | Type | Description |
---|---|---|
data | Array of BusinessCustomer, IndividualCustomer or TrustCustomer | Array of customer resources. Each resource can be one of business, individual or trust, as indicated by the type field. |
meta | JSON object that contains pagination data | Pagination data includes offset, limit and total (total items). |
{ "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 |
#
AttributesName | 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. |
#
ResponseResponse is a JSON:API document.
#
200 OKField | Type | Description |
---|---|---|
data | BusinessCustomer, IndividualCustomer or TrustCustomer | Customer resource. Can be one of business, individual or trust, as indicated by the type field. |
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 |
#
AttributesName | Type | Description |
---|---|---|
authorizedUsers | Array of AuthorizedUser | Array of authorized users. The provided array items will be added to the existing ones. |
#
ResponseResponse is a JSON:API document.
#
200 OKField | Type | Description |
---|---|---|
data | BusinessCustomer, IndividualCustomer or TrustCustomer | Customer resource. Can be one of business, individual or trust, as indicated by the type field. |
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 |
#
AttributesName | Type | Description |
---|---|---|
authorizedUsersEmails | Array of emails (strings) | The list of authorized users emails to remove from the customer. |
#
ResponseResponse is a JSON:API document.
#
200 OKField | Type | Description |
---|---|---|
data | BusinessCustomer, IndividualCustomer or TrustCustomer | Customer resource. Can be one of business, individual or trust, as indicated by the type field. |
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" ] } }}'