Customers

customer is an end-user, the actual owner of one or more accounts at supported financial institutions. Finicity's Customer resource includes services for creating, modifying, and deleting customers.

There are two types of customers:

  • Testing customers may only activate accounts with Finicity's testing institution FinBank (institution ID 101732). Partners subscribed to one of the Test Drive plans may only add testing customers. See Testing Accounts for more information.
  • Active customers are the owners of real-world accounts which are refreshed every evening through Finicity's daily aggregation process.

See Active Docs to experiment directly with the API.

Available services:

Customer Record

The following fields are available in a customer record:

Field Name Description
id The customer ID
username The customer's username, assigned by the partner (a unique identifier), following these rules:
  • minimum 6 characters
  • maximum 255 characters
  • Any mix of uppercase, lowercase, numeric, and special characters ! @ # $ % & * _ - +
firstName The customer's first name(s) / given name(s) (optional)
lastName The customer's last name(s) / surname(s) (optional)
type One of the values testingactive
createdDate A timestamp showing when the customer was added (see Handling Dates and Times)

Get Customers
GET /v1/customers?search=[text]&start=[index]&limit=[count]&type=[type]&username=[username]

Find all customers enrolled by the current partner, where the search text is found in the customer's username or any combination of firstName and lastName fields. If no search text is provided, return all customers.

Valid values for type are testingactive.

If the value of moreAvailable in the response is true, you can retrieve the next page of results by increasing the value of the start parameter in your next request:

  ...&start=6&limit=5

JSON Implementation

Request Details:

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Accept HTTP header  

application/json

search query  

Text to match, or leave empty to return all customers.

Must be URL-encoded (see Handling Spaces in Queries)

username query   Username for exact match. (Will return 0 or 1 <customer> records.) 
start query 1 Starting index for this page of results
limit query 25 Maximum number of entries for this page of results
type query   One of the values testing or active to return only customers of that type, or leave empty to return all customers.

Success: HTTP 200 (OK)

Example Requests:

GET https://api.finicity.com/aggregation/v1/customers
GET https://api.finicity.com/aggregation/v1/customers?username=rsmith
GET https://api.finicity.com/aggregation/v1/customers?search=doe+john
GET https://api.finicity.com/aggregation/v1/customers?search=john+doe
GET https://api.finicity.com/aggregation/v1/customers?search=smith&start=1&limit=2

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v1/customers?search=john+doe"

Response Details:

Field Name Description
found Total number of records matching search criteria
displaying Number of records in this response
moreAvailable true if this response does not contain the last record in the result set
customers List of customer records

Example Response:

{
"found": 7,
"displaying": 2,
"moreAvailable": true,
"customers": [
{
"id": 41442,
"username": "rsmith",
"firstName": "Ron",
"lastName": "Smith",
"type": "active",
"createdDate": 1412792539
},
{
  "id": 41463,
"username": "sbrown",
"firstName": "Smithie",
"lastName": "Brown",
"type": "active",
"createdDate": 1412884724
}
]
}

XML Implementation

Request Details:

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Accept HTTP header  

application/xml

search query  

Text to match, or leave empty to return all customers.

Must be URL-encoded (see Handling Spaces in Queries)

username query   Username for exact match. (Will return 0 or 1 <customer> records.)
start query 1 Starting index for this page of results
limit query 25 Maximum number of entries for this page of results
type query   One of the values testing or active to return only customers of that type, or leave empty to return all customers.

Success: HTTP 200 (OK)

Example Requests:

GET https://api.finicity.com/aggregation/v1/customers
GET https://api.finicity.com/aggregation/v1/customers?username=rsmith
GET https://api.finicity.com/aggregation/v1/customers?search=doe+john
GET https://api.finicity.com/aggregation/v1/customers?search=john+doe
GET https://api.finicity.com/aggregation/v1/customers?search=smith&start=1&limit=2

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v1/customers?search=john+doe"

Response Details:

XML Name Description
customers Root element
found Attribute giving the total number of records matching search criteria
displaying Attribute giving the number of records in this response
moreAvailable Attribute giving true if this response does not contain the last record in the result set
customer A customer record

Example Response:

<customers found="7" displaying="2" moreAvailable="true">
  <customer>
    <id>41442</id>
    <username>rsmith</username>
    <firstName>Ron</firstName>
    <lastName>Smith</lastName>
    <type>active</type>
    <createdDate>1412792539</createdDate>
  </customer>
  <customer>
    <id>41463</id>
    <username>sbrown</username>
    <firstName>Smithie</firstName>
    <lastName>Brown</lastName>
    <type>active</type>
    <createdDate>1412884724</createdDate>
  </customer>
</customers>

Get Customer
GET /v1/customers/{customerId}

Get details for the specified customer.

JSON Implementation

Request Details:

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Accept HTTP header  

application/json

customerId path  

ID of the customer to retrieve

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v1/customers/41442"

Response Details:

A single customer record.

Example Response:

{
"id": "41442", "username": "rsmith", "firstName": "Ron", "lastName": "Smith", "type": "active" "createdDate", "1412792539" }

XML Implementation

Request Details:

Parameter Type Default Description
Finicity-App-Key HTTP header   Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header   Token returned from Partner Authentication
Accept HTTP header  

application/xml

customerId path  

ID of the customer to retrieve

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" =H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v1/customers/41442"

