Address Book

An address book is a tool that allows users to look up and connect to other Customers Bank clients to facilitate book transfers between accounts. Customers Bank provides API access for searching and managing these connections.

Connection Request

To initiate a book transfer to another client, both clients must be connected. To request a connection with an account, initiate a POST request directed to the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/AddressBook/entries

This request requires additional data to be included in the body of the request.

Body Parameter Data Element Details:

Name	Type	Description
requesterAccountId	string	account id associated with the client initiating a connection request
targetAccountId	string	account id associated with the client receiving a request to connect

Example Request:

A successful request will generate a response of 202 – Accepted.

Example Response:

Error Handling
Common errors will include:
400 – Bad Request
403 - Forbidden
422 - Unprocessable Content

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

Cancel Connection Request

In the event that a connection request was sent in error, a user may cancel the request as long as it is still in a pending status. To cancel a connection request, initiate a POST request directed to the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/AddressBook/entries/{id}/cancel

This request requires the additional data to be included in the path of the request.

Path Parameter Data Element Details:

Name	Type	Description
id	string	address book id

Example Request:

A successful request will generate a response of 202 – Accepted.

Example Response:

Error Handling

Common errors will include:
400 – Bad Request
403 - Forbidden
422 - Unprocessable Content

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

View All Connections

A users has the ability to view all connections within their clients address book. This request will provide relevant details around each connection. To view all connections, initiate a GET request directed to the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/AddressBook/entries

This request requires additional query parameters to be included.

Query Parameter Data Element Details:

Name	Type	Description
partnerName	string	client name
paginateResults	boolean	indicates whether the request should be paginated
page	int32	indicates the page to return
perPage	int32	indicates how many items are on a page
sortOn	string	indicates the attribute by which the data is sorted
sortAscending	boolean	indicates if the data is sorted ascending or descending

Example Request:

GET /transfers/v1/addressbook/entries HTTP/1.1
Host: cubi-sandbox-api.customersbank.com
Authorization: Bearer ******

A successful request will generate a response of 200 - Ok.

Example Response:

{
    "pageSize": 100,
    "pageOffset": 0,
    "totalPages": 1,
    "totalItemCount": 1,
    "items": [
        {
            "id": "e7d5746b-61a0-4cea-a656-b13a00f77209",
            "requesterPartnerId": "06d4503d-dc24-4267-be4b-25d6b4b6c274",
            "requesterPartnerName": "First UAT Bank",
            "requesterAccountId": "1aa81254-13ff-44a4-a132-e4270db6bc46",
            "requesterAccountName": "Operating",
            "requesterAccountNumberLast4Digits": "9863",
            "requestApprovedAt": "2024-03-26T14:02:10.5716374",
            "targetPartnerId": "039b5a1f-5c8f-4ece-97f6-218dfb33f77d",
            "targetPartnerName": "Second UAT Bank",
            "targetAccountId": "59b8d79c-6303-40e0-ab36-b131014d900a",
            "targetAccountName": "8461408",
            "targetAccountNumberLast4Digits": "1408",
            "accountLinkApprovedByUserName": "Jason Tester",
            "accountLinkApprovedByUserEmail": "[email protected]",
            "accountLinkApprovedAt": "2024-03-28T19:30:17.7125339",
            "status": "Linked",
            "lastModifiedAt": "2024-03-28T19:30:17.7126299"
        }
    ]
}

Response Data Element Details:

Name	Type	Description
pageSize	int32	number of items displayed on a page
pageOffset	int32	offset index indicating starting point for page items
totalPages	int32	total number of pages
totalItemCount	int32	total count of items across all pages
items	array of objects \| null	items model
> id	string	address book id
> requesterPartnerId	string \| null	partner id associated with the client initiating a connection request
> requesterPartnerName	string	partner name associated with the client initiating a connection request
> requesterAccountId	string \| null	account id associated with the client initiating a connection request
> requesterAccountName	string \| null	account name associated with the client initiating a connection request
> requesterAccountNumber	string \| null	account number associated with the client initiating a connection request
> requestedByUserId	string \| null	user id that initiated the connection request
> requestedByUserName	string \| null	user name that initiated the connection request
> requestedByUserEmail	string \| null	user email that initiated the connection request
> requestedAt	date-time \| null	date and time the connection request was initiated
> requestApprovedByUserName	string \| null	user name that approved connection request
> requestApprovedByUserEmail	string \| null	user email that approved connection request
> requestApprovedAt	date-time \| null	date and time the connection request was approved
> targetPartnerId	string	partner id associated with the client receiving a request to connect
> targetPartnerName	string \| null	partner name associated with the client receiving a request to connect
> targetAccountId	string	account id associated with the client receiving a request to connect
> targetAccountName	string \| null	account name associated with the client receiving a request to connect
> targetAccountNumber	string \| null	account number associated with the client receiving a request to connect
> accountLinkApprovedByUserName /	string \| null
> accountLinkApprovedByUserEmail	string \| null
> accountLinkApprovedAt	date-time \| null
> status	string	one of the following: Initiated; ApprovalRequired; Declined; Requested; RequestDeclined; Linked; Deleted
> lastModifiedAt	date-time	date and time connection was last modified

Error Handling
Common errors will include:
400 – Bad Request
403 - Forbidden
422 - Unprocessable Content

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

View a Specific Connection

Similar to the prior request, a user can obtain the same level of information for a specific connection if they know the id of the address book entry to be retrieved. To get connection information for a specific connection, initiate a GET request directed to the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/AddressBook/entries/{id}

This request requires the additional data to be included in the path of the request.

Path Parameter Data Element Details:

Name	Type	Description
id	string	address book id

Example Request:

A successful request will generate a response of 200 – Ok.

Example Response:

Response Data Element Details:

Name	Type	Description
pageSize	int32	number of items displayed on a page
pageOffset	int32	offset index indicating starting point for page items
totalPages	int32	total number of pages
totalItemCount	int32	total count of items across all pages
items	array of objects \| null	items model
> id	string	address book id
> requesterPartnerId	string \| null	partner id associated with the client initiating a connection request
> requesterPartnerName	string	partner name associated with the client initiating a connection request
> requesterAccountId	string \| null	account id associated with the client initiating a connection request
> requesterAccountName	string \| null	account name associated with the client initiating a connection request
> requesterAccountNumber	string \| null	account number associated with the client initiating a connection request
> requestedByUserId	string \| null	user id that initiated the connection request
> requestedByUserName	string \| null	user name that initiated the connection request
> requestedByUserEmail	string \| null	user email that initiated the connection request
> requestedAt	date-time \| null	date and time the connection request was initiated
> requestApprovedByUserName	string \| null	user name that approved connection request
> requestApprovedByUserEmail	string \| null	user email that approved connection request
> requestApprovedAt	date-time \| null	date and time the connection request was approved
> targetPartnerId	string	partner id associated with the client receiving a request to connect
> targetPartnerName	string \| null	partner name associated with the client receiving a request to connect
> targetAccountId	string	account id associated with the client receiving a request to connect
> targetAccountName	string \| null	account name associated with the client receiving a request to connect
> targetAccountNumber	string \| null	account number associated with the client receiving a request to connect
> accountLinkApprovedByUserName /	string \| null
> accountLinkApprovedByUserEmail	string \| null
> accountLinkApprovedAt	date-time \| null
> status	string	one of the following: Initiated; ApprovalRequired; Declined; Requested; RequestDeclined; Linked; Deleted
> lastModifiedAt	date-time	date and time connection was last modified

Error Handling:
Common errors will include:
400 – Bad Request
403 – Forbidden
404 – Not Found
422 – Unprocessable Content

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

Delete Connection

When a connection is no longer needed, a user can delete it from their address book. Deleting a connection removes it from both clients' address books. To delete a connect, initiate a DELETE request directed to the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/AddressBook/entries/{id}

Path Parameter Data Element Details:

Name	Type	Description
id	string	address book id

Example Request:

DELETE //transfers/v1/addressbook/entries/e7d5746b-61a0-4cea-a656-b13a00f77209 HTTP/1.1
Host: cubi-sandbox-api.customersbank.com
Authorization: ******