Response Details:

An XML document containing one customer record.

Example Response:

<customer>
  <id>41442</id>
  <username>rsmith</username>
  <firstName>Ron</firstName>
  <lastName>Smith</lastName>
  <type>active</type>
  <createdDate>1412792539</createdDate>
</customer>

Add Testing Customer
POST /v1/customers/testing

Enroll a testing customer. A testing customer may only register accounts with FinBank (institution ID 101732). See Testing Accounts for more information.

Details: See Adding a Customer.

Add Customer
POST /v1/customers/active

Enroll an active customer (the actual owner of one or more real-world accounts). The customer's account transactions will be refreshed every night.

This service is not available from the Test Drive. Calls to this service before enrolling in a paid plan will return HTTP 429 (Too Many Requests).

Details: See Adding a Customer.

Adding a Customer

JSON Implementation

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Content-Type HTTP header

application/json

Accept HTTP header

application/json

username JSON field

The customer's username, assigned by the partner (a unique identifier), following these rules:

  • minimum 6 characters
  • maximum 255 characters
  • Any mix of uppercase, lowercase, numeric, and special characters ! @ # $ % & * _ - +
firstName JSON field

The customer's first name(s) / given name(s) (optional)

lastName JSON field

The customer's last name(s) / surname(s) (optional)

Success: HTTP 201 (Created)

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/testing
POST https://api.finicity.com/aggregation/v1/customers/active
{
"username": "USERNAME",
"firstName": "FIRST_NAME",
"lastName": "LAST_NAME"
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -H "Accept:application/json" -X POST "https://api.finicity.com/aggregation/v1/customers/testing" -d '{ "username": "USERNAME", "firstName": "FIRST_NAME", "lastName": "LAST_NAME" }'

Response Details:

Field Name Description
id The ID of the new customer record
createdDate A timestamp of when the customer was added (see Handling Dates and Times)

Example Response:

{
  "id": "41442",
  "createdDate": "1412792539"
}

XML Implementation

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Content-Type HTTP header

application/xml

Accept HTTP header

application/xml

customer XML element

Root element

username XML element

The customer's username, assigned by the partner (a unique identifier), following these rules:

  • minimum 6 characters
  • maximum 255 characters
  • Any mix of uppercase, lowercase, numeric, and special characters ! @ # $ % & * _ - +
firstName XML element

The customer's first name / given name(s) (optional)

lastName XML element

The customer's last name / surname(s) (optional)

Success: HTTP 201 (Created)

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/testing
POST https://api.finicity.com/aggregation/v1/customers/active
<customer>
<username>USERNAME</username>
<firstName>FIRST_NAME</firstName>
<lastName>LAST_NAME</lastName>
</customer>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -H "Accept:application/xml" -X POST "https://api.finicity.com/aggregation/v1/customers/testing" -d '<customer> <username>USERNAME</username> <firstName>FIRST_NAME</firstName> <lastName>LAST_NAME</lastName> </customer>'

Response Details:

XML Name Description
customer Root element
id The ID of the new customer record
createdDate A timestamp of when the customer was added (see Handling Dates and Times)

Example Response:

<customer>
  <id>41442</id>
  <createdDate>1412792539</createdDate>
</customer> 

Modify Customer
PUT /v1/customers/{customerId}

Modify the details for an enrolled customer. You must specify either <firstName> or <lastName> or both in the request.

JSON Implementation

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Content-Type HTTP header

application/json

customerId path

ID of the customer to modify

firstName JSON field

The customer's first name(s) / given name(s) (optional).

lastName JSON field

The customer's last name(s) / surname(s) (optional)

Success: HTTP 204 (No Content)

Example Request:

PUT https://api.finicity.com/aggregation/v1/customers/41442
{
"firstName": "FIRST_NAME",
"lastName": "LAST_NAME"
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -X PUT "https://api.finicity.com/aggregation/v1/customers/41442" -d '{ "firstName": "FIRST_NAME", "lastName": "LAST_NAME" }'

XML Implementation

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Content-Type HTTP header

application/xml

customerId path

ID of the customer to modify

customer XML element

Root element

firstName XML element

The customer's first name / given name(s) (optional).

lastName XML element

The customer's last name / surname(s) (optional)

Success: HTTP 204 (No Content)

Example Request:

PUT https://api.finicity.com/aggregation/v1/customers/41442
<customer>
<firstName>FIRST_NAME</firstName>
<lastName>LAST_NAME</lastName>
</customer>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -X PUT "https://api.finicity.com/aggregation/v1/customers/41442" -d '<customer> <firstName>FIRST_NAME</firstName> <lastName>LAST_NAME</lastName> </customer>'

Delete Customer
DELETE /v1/customers/{customerId}

Completely remove a customer from the system. This will remove the customer and all associated accounts, transactions, and aggregation support tickets.

(Note that the request and response is the same for JSON or XML clients.)

Use this service carefully! It will not pause for confirmation before performing the operation!

Request Details:

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
customerId path

ID of the customer to modify

Success: HTTP 204 (No Content)

Example Request:

DELETE https://api.finicity.com/aggregation/v1/customers/41442

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -X DELETE "https://api.finicity.com/aggregation/v1/customers/41442" -d ''
Have more questions? Submit a request

Comments

Powered by Zendesk