A successful request will generate a response of 204 – No Content.

Error Handling:
Common errors will include:
400 – Bad Request
403 – Forbidden
404 – Not Found
422 – Unprocessable Content

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

View Connection Requests

This endpoint allows users to view all requests to connect. Users will see the client that sent the request, the account they want to connect to, and the account the user is connecting with.

https://cubi-sandbox-api.customersbank.com/transfers/v1/AddressBook/entries/requests

This request requires additional query parameters to be included.

Query Parameter Data Element Details:

Name	Type	Description
paginateResults	boolean	indicates whether the request should be paginated
page	int32	indicates the page to return
perPage	int32	indicates how many items are on a page
sortOn	string	indicates the attribute by which the data is sorted
sortAscending	boolean	indicates if the data is sorted in ascending or descending order

Example Request:

A successful request will generate a response of 200 – Ok.

Example Response:

Response Data Element Details:

Name	Type	Description
pageSize	int32	number of items displayed on a page
pageOffset	int32	offset index indicating starting point for page items
totalPages	int32	total number of pages
totalItemCount	int32	total count of items across all pages
items	array of objects \| null	items model
> id	string	address book id
> requesterPartnerId	string \| null	partner id associated with the client initiating a connection request
> requesterPartnerName	string	partner name associated with the client initiating a connection request
> requesterAccountId	string \| null	account id associated with the client initiating a connection request
> requesterAccountName	string \| null	account name associated with the client initiating a connection request
> requesterAccountNumber	string \| null	account number associated with the client initiating a connection request
> requestedByUserId	string \| null	user id that initiated the connection request
> requestedByUserName	string \| null	user name that initiated the connection request
> requestedByUserEmail	string \| null	user email that initiated the connection request
> requestedAt	date-time \| null	date and time the connection request was initiated
> requestApprovedByUserName	string \| null	user name that approved connection request
> requestApprovedByUserEmail	string \| null	user email that approved connection request
> requestApprovedAt	date-time \| null	date and time the connection request was approved
> targetPartnerId	string	partner id associated with the client receiving a request to connect
> targetPartnerName	string \| null	partner name associated with the client receiving a request to connect
> targetAccountId	string	account id associated with the client receiving a request to connect
> targetAccountName	string \| null	account name associated with the client receiving a request to connect
> targetAccountNumber	string \| null	account number associated with the client receiving a request to connect
> accountLinkApprovedByUserName /	string \| null
> accountLinkApprovedByUserEmail	string \| null
> accountLinkApprovedAt	date-time \| null
> status	string	one of the following: Initiated; ApprovalRequired; Declined; Requested; RequestDeclined; Linked; Deleted
> lastModifiedAt	date-time	date and time connection was last modified

Common errors will include:
403 – Forbidden

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

Search for Connections

To find another client's available accounts, users can search for by the partner's name. A minimum of three characters is required to be entered in the partner name for this request. Searching for connections allows users to discover new clients to connect with or retrieve details for existing or pending connection requests. To search for a connection, initiate a GET request directed at the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/AddressBook/availableAccounts

This request requires additional query parameters to be included.

Query Parameter Data Element Details:

Name	Type	Description
partnerName	string	client name
paginateResults	boolean	indicates whether the request should be paginated
page	int32	indicates the page to return
perPage	int32	indicates how many items are on a page
sortOn	string	indicates the attribute by which the data is sorted
sortAscending	boolean	indicates if the data is sorted in ascending or descending order

Example Request:

A successful request will generate a response of 200 – Ok.

Example Response:

Response Data Element Details:

Name	Type	Description
pageSize	int32	number of items displayed on a page
pageOffset	int32	offset index indicating starting point for page items
totalPages	int32	total number of pages
totalItemCount	int32	total count of items across all pages
items	array of objects \| null	items model
> id	string	address book id
> requesterPartnerId	string \| null	partner id associated with the client initiating a connection request
> requesterPartnerName	string	partner name associated with the client initiating a connection request
> requesterAccountId	string \| null	account id associated with the client initiating a connection request
> requesterAccountName	string \| null	account name associated with the client initiating a connection request
> requesterAccountNumber	string \| null	account number associated with the client initiating a connection request
> requestedByUserId	string \| null	user id that initiated the connection request
> requestedByUserName	string \| null	user name that initiated the connection request
> requestedByUserEmail	string \| null	user email that initiated the connection request
> requestedAt	date-time \| null	date and time the connection request was initiated
> requestApprovedByUserName	string \| null	user name that approved connection request
> requestApprovedByUserEmail	string \| null	user email that approved connection request
> requestApprovedAt	date-time \| null	date and time the connection request was approved
> targetPartnerId	string	partner id associated with the client receiving a request to connect
> targetPartnerName	string \| null	partner name associated with the client receiving a request to connect
> targetAccountId	string	account id associated with the client receiving a request to connect
> targetAccountName	string \| null	account name associated with the client receiving a request to connect
> targetAccountNumber	string \| null	account number associated with the client receiving a request to connect
> accountLinkApprovedByUserName /	string \| null
> accountLinkApprovedByUserEmail	string \| null
> accountLinkApprovedAt	date-time \| null
> status	string	one of the following: Initiated; ApprovalRequired; Declined; Requested; RequestDeclined; Linked; Deleted
> lastModifiedAt	date-time	date and time connection was last modified

Error Handling:
Common errors will include:
403 – Forbidden
404 – Not Found
422 – Unprocessable Content

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

View Incoming Requests to Connect

This endpoint allows users to view incoming requests to connect.

https://cubi-sandbox-api.customersbank.com/transfers/v1/AddressBook/requests

This request requires additional query parameters to be included.

Query Parameter Data Element Details:

Name	Type	Description
paginateResults	boolean	indicates whether the request should be paginated
page	int32	indicates the page to return
perPage	int32	indicates how many items are on a page
sortOn	string	indicates the attribute by which the data is sorted
sortAscending	boolean	indicates if the data is sorted in ascending or descending order

Example Request:

A successful request will generate a response of 200 – Ok.

Example Response:

Response Data Element Details:

Name	Type	Description
pageSize	int32	number of items displayed on a page
pageOffset	int32	offset index indicating starting point for page items
totalPages	int32	total number of pages
totalItemCount	int32	total count of items across all pages
items	array of objects \| null	items model
> id	string
> requesterPartnerName	string \| null	partner name associated with the client initiating a connection request
> requesterAccountName	string \| null	account name associated with the client initiating a connection request
> requesterAccountNumber	string \| null	account number associated with the client initiating a connection request
> targetAccountName	string \| null	account name associated with the client receiving a request to connect
> targetAccountNumber	string \| null	account number associated with the client receiving a request to connect
> requestedAt	date-time	date and time the connection request was initiated

Error Handling: Error Handling:
Common errors will include:
400 – Bad Request
403 – Forbidden

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

Approve Connection Request

Connection requests remain pending until the recipient either approves or declines them. To approve a connection request, initiate a POST request directed at the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/AddressBook/requests/{id}/approve

This request requires the additional data to be included in the path of the request.

Path Parameter Data Element Details:

Name	Type	Description
id	string	address book id

Example Request:

A successful request will generate a response of 202 - Accepted.

Example Response:

Error Handling:
Common errors will include:
400 – Bad Request
403 - Forbidden
422 – Unprocessable Content

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.

Decline Connection Request

Connection requests remain pending until the recipient either approves or declines them. To decline a connection request, initiate a POST request directed at the following endpoint:

https://cubi-sandbox-api.customersbank.com/transfers/v1/AddressBook/requests/{id}/decline

This request requires the additional data to be included in the path of the request.

Path Parameter Data Element Details:

Name	Type	Description
id	string	address book id

Example Request:

A successful request will generate a response of 202 - Accepted.

Example Response:

Error Handling:
Common errors will include:
400 – Bad Request
403 - Forbidden
422 – Unprocessable Content

For guidance on troubleshooting error codes please consult the Error Code Handling section of this guide.