Canopy Servicing Core API

API Overview
Canopy allows you to easily manage credit products from a servicing and compliance perspective - whether newly launched or migrated from existing systems. Using Canopy, you can track balances and transactions for each customer of your product, both in real-time and historically. You can access and track information related to disputes, see how various policy and product changes would impact your customers, and readily generate compliance reports and minimize your risk with all real-time information always on hand.

Simply configure your product’s policies through our Policy Management Dashboard, and then you can immediately begin adding customer accounts and relying on Canopy for accurate servicing information.

This is the documentation for version 1.3 of the API. Last update on Oct 12, 2020.

Base URL
https://sandbox.canopyservicing.com

Getting Started

Get started in four easy steps.

1) Review the Authentication section to connect and experiment with our Sandbox environment.

2) Contact us to request Production API Keys and learn more about our business.

3) Configure policies
      a) For most uses, we recommend using the Policy Management Dashboard
      b) If you will be configuring many credit products programmatically or require niche configurations, you can also configure products in Canopy directly through our Policy Management API.

4) Once your product is configured and launched in Canopy, you have access to the full power of the Servicing API! You can take advantage of sample workflows provided by our team, or construct your own using this API documentation.


Authentication

To create your organization within Canopy, contact our team. Once created, review our API Users routes to handle all subsequent authentication-related activities, including inviting your team members to join your organization.


Authentication

Authenticate to use the appropriate environment (sandbox or production) within Canopy

Get all API users in your organization

Returns a list of all API users in your organization.

URL parameters
  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the products were as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses
  • 200 array[object]

    Array of API Users

    • api_user_id Required / string

      The unique ID in Canopy for this API user

    • organization_name Required / string

      The organization to which the API user belongs.

    • name_first string

      The first name of the API user.

    • name_last string

      The last name of the API user.

    • email Required / string(email)

      The email address of this API User

    • phone string(phonenumber)

      Phone number of the API user

    • role Required / string

      The role of this user in the API

      Values are SERVICING, OPERATIONS, and ADMIN.

  • 404

    No Api Users found

Definition
GET https://sandbox.canopyservicing.com/api_users
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/api_users \ -H "Content-Type: application/json"
Response example (200)
[ { "api_user_id": "44197ea2-eb78-4511-bcf2-bc28201f9c01", "organization_name": "Lever Card 3000", "name_first": "Analise", "name_last": "Goldberg", "email": "marissa@globex.com", "phone": "1-123-456-7890", "role": "SERVICING" } ]
Response example (404)
No content

Invite a new API user to Canopy

When you create a new API user via this POST request, an email invite will be sent for the new user to join your organization. The email invite includes a link with a unique token that will allow the new user to register to join your team in Canopy.

Body
  • role Required / number

    A role to be made accessible for the user. Contact our team for a full list of options.

  • email Required / string(email)

    The email address of this API User

Responses
  • 200 object

    Successfully invited a new user

    • email Required / string(email)

      The email address of this API User

    • created_at Required / string(date-time)

      The Date-Time which the invitation was created in the API

    • expires_at Required / string(date-time)

      The Date-Time which the invitation expires

Definition
POST https://sandbox.canopyservicing.com/api_users
cURL example
curl \ -X POST https://sandbox.canopyservicing.com/api_users \ -H "Content-Type: application/json" \ -d '{"role":3,"email":"marissa@globex.com"}'
Request payload example
{ "role": 3, "email": "marissa@globex.com" }
Response example (200)
{ "email": "marissa@globex.com", "created_at": "2018-06-20 09:12:30 UTC", "expires_at": "2018-06-21 09:12:30 UTC" }

Log in as an API user

When provided appropriate credentials, this route signs in an API user.

Body
  • email Required / string(email)

    The email address of the API User logging in

  • password Required / string

    The password of the user logging in.

Responses
  • 200 object

    Successfully logged in as an API user

    • api_user_id Required / string

      The unique ID in Canopy for this API user

    • organization_name Required / string

      The organization to which the API user belongs.

    • first_name string

      The first name of the API user.

    • last_name string

      The last name of the API user.

    • email Required / string(email)

      The email address of this API User

    • phone string(phonenumber)

      Phone number of the API user

    • role Required / string

      The role of this user in the API

      Values are SERVICING, OPERATIONS, and ADMIN.

    • token Required / string

      The unique token to be included as an x-api-key header in all subsequent requests as this user.

Definition
POST https://sandbox.canopyservicing.com/api_users/login
cURL example
curl \ -X POST https://sandbox.canopyservicing.com/api_users/login \ -H "Content-Type: application/json" \ -d '{"email":"marissa@globex.com","password":"secretPassword123!"}'
Request payload example
{ "email": "marissa@globex.com", "password": "secretPassword123!" }
Response example (200)
{ "api_user_id": "44197ea2-eb78-4511-bcf2-bc28201f9c01", "organization_name": "Lever Card 3000", "first_name": "Analise", "last_name": "Goldberg", "email": "marissa@globex.com", "phone": "1-123-456-7890", "role": "SERVICING", "token": "string" }

Update the password for an API User

When provided appropriate credentials, this route changes an API User's password.

Body
  • current_password Required / string

    The password of the user changing their password.

  • new_password Required / string

    The new password of the user changing their password.

  • token Required / string

    A unique token included in Canopy's reset password email.

Responses
  • 200 object

    Successfully logged in as an API user

    • api_user_id Required / string

      The unique ID in Canopy for this API user

    • organization_name Required / string

      The organization to which the API user belongs.

    • first_name string

      The first name of the API user.

    • last_name string

      The last name of the API user.

    • email Required / string(email)

      The email address of this API User

    • phone string(phonenumber)

      Phone number of the API user

    • role Required / string

      The role of this user in the API

      Values are SERVICING, OPERATIONS, and ADMIN.

Definition
PUT https://sandbox.canopyservicing.com/api_users/password
cURL example
curl \ -X PUT https://sandbox.canopyservicing.com/api_users/password \ -H "Content-Type: application/json" \ -d '{"current_password":"currentSecretPassword123!","new_password":"newSecretPassword123!","token":"string"}'
Request payload example
{ "current_password": "currentSecretPassword123!", "new_password": "newSecretPassword123!", "token": "string" }
Response example (200)
{ "api_user_id": "44197ea2-eb78-4511-bcf2-bc28201f9c01", "organization_name": "Lever Card 3000", "first_name": "Analise", "last_name": "Goldberg", "email": "marissa@globex.com", "phone": "1-123-456-7890", "role": "SERVICING" }

Complete registration for an invited API user

When provided appropriate credentials, this route updates an API user's information for registration.

Body
  • email_confirm Required / string(email)

    The email address of the user being updated.

  • new_password Required / string

    The new password of the API user.

  • name_first Required / string

    The first name of the API user.

  • name_last Required / string

    The last name of the API user.

  • phone Required / string(phonenumber)

    The phone number to add to the API User's information.

  • token Required / string

    A unique token included in Canopy's register user email.

Responses
  • 200 object

    API user successfully registered

    • api_user_id Required / string

      The unique ID in Canopy for this API user

    • organization_name Required / string

      The organization to which the API user belongs.

    • name_first string

      The first name of the API user.

    • name_last string

      The last name of the API user.

    • email Required / string(email)

      The email address of this API User

    • phone string(phonenumber)

      Phone number of the API user

    • role Required / string

      The role of this user in the API

      Values are SERVICING, OPERATIONS, and ADMIN.

Definition
PUT https://sandbox.canopyservicing.com/api_users/register
cURL example
curl \ -X PUT https://sandbox.canopyservicing.com/api_users/register \ -H "Content-Type: application/json" \ -d '{"email_confirm":"harriet@acmecorporation.com","new_password":"newSecretPassword123!","name_first":"Karl","name_last":"Martins","phone":"1-222-222-2222","token":"string"}'
Request payload example
{ "email_confirm": "harriet@acmecorporation.com", "new_password": "newSecretPassword123!", "name_first": "Karl", "name_last": "Martins", "phone": "1-222-222-2222", "token": "string" }
Response example (200)
{ "api_user_id": "44197ea2-eb78-4511-bcf2-bc28201f9c01", "organization_name": "Lever Card 3000", "name_first": "Analise", "name_last": "Goldberg", "email": "marissa@globex.com", "phone": "1-123-456-7890", "role": "SERVICING" }

Get summary info for an API user

Get all summarized information pertaining to the API user making the request.

URL parameters
  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the api user's info was as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses
  • 200 object

    API User

    • api_user_id Required / string

      The unique ID in Canopy for this API user

    • organization_name Required / string

      The organization to which the API user belongs.

    • name_first string

      The first name of the API user.

    • name_last string

      The last name of the API user.

    • email Required / string(email)

      The email address of this API User

    • phone string(phonenumber)

      Phone number of the API user

    • role Required / string

      The role of this user in the API

      Values are SERVICING, OPERATIONS, and ADMIN.

  • 404

    No Products

Definition
GET https://sandbox.canopyservicing.com/api_users/summary
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/api_users/summary \ -H "Content-Type: application/json"
Response example (200)
{ "api_user_id": "44197ea2-eb78-4511-bcf2-bc28201f9c01", "organization_name": "Lever Card 3000", "name_first": "Analise", "name_last": "Goldberg", "email": "marissa@globex.com", "phone": "1-123-456-7890", "role": "SERVICING" }
Response example (404)
No content

Products

Create and launch credit products within the Canopy system.

Get all available products

If you have configured and launched multiple products within Canopy, retrieve information related to all of your configured products at once.

URL parameters
  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the products were as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses
  • 200 array[object]

    Array of Products

    • product_id Required / string(uuid)

      The Canopy-generated ID for the product.

    • name Required / string

      Name of Product, i.e. Express Card.

    • description Required / string

      Description of the Product.

    • created_at Required / string(date-time)

      The Date-Time that this product was created on the server.

    • type Required / string

      The Type of Product

      Values are CREDIT.

    • status Required / string

      The status of a Product (i.e. live). Currently, all configured products are in the live state.

      Values are VALID.

    • policies Required / object

      An object of policies that drive product behavior.

      • policies.base_policy_config object

        A base group of policies that define a Product

        • policies.base_policy_config.min_pay Required / object

          The configured minimum payment required for a given pay period.

          • policies.base_policy_config.min_pay.percentage number

            The percentage of total balance calculated for min pay. (i.e. 20 means 20%)

        • policies.base_policy_config.billing_cycle Required / object

          The Billing Cycle Object

          • policies.base_policy_config.billing_cycle.period Required / string(interval)

            The length of the billing cycle. after which a statement is generated, and a due date assigned. IE '1 month' '3 months' or '7 days' (most common is monthly)

          • policies.base_policy_config.billing_cycle.billing_due_date_interval Required / string(interval)

            The amount of time you would like between the statement cut and the billing due date. IE '25 days'. Cannot exceed the start of the next billing cycle and generally needs to be at least 21 days.

        • policies.base_policy_config.interest_policies Required / object

          The Interest Policy Object

          • policies.base_policy_config.interest_policies.type Required / string

            Values are compound.

          • policies.base_policy_config.interest_policies.method Required / string

            The actual base formula used to calculate and assign interest.

            Values are average daily balance.

          • policies.base_policy_config.interest_policies.day_calc_type Required / string

            Affects the base calculation by determining how many days there are in a given year.

            Values are 365.

          • policies.base_policy_config.interest_policies.interest_calc_time Required / string(date-time)

            Interest for this policy is calculated at this time every X interval.

        • policies.base_policy_config.close_of_business_and_timezone Required / string(date-time)

          Time and timezone of the close of business. This is used for statement cuts and partner-level and issuing bank-level reconciliation

    • product_summary Required / object

      Summary of product information

      • product_summary.accounts_overview object
        • product_summary.accounts_overview.account_count_total integer

          Total number of accounts under the product.

        • product_summary.accounts_overview.account_count_delinquent integer

          Total number of delinquent accounts under the product.

      • product_summary.total_credit_issued_cents integer

        Total amount (in cents) of credit issued to accounts under the product.

      • product_summary.utilization_rate number

        The percent utilization rate of the product.

      • product_summary.product_id string(uuid)

        The Canopy-generated ID for the product.

      • product_summary.effective_as_of_date string(date-time)

        The Date-Time you would like the system to return the data as of. IE "tell me what the product information was as if I had asked on 2020-01-20 00:00:00 EST". If empty defaults to current time.

    • default_attributes Required / object
      • default_attributes.rate Required / number

        The percent default rate for this interest policy (i.e. 3.2 means a 3.2% rate). This default rate can be overridden on a per-account basis if a rate is selected at the time of assigning an account to a product. Rates for an account can also be updated post-account creation.

      • default_attributes.credit_limit_cents Required / integer

        The default maximum principal credit (in cents) available for a customer account. This default limit can be overridden on a per-account basis if a credit_limit is selected at the time of assigning an account to a product. Credit limits for an account can also be updated post-account creation.

  • 404

    No Products

Definition
GET https://sandbox.canopyservicing.com/products
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/products \ -H "Content-Type: application/json"
Response example (200)
[ { "product_id": "8fe1eb97-d640-45d6-83bb-f415ddf97a51", "name": "Blue Cash Express", "description": "Student credit card.", "created_at": "2019-03-20 09:12:28 UTC", "type": "CREDIT", "status": "VALID", "policies": { "base_policy_config": { "min_pay": { "percentage": "20" }, "billing_cycle": { "period": "1 month", "billing_due_date_interval": "25 days" }, "interest_policies": { "type": "compound", "method": "average daily balance", "day_calc_type": "365", "interest_calc_time": 18000 }, "close_of_business_and_timezone": "2020-03-20 09:12:28 UTC" } }, "product_summary": { "accounts_overview": { "account_count_total": 10005, "account_count_delinquent": 200 }, "total_credit_issued_cents": 25500000, "utilization_rate": 30.34, "product_id": "ca3cf4e9-5048-4461-a763-8f67b46dfd4d", "effective_as_of_date": "2017-06-20 09:12:14 UTC" }, "default_attributes": { "rate": 3.2, "credit_limit_cents": 600000 } } ]
Response example (404)
No content

Create a new product

At its core, Canopy allows you to create credit products that meet the specific needs of your users. We offer robust options to configure these products within our system.

For most use cases, we recommend configuring products by using the Policy Management Dashboard; however, you can also configure and manage products programmatically.

Request body for creating a new product.

The following fields are minimum requirements for products to be published with the live status:
- name
- default_rate
- default_credit_limit_cents
policies (with an appropriate Base Policy Configuration)

Body
  • name Required / string

    The Name of the Product

  • type string

    The Type of Product. If not included, defaults to credit

    Values are credit.

  • default_rate number

    The percentage default rate for accounts created under this interest policy (i.e. 5.2 indicates a 5.2% interest rate). You may customize rates for each account by overriding this default rate at the time of account creation or updating the rate for a given account.

  • default_credit_limit_cents integer

    The default total oustanding amout of money (in cents) that an account created under this product could borrow. You may customize rates for each account by overriding this default rate at the time of account creation or updating the rate for a given account.

  • description string

    Description of the Product.

  • policies object

    An Object of policies that drive Product behaviour.

    • policies.base_policy_config object

      A base group of policies that define a Product

      • policies.base_policy_config.min_pay Required / object

        The configured minimum payment required for a given pay period.

        • policies.base_policy_config.min_pay.percentage number

          The percentage of total balance calculated for min pay. (i.e. 20 means 20%)

      • policies.base_policy_config.billing_cycle Required / object

        The Billing Cycle Object

        • policies.base_policy_config.billing_cycle.period Required / string(interval)

          The length of the billing cycle. after which a statement is generated, and a due date assigned. IE '1 month' '3 months' or '7 days' (most common is monthly)

        • policies.base_policy_config.billing_cycle.billing_due_date_interval Required / string(interval)

          The amount of time you would like between the statement cut and the billing due date. IE '25 days'. Cannot exceed the start of the next billing cycle and generally needs to be at least 21 days.

      • policies.base_policy_config.interest_policies Required / object

        The Interest Policy Object

        • policies.base_policy_config.interest_policies.type Required / string

          Values are compound.

        • policies.base_policy_config.interest_policies.method Required / string

          The actual base formula used to calculate and assign interest.

          Values are average daily balance.

        • policies.base_policy_config.interest_policies.day_calc_type Required / string

          Affects the base calculation by determining how many days there are in a given year.

          Values are 365.

        • policies.base_policy_config.interest_policies.interest_calc_time Required / string(date-time)

          Interest for this policy is calculated at this time every X interval.

      • policies.base_policy_config.close_of_business_and_timezone Required / string(date-time)

        Time and timezone of the close of business. This is used for statement cuts and partner-level and issuing bank-level reconciliation

Responses
  • 204 object

    Product Created

    • name string

      The name of the product

    • product_id string(uuid)

      An ID for your newly created product, generated by Canopy.

    • status string

      The Status of a Product (i.e. live or draft). Products with the draft status require additional policy configurations to launch.

    • network string

      The network, if applicable, on which the product is issued.

      Values are visa, mastercard, american express, and discover.

  • 422

    Invalid input

Definition
POST https://sandbox.canopyservicing.com/products
cURL example
curl \ -X POST https://sandbox.canopyservicing.com/products \ -H "Content-Type: application/json" \ -d '{"name":"Blue Cash Express","type":"credit","default_rate":"5.2","default_credit_limit_cents":"700000","description":"Consumer credit card","policies":{"base_policy_config":{"min_pay":{"percentage":"20"},"billing_cycle":{"period":"1 month","billing_due_date_interval":"25 days"},"interest_policies":{"type":"compound","method":"average daily balance","day_calc_type":"365","interest_calc_time":18000},"close_of_business_and_timezone":"2020-03-20T09:12:28Z"}}}'
Request payload example
{ "name": "Blue Cash Express", "type": "credit", "default_rate": "5.2", "default_credit_limit_cents": "700000", "description": "Consumer credit card", "policies": { "base_policy_config": { "min_pay": { "percentage": "20" }, "billing_cycle": { "period": "1 month", "billing_due_date_interval": "25 days" }, "interest_policies": { "type": "compound", "method": "average daily balance", "day_calc_type": "365", "interest_calc_time": 18000 }, "close_of_business_and_timezone": "2020-03-20 09:12:28 UTC" } } }
Response example (204)
{ "name": "Blue Cash Express", "product_id": "44c7298f-b515-4dc3-84b2-21186e1b1d3b", "status": "live", "network": "visa" }
Response example (422)
No content

Get info on a particular product

Using the product_id which was generated when the product was launched, retrieve information pertaining to a specific product.

URL parameters
  • product_id Required / string(uuid)

    Product ID

  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the Products were as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses
  • 200 object

    Product

    • product_id Required / string(uuid)

      The Canopy-generated ID for the product.

    • name Required / string

      Name of Product, i.e. Express Card.

    • description Required / string

      Description of the Product.

    • created_at Required / string(date-time)

      The Date-Time that this product was created on the server.

    • type Required / string

      The Type of Product

      Values are CREDIT.

    • status Required / string

      The status of a Product (i.e. live). Currently, all configured products are in the live state.

      Values are VALID.

    • policies Required / object

      An object of policies that drive product behavior.

      • policies.base_policy_config object

        A base group of policies that define a Product

        • policies.base_policy_config.min_pay Required / object

          The configured minimum payment required for a given pay period.

          • policies.base_policy_config.min_pay.percentage number

            The percentage of total balance calculated for min pay. (i.e. 20 means 20%)

        • policies.base_policy_config.billing_cycle Required / object

          The Billing Cycle Object

          • policies.base_policy_config.billing_cycle.period Required / string(interval)

            The length of the billing cycle. after which a statement is generated, and a due date assigned. IE '1 month' '3 months' or '7 days' (most common is monthly)

          • policies.base_policy_config.billing_cycle.billing_due_date_interval Required / string(interval)

            The amount of time you would like between the statement cut and the billing due date. IE '25 days'. Cannot exceed the start of the next billing cycle and generally needs to be at least 21 days.

        • policies.base_policy_config.interest_policies Required / object

          The Interest Policy Object

          • policies.base_policy_config.interest_policies.type Required / string

            Values are compound.

          • policies.base_policy_config.interest_policies.method Required / string

            The actual base formula used to calculate and assign interest.

            Values are average daily balance.

          • policies.base_policy_config.interest_policies.day_calc_type Required / string

            Affects the base calculation by determining how many days there are in a given year.

            Values are 365.

          • policies.base_policy_config.interest_policies.interest_calc_time Required / string(date-time)

            Interest for this policy is calculated at this time every X interval.

        • policies.base_policy_config.close_of_business_and_timezone Required / string(date-time)

          Time and timezone of the close of business. This is used for statement cuts and partner-level and issuing bank-level reconciliation

    • product_summary Required / object

      Summary of product information

      • product_summary.accounts_overview object
        • product_summary.accounts_overview.account_count_total integer

          Total number of accounts under the product.

        • product_summary.accounts_overview.account_count_delinquent integer

          Total number of delinquent accounts under the product.

      • product_summary.total_credit_issued_cents integer

        Total amount (in cents) of credit issued to accounts under the product.

      • product_summary.utilization_rate number

        The percent utilization rate of the product.

      • product_summary.product_id string(uuid)

        The Canopy-generated ID for the product.

      • product_summary.effective_as_of_date string(date-time)

        The Date-Time you would like the system to return the data as of. IE "tell me what the product information was as if I had asked on 2020-01-20 00:00:00 EST". If empty defaults to current time.

    • default_attributes Required / object
      • default_attributes.rate Required / number

        The percent default rate for this interest policy (i.e. 3.2 means a 3.2% rate). This default rate can be overridden on a per-account basis if a rate is selected at the time of assigning an account to a product. Rates for an account can also be updated post-account creation.

      • default_attributes.credit_limit_cents Required / integer

        The default maximum principal credit (in cents) available for a customer account. This default limit can be overridden on a per-account basis if a credit_limit is selected at the time of assigning an account to a product. Credit limits for an account can also be updated post-account creation.

  • 404

    No Products found

Definition
GET https://sandbox.canopyservicing.com/products/{product_id}
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/products/{product_id} \ -H "Content-Type: application/json"
Response example (200)
{ "product_id": "8fe1eb97-d640-45d6-83bb-f415ddf97a51", "name": "Blue Cash Express", "description": "Student credit card.", "created_at": "2019-03-20 09:12:28 UTC", "type": "CREDIT", "status": "VALID", "policies": { "base_policy_config": { "min_pay": { "percentage": "20" }, "billing_cycle": { "period": "1 month", "billing_due_date_interval": "25 days" }, "interest_policies": { "type": "compound", "method": "average daily balance", "day_calc_type": "365", "interest_calc_time": 18000 }, "close_of_business_and_timezone": "2020-03-20 09:12:28 UTC" } }, "product_summary": { "accounts_overview": { "account_count_total": 10005, "account_count_delinquent": 200 }, "total_credit_issued_cents": 25500000, "utilization_rate": 30.34, "product_id": "ca3cf4e9-5048-4461-a763-8f67b46dfd4d", "effective_as_of_date": "2017-06-20 09:12:14 UTC" }, "default_attributes": { "rate": 3.2, "credit_limit_cents": 600000 } }
Response example (404)
No content

Get all accounts created under a specific product

Returns all accounts created under a specific product. Results are paginated.

URL parameters
  • offset integer

    The zero-indexed starting point for paginated account requests sorted by account created date.

  • limit integer

    The maximum number of accounts to be returned. Defaults to 100.

Responses
  • 200 object
    • current_accounts Required / array[string](uuid)

      Account ID

  • 404

    Account not found

Definition
GET https://sandbox.canopyservicing.com/products/{product_id}/accounts
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/products/{product_id}/accounts \ -H "Content-Type: application/json"
Response example (200)
{ "current_accounts": [ "5e860ad7-5fff-4130-844c-ec9ead83a025" ] }
Response example (404)
No content

Customers

Onboard customers into your system, so they can begin using your credit products

Get all accounts for all customers

Returns all accounts from the perspective of each customer. For instance, if one account has two customers, these are reflected as two separate items in the response array. Similarly, if one customer has multiple accounts, each account is reflected as a separate item in the response array.

URL parameters
  • offset integer

    The zero-indexed starting point for paginated account requests sorted by account created date.

  • limit integer

    The maximum number of accounts to be returned. Defaults to 100.

  • search_query string

    A search query to be applied to results before the customer accounts list is returned. Search by name, phone number, account ID, or SSN last-four digits.

  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the customers were as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses
  • 200 object

    Array of Customers and their corresponding Accounts

    • customer_accounts array[object]

      An array of information for all customer-account correspondences within the requested range.

      • customer_accounts.account object
        • customer_accounts.account.account_id Required / string(uuid)

          This is generated by Canopy. A unique ID for the account.

        • customer_accounts.account.account_status Required / string

          The Status of the Account. Active upon account creation.

        • customer_accounts.account.account_status_subtype Required / string

          The subtype of the Status of the Account. Null upon account creation.

        • customer_accounts.account.effective_at Required / string(date-time)

          The Date-Time that this account became/becomes active.

        • customer_accounts.account.created_at Required / string(date-time)

          The Date-Time which the account was created in the API.

        • customer_accounts.account.product Required / object
          • customer_accounts.account.product.product_id Required / string(uuid)

            The Canopy-generated ID for the product.

          • customer_accounts.account.product.name Required / string

            Name of Product, i.e. Express Card.

          • customer_accounts.account.product.description Required / string

            Description of the Product.

          • customer_accounts.account.product.created_at Required / string(date-time)

            The Date-Time that this product was created on the server.

          • customer_accounts.account.product.type Required / string

            The Type of Product

            Values are CREDIT.

          • customer_accounts.account.product.status Required / string

            The status of a Product (i.e. live). Currently, all configured products are in the live state.

            Values are VALID.

          • customer_accounts.account.product.policies Required / object

            An object of policies that drive product behavior.

            • customer_accounts.account.product.policies.base_policy_config object

              A base group of policies that define a Product

              • customer_accounts.account.product.policies.base_policy_config.min_pay Required / object

                The configured minimum payment required for a given pay period.

                • customer_accounts.account.product.policies.base_policy_config.min_pay.percentage number

                  The percentage of total balance calculated for min pay. (i.e. 20 means 20%)

              • customer_accounts.account.product.policies.base_policy_config.billing_cycle Required / object

                The Billing Cycle Object

                • customer_accounts.account.product.policies.base_policy_config.billing_cycle.period Required / string(interval)

                  The length of the billing cycle. after which a statement is generated, and a due date assigned. IE '1 month' '3 months' or '7 days' (most common is monthly)

                • customer_accounts.account.product.policies.base_policy_config.billing_cycle.billing_due_date_interval Required / string(interval)

                  The amount of time you would like between the statement cut and the billing due date. IE '25 days'. Cannot exceed the start of the next billing cycle and generally needs to be at least 21 days.

              • customer_accounts.account.product.policies.base_policy_config.interest_policies Required / object

                The Interest Policy Object

                • customer_accounts.account.product.policies.base_policy_config.interest_policies.type Required / string

                  Values are compound.

                • customer_accounts.account.product.policies.base_policy_config.interest_policies.method Required / string

                  The actual base formula used to calculate and assign interest.

                  Values are average daily balance.

                • customer_accounts.account.product.policies.base_policy_config.interest_policies.day_calc_type Required / string

                  Affects the base calculation by determining how many days there are in a given year.

                  Values are 365.

                • customer_accounts.account.product.policies.base_policy_config.interest_policies.interest_calc_time Required / string(date-time)

                  Interest for this policy is calculated at this time every X interval.

              • customer_accounts.account.product.policies.base_policy_config.close_of_business_and_timezone Required / string(date-time)

                Time and timezone of the close of business. This is used for statement cuts and partner-level and issuing bank-level reconciliation

          • customer_accounts.account.product.product_summary Required / object

            Summary of product information

            • customer_accounts.account.product.product_summary.accounts_overview object
              • customer_accounts.account.product.product_summary.accounts_overview.account_count_total integer

                Total number of accounts under the product.

              • customer_accounts.account.product.product_summary.accounts_overview.account_count_delinquent integer

                Total number of delinquent accounts under the product.

            • customer_accounts.account.product.product_summary.total_credit_issued_cents integer

              Total amount (in cents) of credit issued to accounts under the product.

            • customer_accounts.account.product.product_summary.utilization_rate number

              The percent utilization rate of the product.

            • customer_accounts.account.product.product_summary.product_id string(uuid)

              The Canopy-generated ID for the product.

            • customer_accounts.account.product.product_summary.effective_as_of_date string(date-time)

              The Date-Time you would like the system to return the data as of. IE "tell me what the product information was as if I had asked on 2020-01-20 00:00:00 EST". If empty defaults to current time.

          • customer_accounts.account.product.default_attributes Required / object
            • customer_accounts.account.product.default_attributes.rate Required / number

              The percent default rate for this interest policy (i.e. 3.2 means a 3.2% rate). This default rate can be overridden on a per-account basis if a rate is selected at the time of assigning an account to a product. Rates for an account can also be updated post-account creation.

            • customer_accounts.account.product.default_attributes.credit_limit_cents Required / integer

              The default maximum principal credit (in cents) available for a customer account. This default limit can be overridden on a per-account basis if a credit_limit is selected at the time of assigning an account to a product. Credit limits for an account can also be updated post-account creation.

        • customer_accounts.account.external_account_ids array[object]

          An Array of External Account IDs. These should be used to connect accounts created in Canopy to Users in your system and any connected external systems.

          • customer_accounts.account.external_account_ids.name string

            Name of the External Party

          • customer_accounts.account.external_account_ids.id string

            External Account ID

        • customer_accounts.account.total_balance Required / number

          The total balance (in cents) associated with the account.

        • customer_accounts.account.credit_limit_cents Required / integer

          Total Amount (in cents) that this account can borrow.

        • customer_accounts.account.rate Required / number

          The percentage interest applied to the account (i.e. 6.2 means 6.2%)

        • customer_accounts.account.available_credit_balance Required / number

          The total available credit balance (in cents) for the account.

      • customer_accounts.customer object
        • customer_accounts.customer.customer_id string(uuid)

          A Canopy-generated unique ID for the customer

        • customer_accounts.customer.name_prefix string

          Prefix to the customer's name

        • customer_accounts.customer.name_first string

          Customer's first name

        • customer_accounts.customer.name_middle string

          Customer's middle name

        • customer_accounts.customer.name_last string

          Customer's last name

        • customer_accounts.customer.name_suffix string

          Prefix to the customer's name

        • customer_accounts.customer.phone_number string(phonenumber)

          Phone number of the customer

        • customer_accounts.customer.address_line_one string

          Address line one

        • customer_accounts.customer.address_line_two string

          Address line two

        • customer_accounts.customer.address_city string

          Address city

        • customer_accounts.customer.address_state string

          Address state

        • customer_accounts.customer.address_zip string

          Address zip code

        • customer_accounts.customer.ssn string

          Social security number of the customer

        • customer_accounts.customer.email string(email)

          The email address of this customer

        • customer_accounts.customer.date_of_birth string(date-time)

          Customer's date of birth

      • customer_accounts.customers array[object]

        An array of information for all customers within the requested range.

        • customer_accounts.customers.customer_id string(uuid)

          A Canopy-generated unique ID for the customer

        • customer_accounts.customers.name_prefix string

          Prefix to the customer's name

        • customer_accounts.customers.name_first string

          Customer's first name

        • customer_accounts.customers.name_middle string

          Customer's middle name

        • customer_accounts.customers.name_last string

          Customer's last name

        • customer_accounts.customers.name_suffix string

          Prefix to the customer's name

        • customer_accounts.customers.phone_number string(phonenumber)

          Phone number of the customer

        • customer_accounts.customers.address_line_one string

          Address line one

        • customer_accounts.customers.address_line_two string

          Address line two

        • customer_accounts.customers.address_city string

          Address city

        • customer_accounts.customers.address_state string

          Address state

        • customer_accounts.customers.address_zip string

          Address zip code

        • customer_accounts.customers.ssn string

          Social security number of the customer

        • customer_accounts.customers.email string(email)

          The email address of this customer

        • customer_accounts.customers.date_of_birth string(date-time)

          Customer's date of birth

      • customer_accounts.customer_account_role string

        The role of the customer for the account.

        Values are primary and secondary.

      • customer_accounts.customer_account_pan string

        A unique number for the customer on the account. For instance, a credit card number. If none is provided, a Canopy-generated ID can be used.

    • total_customer_account_count integer

      Total number of unique customer-account correspondences

  • 404

    Unable to get customers

Definition
GET https://sandbox.canopyservicing.com/customers/accounts
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/customers/accounts \ -H "Content-Type: application/json"
Response example (200)
{ "customer_accounts": [ { "account": { "account_id": "5fb3a288-5f6c-440f-b079-b06c828b7768", "account_status": "suspended", "account_status_subtype": "suspended-bankruptcy", "effective_at": "2018-03-20 09:12:28 UTC", "created_at": "2017-06-20 09:12:14 UTC", "product": { "product_id": "8fe1eb97-d640-45d6-83bb-f415ddf97a51", "name": "Blue Cash Express", "description": "Student credit card.", "created_at": "2019-03-20 09:12:28 UTC", "type": "CREDIT", "status": "VALID", "policies": { "base_policy_config": { "min_pay": { "percentage": "20" }, "billing_cycle": { "period": "1 month", "billing_due_date_interval": "25 days" }, "interest_policies": { "type": "compound", "method": "average daily balance", "day_calc_type": "365", "interest_calc_time": 18000 }, "close_of_business_and_timezone": "2020-03-20 09:12:28 UTC" } }, "product_summary": { "accounts_overview": { "account_count_total": 10005, "account_count_delinquent": 200 }, "total_credit_issued_cents": 25500000, "utilization_rate": 30.34, "product_id": "ca3cf4e9-5048-4461-a763-8f67b46dfd4d", "effective_as_of_date": "2017-06-20 09:12:14 UTC" }, "default_attributes": { "rate": 3.2, "credit_limit_cents": 600000 } }, "external_account_ids": [ { "name": "Umbrella Corporation", "id": "22445702-a389-431f-927d-07b8d0750787" } ], "total_balance": "300000", "credit_limit_cents": "400000", "rate": "6.2", "available_credit_balance": "100000" }, "customer": { "customer_id": "78e1bae0-b7dd-4626-bcda-9d7e7b81be30", "name_prefix": "Dr.", "name_first": "Miriam", "name_middle": "Louise", "name_last": "Trevino", "name_suffix": "Jr", "phone_number": "555-555-5555", "address_line_one": "12 Strawberry Road", "address_line_two": "Suite 101", "address_city": "Atlanta", "address_state": "GA", "address_zip": "99999-1000", "ssn": "888-88-8888", "email": "marissa@protonmail.com", "date_of_birth": "2018-06-20 09:12:30 UTC" }, "customers": [ { "customer_id": "78e1bae0-b7dd-4626-bcda-9d7e7b81be30", "name_prefix": "Dr.", "name_first": "Miriam", "name_middle": "Louise", "name_last": "Trevino", "name_suffix": "Jr", "phone_number": "555-555-5555", "address_line_one": "12 Strawberry Road", "address_line_two": "Suite 101", "address_city": "Atlanta", "address_state": "GA", "address_zip": "99999-1000", "ssn": "888-88-8888", "email": "marissa@protonmail.com", "date_of_birth": "2018-06-20 09:12:30 UTC" } ], "customer_account_role": "primary", "customer_account_pan": "4465220133024156" } ], "total_customer_account_count": 42 }
Response example (404)
No content

Create a new customer

Customer can be created within Canopy with attached data managed in a secure and compliant way to facilitate providing the best service for products created through Canopy.

Body
  • name_prefix string

    Prefix to the customer's name

  • name_first string

    Customer's first name

  • name_middle string

    Customer's middle name

  • name_last string

    Customer's last name

  • name_suffix string

    Prefix to the customer's name

  • phone_number string(phonenumber)

    Phone number of the customer

  • address_line_one string

    Address line one

  • address_line_two string

    Address line two

  • address_city string

    Address city

  • address_state string

    Address state

  • address_zip string

    Address zip code

  • ssn string

    Social security number of the customer

  • email string(email)

    The email address of this Customer

  • date_of_birth string(date-time)

    Customer's date of birth

  • accounts array[object]

    An array of existing accounts to which this Customer should be assigned.

    If left empty, the customer will not be assigned to any accounts, and can be later assigned to an account via the Update an existing customer route.

    Customers only become meaningful agents in Canopy's servicing system once they are assigned to accounts.

    • accounts.account_id string(uuid)

      This is generated by Canopy. A unique ID for the account.

    • accounts.customer_account_role string

      The role of the customer for the account.

      Values are primary and secondary.

    • accounts.customer_account_pan string

      A unique number for the customer on the account. For instance, a credit card number. If none is provided, a Canopy-generated ID can be used.

Responses
  • 200 object

    New Customer Created

    • customer_id string(uuid)

      A Canopy-generated unique ID for the customer

    • name_prefix string

      Prefix to the customer's name

    • name_first string

      Customer's first name

    • name_middle string

      Customer's middle name

    • name_last string

      Customer's last name

    • name_suffix string

      Prefix to the customer's name

    • phone_number string(phonenumber)

      Phone number of the customer

    • address_line_one string

      Address line one

    • address_line_two string

      Address line two

    • address_city string

      Address city

    • address_state string

      Address state

    • address_zip string

      Address zip code

    • ssn string

      Social security number of the customer

    • email string(email)

      The email address of this customer

    • date_of_birth string(date-time)

      Customer's date of birth

Definition
POST https://sandbox.canopyservicing.com/customers
cURL example
curl \ -X POST https://sandbox.canopyservicing.com/customers \ -H "Content-Type: application/json" \ -d '{"name_prefix":"Dr.","name_first":"Miriam","name_middle":"Louise","name_last":"Trevino","name_suffix":"Jr","phone_number":"555-555-5555","address_line_one":"12 Strawberry Road","address_line_two":"Suite 101","address_city":"Atlanta","address_state":"GA","address_zip":"99999-1000","ssn":"888-88-8888","email":"marissa@protonmail.com","date_of_birth":"2018-06-20T09:12:30Z","accounts":[{"account_id":"5fb3a288-5f6c-440f-b079-b06c828b7768","customer_account_role":"primary","customer_account_pan":"...}'
Request payload example
{ "name_prefix": "Dr.", "name_first": "Miriam", "name_middle": "Louise", "name_last": "Trevino", "name_suffix": "Jr", "phone_number": "555-555-5555", "address_line_one": "12 Strawberry Road", "address_line_two": "Suite 101", "address_city": "Atlanta", "address_state": "GA", "address_zip": "99999-1000", "ssn": "888-88-8888", "email": "marissa@protonmail.com", "date_of_birth": "2018-06-20 09:12:30 UTC", "accounts": [ { "account_id": "5fb3a288-5f6c-440f-b079-b06c828b7768", "customer_account_role": "primary", "customer_account_pan": "4465220133024156" } ] }
Response example (200)
{ "customer_id": "78e1bae0-b7dd-4626-bcda-9d7e7b81be30", "name_prefix": "Dr.", "name_first": "Miriam", "name_middle": "Louise", "name_last": "Trevino", "name_suffix": "Jr", "phone_number": "555-555-5555", "address_line_one": "12 Strawberry Road", "address_line_two": "Suite 101", "address_city": "Atlanta", "address_state": "GA", "address_zip": "99999-1000", "ssn": "888-88-8888", "email": "marissa@protonmail.com", "date_of_birth": "2018-06-20 09:12:30 UTC" }

Get a specific customer

Returns summary information for a specific customer.

URL parameters
  • customer_id Required / string

    The ID of the customer to return.

Responses
  • 200 object

    Successful query of information for a specific customer

    • customer_id string(uuid)

      A Canopy-generated unique ID for the customer

    • name_prefix string

      Prefix to the customer's name

    • name_first string

      Customer's first name

    • name_middle string

      Customer's middle name

    • name_last string

      Customer's last name

    • name_suffix string

      Prefix to the customer's name

    • phone_number string(phonenumber)

      Phone number of the customer

    • address_line_one string

      Address line one

    • address_line_two string

      Address line two

    • address_city string

      Address city

    • address_state string

      Address state

    • address_zip string

      Address zip code

    • ssn string

      Social security number of the customer

    • email string(email)

      The email address of this customer

    • date_of_birth string(date-time)

      Customer's date of birth

  • 404

    Unable to get customer

Definition
GET https://sandbox.canopyservicing.com/customers/{customer_id}
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/customers/Coco Parker \ -H "Content-Type: application/json"
Response example (200)
{ "customer_id": "78e1bae0-b7dd-4626-bcda-9d7e7b81be30", "name_prefix": "Dr.", "name_first": "Miriam", "name_middle": "Louise", "name_last": "Trevino", "name_suffix": "Jr", "phone_number": "555-555-5555", "address_line_one": "12 Strawberry Road", "address_line_two": "Suite 101", "address_city": "Atlanta", "address_state": "GA", "address_zip": "99999-1000", "ssn": "888-88-8888", "email": "marissa@protonmail.com", "date_of_birth": "2018-06-20 09:12:30 UTC" }
Response example (404)
No content

Update an existing customer

Update data for a customer in Canopy.

URL parameters
  • customer_id Required / string(uuid)

    The ID of the customer to be updated.

Body
  • name_prefix string

    Prefix to the customer's name

  • name_first string

    Customer's first name

  • name_middle string

    Customer's middle name

  • name_last string

    Customer's last name

  • name_suffix string

    Prefix to the customer's name

  • phone_number string(phonenumber)

    Phone number of the customer

  • address_line_one string

    Address line one

  • address_line_two string

    Address line two

  • address_city string

    Address city

  • address_state string

    Address state

  • address_zip string

    Address zip code

  • email string(email)

    The email address of this Customer

  • ssn string

    Social security number of the customer

  • date_of_birth string(date-time)

    Customer's date of birth

  • account_id string(uuid)

    The ID of the account for which you are updating the customer's information. (I.e. change the customer's address for this account) .

  • new_accounts array[object]

    An array of existing accounts to which this Customer will be newly assigned.

    • new_accounts.account_id string(uuid)

      This is generated by Canopy. A unique ID for the account.

    • new_accounts.customer_account_role string

      The role of the customer for the account.

      Values are primary and secondary.

    • new_accounts.customer_account_pan string

      A unique number for the customer on the account. For instance, a credit card number. If none is provided, a Canopy-generated ID can be used.

Responses
  • 204 object

    Successful query of information for a specific customer

    • customer_id string(uuid)

      A Canopy-generated unique ID for the customer

    • name_prefix string

      Prefix to the customer's name

    • name_first string

      Customer's first name

    • name_middle string

      Customer's middle name

    • name_last string

      Customer's last name

    • name_suffix string

      Prefix to the customer's name

    • phone_number string(phonenumber)

      Phone number of the customer

    • address_line_one string

      Address line one

    • address_line_two string

      Address line two

    • address_city string

      Address city

    • address_state string

      Address state

    • address_zip string

      Address zip code

    • ssn string

      Social security number of the customer

    • email string(email)

      The email address of this customer

    • date_of_birth string(date-time)

      Customer's date of birth

    • accounts array[object]

      An array of Accounts to which this Customer is assigned

      • accounts.account_id Required / string(uuid)

        This is generated by Canopy. A unique ID for the account.

      • accounts.account_status Required / string

        The Status of the Account. Active upon account creation.

      • accounts.account_status_subtype Required / string

        The subtype of the Status of the Account. Null upon account creation.

      • accounts.effective_at Required / string(date-time)

        The Date-Time that this account became/becomes active.

      • accounts.created_at Required / string(date-time)

        The Date-Time which the account was created in the API.

      • accounts.product Required / object
        • accounts.product.product_id Required / string(uuid)

          The Canopy-generated ID for the product.

        • accounts.product.name Required / string

          Name of Product, i.e. Express Card.

        • accounts.product.description Required / string

          Description of the Product.

        • accounts.product.created_at Required / string(date-time)

          The Date-Time that this product was created on the server.

        • accounts.product.type Required / string

          The Type of Product

          Values are CREDIT.

        • accounts.product.status Required / string

          The status of a Product (i.e. live). Currently, all configured products are in the live state.

          Values are VALID.

        • accounts.product.policies Required / object

          An object of policies that drive product behavior.

          • accounts.product.policies.base_policy_config object

            A base group of policies that define a Product

            • accounts.product.policies.base_policy_config.min_pay Required / object

              The configured minimum payment required for a given pay period.

              • accounts.product.policies.base_policy_config.min_pay.percentage number

                The percentage of total balance calculated for min pay. (i.e. 20 means 20%)

            • accounts.product.policies.base_policy_config.billing_cycle Required / object

              The Billing Cycle Object

              • accounts.product.policies.base_policy_config.billing_cycle.period Required / string(interval)

                The length of the billing cycle. after which a statement is generated, and a due date assigned. IE '1 month' '3 months' or '7 days' (most common is monthly)

              • accounts.product.policies.base_policy_config.billing_cycle.billing_due_date_interval Required / string(interval)

                The amount of time you would like between the statement cut and the billing due date. IE '25 days'. Cannot exceed the start of the next billing cycle and generally needs to be at least 21 days.

            • accounts.product.policies.base_policy_config.interest_policies Required / object

              The Interest Policy Object

              • accounts.product.policies.base_policy_config.interest_policies.type Required / string

                Values are compound.

              • accounts.product.policies.base_policy_config.interest_policies.method Required / string

                The actual base formula used to calculate and assign interest.

                Values are average daily balance.

              • accounts.product.policies.base_policy_config.interest_policies.day_calc_type Required / string

                Affects the base calculation by determining how many days there are in a given year.

                Values are 365.

              • accounts.product.policies.base_policy_config.interest_policies.interest_calc_time Required / string(date-time)

                Interest for this policy is calculated at this time every X interval.

            • accounts.product.policies.base_policy_config.close_of_business_and_timezone Required / string(date-time)

              Time and timezone of the close of business. This is used for statement cuts and partner-level and issuing bank-level reconciliation

        • accounts.product.product_summary Required / object

          Summary of product information

          • accounts.product.product_summary.accounts_overview object
            • accounts.product.product_summary.accounts_overview.account_count_total integer

              Total number of accounts under the product.

            • accounts.product.product_summary.accounts_overview.account_count_delinquent integer

              Total number of delinquent accounts under the product.

          • accounts.product.product_summary.total_credit_issued_cents integer

            Total amount (in cents) of credit issued to accounts under the product.

          • accounts.product.product_summary.utilization_rate number

            The percent utilization rate of the product.

          • accounts.product.product_summary.product_id string(uuid)

            The Canopy-generated ID for the product.

          • accounts.product.product_summary.effective_as_of_date string(date-time)

            The Date-Time you would like the system to return the data as of. IE "tell me what the product information was as if I had asked on 2020-01-20 00:00:00 EST". If empty defaults to current time.

        • accounts.product.default_attributes Required / object
          • accounts.product.default_attributes.rate Required / number

            The percent default rate for this interest policy (i.e. 3.2 means a 3.2% rate). This default rate can be overridden on a per-account basis if a rate is selected at the time of assigning an account to a product. Rates for an account can also be updated post-account creation.

          • accounts.product.default_attributes.credit_limit_cents Required / integer

            The default maximum principal credit (in cents) available for a customer account. This default limit can be overridden on a per-account basis if a credit_limit is selected at the time of assigning an account to a product. Credit limits for an account can also be updated post-account creation.

      • accounts.external_account_ids array[object]

        An Array of External Account IDs. These should be used to connect accounts created in Canopy to Users in your system and any connected external systems.

        • accounts.external_account_ids.name string

          Name of the External Party

        • accounts.external_account_ids.id string

          External Account ID

      • accounts.total_balance Required / number

        The total balance (in cents) associated with the account.

      • accounts.credit_limit_cents Required / integer

        Total Amount (in cents) that this account can borrow.

      • accounts.rate Required / number

        The percentage interest applied to the account (i.e. 6.2 means 6.2%)

      • accounts.available_credit_balance Required / number

        The total available credit balance (in cents) for the account.

Definition
PUT https://sandbox.canopyservicing.com/customers/{customer_id}
cURL example
curl \ -X PUT https://sandbox.canopyservicing.com/customers/975d11ab-92d3-489e-9aa5-8d0277b0222a \ -H "Content-Type: application/json" \ -d '{"name_prefix":"Dr.","name_first":"Miriam","name_middle":"Louise","name_last":"Trevino","name_suffix":"Jr","phone_number":"555-555-5555","address_line_one":"12 Strawberry Road","address_line_two":"Suite 101","address_city":"Atlanta","address_state":"GA","address_zip":"99999-1000","email":"marissa@protonmail.com","ssn":"888-88-8888","date_of_birth":"2018-06-20T09:12:30Z","account_id":"39495885-2116-4707-9522-9e90f110e93d","new_accounts":[{"account_id":"5fb3a288-5f6c-440f-b079-b06c828b7768","c...}'
Request payload example
{ "name_prefix": "Dr.", "name_first": "Miriam", "name_middle": "Louise", "name_last": "Trevino", "name_suffix": "Jr", "phone_number": "555-555-5555", "address_line_one": "12 Strawberry Road", "address_line_two": "Suite 101", "address_city": "Atlanta", "address_state": "GA", "address_zip": "99999-1000", "email": "marissa@protonmail.com", "ssn": "888-88-8888", "date_of_birth": "2018-06-20 09:12:30 UTC", "account_id": "39495885-2116-4707-9522-9e90f110e93d", "new_accounts": [ { "account_id": "5fb3a288-5f6c-440f-b079-b06c828b7768", "customer_account_role": "primary", "customer_account_pan": "4465220133024156" } ] }
Response example (204)
{ "customer_id": "78e1bae0-b7dd-4626-bcda-9d7e7b81be30", "name_prefix": "Dr.", "name_first": "Miriam", "name_middle": "Louise", "name_last": "Trevino", "name_suffix": "Jr", "phone_number": "555-555-5555", "address_line_one": "12 Strawberry Road", "address_line_two": "Suite 101", "address_city": "Atlanta", "address_state": "GA", "address_zip": "99999-1000", "ssn": "888-88-8888", "email": "marissa@protonmail.com", "date_of_birth": "2018-06-20 09:12:30 UTC", "accounts": [ { "account_id": "5fb3a288-5f6c-440f-b079-b06c828b7768", "account_status": "suspended", "account_status_subtype": "suspended-bankruptcy", "effective_at": "2018-03-20 09:12:28 UTC", "created_at": "2017-06-20 09:12:14 UTC", "product": { "product_id": "8fe1eb97-d640-45d6-83bb-f415ddf97a51", "name": "Blue Cash Express", "description": "Student credit card.", "created_at": "2019-03-20 09:12:28 UTC", "type": "CREDIT", "status": "VALID", "policies": { "base_policy_config": { "min_pay": { "percentage": "20" }, "billing_cycle": { "period": "1 month", "billing_due_date_interval": "25 days" }, "interest_policies": { "type": "compound", "method": "average daily balance", "day_calc_type": "365", "interest_calc_time": 18000 }, "close_of_business_and_timezone": "2020-03-20 09:12:28 UTC" } }, "product_summary": { "accounts_overview": { "account_count_total": 10005, "account_count_delinquent": 200 }, "total_credit_issued_cents": 25500000, "utilization_rate": 30.34, "product_id": "ca3cf4e9-5048-4461-a763-8f67b46dfd4d", "effective_as_of_date": "2017-06-20 09:12:14 UTC" }, "default_attributes": { "rate": 3.2, "credit_limit_cents": 600000 } }, "external_account_ids": [ { "name": "Umbrella Corporation", "id": "22445702-a389-431f-927d-07b8d0750787" } ], "total_balance": "300000", "credit_limit_cents": "400000", "rate": "6.2", "available_credit_balance": "100000" } ] }

Accounts

Manage the way your users use credit products you've launched in Canopy

Get summary details for a specific product.

For analytic purposes, retrieve commonly needed summary statistics computed for a specific product.

URL parameters
  • product_id Required / string(uuid)

    Product ID

  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the product summary information was on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses
  • 200 object

    Response for a request for summary data for a specific product.

    • accounts_overview object
      • accounts_overview.account_count_total integer

        Total number of accounts under the product.

      • accounts_overview.account_count_delinquent integer

        Total number of delinquent accounts under the product.

    • total_credit_issued_cents integer

      Total amount (in cents) of credit issued to accounts under the product.

    • utilization_rate number

      The percent utilization rate of the product.

    • product_id string(uuid)

      The Canopy-generated ID for the product.

    • effective_as_of_date string(date-time)

      The Date-Time you would like the system to return the data as of. IE "tell me what the product information was as if I had asked on 2020-01-20 00:00:00 EST". If empty defaults to current time.

  • 404

    Account not found

Definition
GET https://sandbox.canopyservicing.com/products/{product_id}/summaries
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/products/{product_id}/summaries \ -H "Content-Type: application/json"
Response example (200)
{ "accounts_overview": { "account_count_total": 10005, "account_count_delinquent": 200 }, "total_credit_issued_cents": 25500000, "utilization_rate": 30.34, "product_id": "ca3cf4e9-5048-4461-a763-8f67b46dfd4d", "effective_as_of_date": "2017-06-20 09:12:14 UTC" }
Response example (404)
No content

Create a new account

At least one account should be created for customer of each of your products. Once created, you will be able to add line_items to the account.

Body
  • product_id Required / string(uuid)

    The Product ID of the account

  • external_ids array[object]

    An array of static references to ID fields in a third party system.

    • external_ids.name string

      Name of the External Party

    • external_ids.id string

      External Account ID

  • credit_limit_cents integer

    For accounts created under credit products, total Amount (in cents) that this account can borrow.

  • rate number

    The percentage interest applied to the account (i.e. 6.2%)

  • existing_customers array[object]

    Array of existing customer IDs to be added to the account. At least one existing OR one new customer must be included in account creation.

    • existing_customers.customer_id string(uuid)

      Canopy-generated unique ID for this customer

    • existing_customers.customer_account_role integer

      The role of the customer for the account. For instance, 1 may correspond to a primary account holder while 2 corresponds to secondary.

      Values are 1 and 2.

Responses
  • 201 object

    New Account Created

    • account_id Required / string(uuid)

      This is generated by Canopy. A unique ID for the account.

    • account_status Required / string

      The Status of the Account. Active upon account creation.

    • account_status_subtype Required / string

      The subtype of the Status of the Account. Null upon account creation.

    • effective_at Required / string(date-time)

      The Date-Time that this account became/becomes active.

    • created_at Required / string(date-time)

      The Date-Time which the account was created in the API.

    • product Required / object
      • product.product_id Required / string(uuid)

        The Canopy-generated ID for the product.

      • product.name Required / string

        Name of Product, i.e. Express Card.

      • product.description Required / string

        Description of the Product.

      • product.created_at Required / string(date-time)

        The Date-Time that this product was created on the server.

      • product.type Required / string

        The Type of Product

        Values are CREDIT.

      • product.status Required / string

        The status of a Product (i.e. live). Currently, all configured products are in the live state.

        Values are VALID.

      • product.policies Required / object

        An object of policies that drive product behavior.

        • product.policies.base_policy_config object

          A base group of policies that define a Product

          • product.policies.base_policy_config.min_pay Required / object

            The configured minimum payment required for a given pay period.

            • product.policies.base_policy_config.min_pay.percentage number

              The percentage of total balance calculated for min pay. (i.e. 20 means 20%)

          • product.policies.base_policy_config.billing_cycle Required / object

            The Billing Cycle Object

            • product.policies.base_policy_config.billing_cycle.period Required / string(interval)

              The length of the billing cycle. after which a statement is generated, and a due date assigned. IE '1 month' '3 months' or '7 days' (most common is monthly)

            • product.policies.base_policy_config.billing_cycle.billing_due_date_interval Required / string(interval)

              The amount of time you would like between the statement cut and the billing due date. IE '25 days'. Cannot exceed the start of the next billing cycle and generally needs to be at least 21 days.

          • product.policies.base_policy_config.interest_policies Required / object

            The Interest Policy Object

            • product.policies.base_policy_config.interest_policies.type Required / string

              Values are compound.

            • product.policies.base_policy_config.interest_policies.method Required / string

              The actual base formula used to calculate and assign interest.

              Values are average daily balance.

            • product.policies.base_policy_config.interest_policies.day_calc_type Required / string

              Affects the base calculation by determining how many days there are in a given year.

              Values are 365.

            • product.policies.base_policy_config.interest_policies.interest_calc_time Required / string(date-time)

              Interest for this policy is calculated at this time every X interval.

          • product.policies.base_policy_config.close_of_business_and_timezone Required / string(date-time)

            Time and timezone of the close of business. This is used for statement cuts and partner-level and issuing bank-level reconciliation

      • product.product_summary Required / object

        Summary of product information

        • product.product_summary.accounts_overview object
          • product.product_summary.accounts_overview.account_count_total integer

            Total number of accounts under the product.

          • product.product_summary.accounts_overview.account_count_delinquent integer

            Total number of delinquent accounts under the product.

        • product.product_summary.total_credit_issued_cents integer

          Total amount (in cents) of credit issued to accounts under the product.

        • product.product_summary.utilization_rate number

          The percent utilization rate of the product.

        • product.product_summary.product_id string(uuid)

          The Canopy-generated ID for the product.

        • product.product_summary.effective_as_of_date string(date-time)

          The Date-Time you would like the system to return the data as of. IE "tell me what the product information was as if I had asked on 2020-01-20 00:00:00 EST". If empty defaults to current time.

      • product.default_attributes Required / object
        • product.default_attributes.rate Required / number

          The percent default rate for this interest policy (i.e. 3.2 means a 3.2% rate). This default rate can be overridden on a per-account basis if a rate is selected at the time of assigning an account to a product. Rates for an account can also be updated post-account creation.

        • product.default_attributes.credit_limit_cents Required / integer

          The default maximum principal credit (in cents) available for a customer account. This default limit can be overridden on a per-account basis if a credit_limit is selected at the time of assigning an account to a product. Credit limits for an account can also be updated post-account creation.

    • external_account_ids array[object]

      An Array of External Account IDs. These should be used to connect accounts created in Canopy to Users in your system and any connected external systems.

      • external_account_ids.name string

        Name of the External Party

      • external_account_ids.id string

        External Account ID

    • total_balance Required / number

      The total balance (in cents) associated with the account.

    • credit_limit_cents Required / integer

      Total Amount (in cents) that this account can borrow.

    • rate Required / number

      The percentage interest applied to the account (i.e. 6.2 means 6.2%)

    • available_credit_balance Required / number

      The total available credit balance (in cents) for the account.

    • customers array[object]

      An array of customers who have been assigned to the account

      • customers.customer_id string(uuid)

        A Canopy-generated unique ID for the customer

      • customers.name_prefix string

        Prefix to the customer's name

      • customers.name_first string

        Customer's first name

      • customers.name_middle string

        Customer's middle name

      • customers.name_last string

        Customer's last name

      • customers.name_suffix string

        Prefix to the customer's name

      • customers.phone_number string(phonenumber)

        Phone number of the customer

      • customers.address_line_one string

        Address line one

      • customers.address_line_two string

        Address line two

      • customers.address_city string

        Address city

      • customers.address_state string

        Address state

      • customers.address_zip string

        Address zip code

      • customers.ssn string

        Social security number of the customer

      • customers.email string(email)

        The email address of this customer

      • customers.date_of_birth string(date-time)

        Customer's date of birth

  • 405

    Invalid input

Definition
POST https://sandbox.canopyservicing.com/accounts
cURL example
curl \ -X POST https://sandbox.canopyservicing.com/accounts \ -H "Content-Type: application/json" \ -d '{"product_id":"d119341c-47fd-4a55-bce7-28406dacfa20","external_ids":[{"name":"Globex Corporation","id":"22445702-a389-431f-927d-07b8d0750787"}],"credit_limit_cents":"400000","rate":"6.2","existing_customers":[{"customer_id":"d581a0aa-5e11-473c-9569-64bc3a494287","customer_account_role":"1"}]}'
Request payload example
{ "product_id": "d119341c-47fd-4a55-bce7-28406dacfa20", "external_ids": [ { "name": "Globex Corporation", "id": "22445702-a389-431f-927d-07b8d0750787" } ], "credit_limit_cents": "400000", "rate": "6.2", "existing_customers": [ { "customer_id": "d581a0aa-5e11-473c-9569-64bc3a494287", "customer_account_role": "1" } ] }
Response example (201)
{ "account_id": "5fb3a288-5f6c-440f-b079-b06c828b7768", "account_status": "suspended", "account_status_subtype": "suspended-bankruptcy", "effective_at": "2018-03-20 09:12:28 UTC", "created_at": "2017-06-20 09:12:14 UTC", "product": { "product_id": "8fe1eb97-d640-45d6-83bb-f415ddf97a51", "name": "Blue Cash Express", "description": "Student credit card.", "created_at": "2019-03-20 09:12:28 UTC", "type": "CREDIT", "status": "VALID", "policies": { "base_policy_config": { "min_pay": { "percentage": "20" }, "billing_cycle": { "period": "1 month", "billing_due_date_interval": "25 days" }, "interest_policies": { "type": "compound", "method": "average daily balance", "day_calc_type": "365", "interest_calc_time": 18000 }, "close_of_business_and_timezone": "2020-03-20 09:12:28 UTC" } }, "product_summary": { "accounts_overview": { "account_count_total": 10005, "account_count_delinquent": 200 }, "total_credit_issued_cents": 25500000, "utilization_rate": 30.34, "product_id": "ca3cf4e9-5048-4461-a763-8f67b46dfd4d", "effective_as_of_date": "2017-06-20 09:12:14 UTC" }, "default_attributes": { "rate": 3.2, "credit_limit_cents": 600000 } }, "external_account_ids": [ { "name": "Umbrella Corporation", "id": "22445702-a389-431f-927d-07b8d0750787" } ], "total_balance": "300000", "credit_limit_cents": "400000", "rate": "6.2", "available_credit_balance": "100000", "customers": [ { "customer_id": "78e1bae0-b7dd-4626-bcda-9d7e7b81be30", "name_prefix": "Dr.", "name_first": "Miriam", "name_middle": "Louise", "name_last": "Trevino", "name_suffix": "Jr", "phone_number": "555-555-5555", "address_line_one": "12 Strawberry Road", "address_line_two": "Suite 101", "address_city": "Atlanta", "address_state": "GA", "address_zip": "99999-1000", "ssn": "888-88-8888", "email": "marissa@protonmail.com", "date_of_birth": "2018-06-20 09:12:30 UTC" } ] }
Response example (405)
No content

Get a specific Account

URL parameters
  • account_id Required / string(uuid)

    Account ID

  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the account information was on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses
  • 200 object

    Successful query of information for a specific account

    • account_id Required / string(uuid)

      This is generated by Canopy. A unique ID for the account.

    • account_status Required / string

      The Status of the Account. Active upon account creation.

    • account_status_subtype Required / string

      The subtype of the Status of the Account. Null upon account creation.

    • effective_at Required / string(date-time)

      The Date-Time that this account became/becomes active.

    • created_at Required / string(date-time)

      The Date-Time which the account was created in the API.

    • product Required / object
      • product.product_id Required / string(uuid)

        The Canopy-generated ID for the product.

      • product.name Required / string

        Name of Product, i.e. Express Card.

      • product.description Required / string

        Description of the Product.

      • product.created_at Required / string(date-time)

        The Date-Time that this product was created on the server.

      • product.type Required / string

        The Type of Product

        Values are CREDIT.

      • product.status Required / string

        The status of a Product (i.e. live). Currently, all configured products are in the live state.

        Values are VALID.

      • product.policies Required / object

        An object of policies that drive product behavior.

        • product.policies.base_policy_config object

          A base group of policies that define a Product

          • product.policies.base_policy_config.min_pay Required / object

            The configured minimum payment required for a given pay period.

            • product.policies.base_policy_config.min_pay.percentage number

              The percentage of total balance calculated for min pay. (i.e. 20 means 20%)

          • product.policies.base_policy_config.billing_cycle Required / object

            The Billing Cycle Object

            • product.policies.base_policy_config.billing_cycle.period Required / string(interval)

              The length of the billing cycle. after which a statement is generated, and a due date assigned. IE '1 month' '3 months' or '7 days' (most common is monthly)

            • product.policies.base_policy_config.billing_cycle.billing_due_date_interval Required / string(interval)

              The amount of time you would like between the statement cut and the billing due date. IE '25 days'. Cannot exceed the start of the next billing cycle and generally needs to be at least 21 days.

          • product.policies.base_policy_config.interest_policies Required / object

            The Interest Policy Object

            • product.policies.base_policy_config.interest_policies.type Required / string

              Values are compound.

            • product.policies.base_policy_config.interest_policies.method Required / string

              The actual base formula used to calculate and assign interest.

              Values are average daily balance.

            • product.policies.base_policy_config.interest_policies.day_calc_type Required / string

              Affects the base calculation by determining how many days there are in a given year.

              Values are 365.

            • product.policies.base_policy_config.interest_policies.interest_calc_time Required / string(date-time)

              Interest for this policy is calculated at this time every X interval.

          • product.policies.base_policy_config.close_of_business_and_timezone Required / string(date-time)

            Time and timezone of the close of business. This is used for statement cuts and partner-level and issuing bank-level reconciliation

      • product.product_summary Required / object

        Summary of product information

        • product.product_summary.accounts_overview object
          • product.product_summary.accounts_overview.account_count_total integer

            Total number of accounts under the product.

          • product.product_summary.accounts_overview.account_count_delinquent integer

            Total number of delinquent accounts under the product.

        • product.product_summary.total_credit_issued_cents integer

          Total amount (in cents) of credit issued to accounts under the product.

        • product.product_summary.utilization_rate number

          The percent utilization rate of the product.

        • product.product_summary.product_id string(uuid)

          The Canopy-generated ID for the product.

        • product.product_summary.effective_as_of_date string(date-time)

          The Date-Time you would like the system to return the data as of. IE "tell me what the product information was as if I had asked on 2020-01-20 00:00:00 EST". If empty defaults to current time.

      • product.default_attributes Required / object
        • product.default_attributes.rate Required / number

          The percent default rate for this interest policy (i.e. 3.2 means a 3.2% rate). This default rate can be overridden on a per-account basis if a rate is selected at the time of assigning an account to a product. Rates for an account can also be updated post-account creation.

        • product.default_attributes.credit_limit_cents Required / integer

          The default maximum principal credit (in cents) available for a customer account. This default limit can be overridden on a per-account basis if a credit_limit is selected at the time of assigning an account to a product. Credit limits for an account can also be updated post-account creation.

    • external_account_ids array[object]

      An Array of External Account IDs. These should be used to connect accounts created in Canopy to Users in your system and any connected external systems.

      • external_account_ids.name string

        Name of the External Party

      • external_account_ids.id string

        External Account ID

    • total_balance Required / number

      The total balance (in cents) associated with the account.

    • credit_limit_cents Required / integer

      Total Amount (in cents) that this account can borrow.

    • rate Required / number

      The percentage interest applied to the account (i.e. 6.2 means 6.2%)

    • available_credit_balance Required / number

      The total available credit balance (in cents) for the account.

    • customers array[object]

      An array of customers who have been assigned to the account

      • customers.customer_id string(uuid)

        A Canopy-generated unique ID for the customer

      • customers.name_prefix string

        Prefix to the customer's name

      • customers.name_first string

        Customer's first name

      • customers.name_middle string

        Customer's middle name

      • customers.name_last string

        Customer's last name

      • customers.name_suffix string

        Prefix to the customer's name

      • customers.phone_number string(phonenumber)

        Phone number of the customer

      • customers.address_line_one string

        Address line one

      • customers.address_line_two string

        Address line two

      • customers.address_city string

        Address city

      • customers.address_state string

        Address state

      • customers.address_zip string

        Address zip code

      • customers.ssn string

        Social security number of the customer

      • customers.email string(email)

        The email address of this customer

      • customers.date_of_birth string(date-time)

        Customer's date of birth

  • 404

    Account not found

Definition
GET https://sandbox.canopyservicing.com/accounts/{account_id}
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/accounts/a361c813-92e5-4765-82ea-9df368a81a89 \ -H "Content-Type: application/json"
Response example (200)
{ "account_id": "5fb3a288-5f6c-440f-b079-b06c828b7768", "account_status": "suspended", "account_status_subtype": "suspended-bankruptcy", "effective_at": "2018-03-20 09:12:28 UTC", "created_at": "2017-06-20 09:12:14 UTC", "product": { "product_id": "8fe1eb97-d640-45d6-83bb-f415ddf97a51", "name": "Blue Cash Express", "description": "Student credit card.", "created_at": "2019-03-20 09:12:28 UTC", "type": "CREDIT", "status": "VALID", "policies": { "base_policy_config": { "min_pay": { "percentage": "20" }, "billing_cycle": { "period": "1 month", "billing_due_date_interval": "25 days" }, "interest_policies": { "type": "compound", "method": "average daily balance", "day_calc_type": "365", "interest_calc_time": 18000 }, "close_of_business_and_timezone": "2020-03-20 09:12:28 UTC" } }, "product_summary": { "accounts_overview": { "account_count_total": 10005, "account_count_delinquent": 200 }, "total_credit_issued_cents": 25500000, "utilization_rate": 30.34, "product_id": "ca3cf4e9-5048-4461-a763-8f67b46dfd4d", "effective_as_of_date": "2017-06-20 09:12:14 UTC" }, "default_attributes": { "rate": 3.2, "credit_limit_cents": 600000 } }, "external_account_ids": [ { "name": "Umbrella Corporation", "id": "22445702-a389-431f-927d-07b8d0750787" } ], "total_balance": "300000", "credit_limit_cents": "400000", "rate": "6.2", "available_credit_balance": "100000", "customers": [ { "customer_id": "78e1bae0-b7dd-4626-bcda-9d7e7b81be30", "name_prefix": "Dr.", "name_first": "Miriam", "name_middle": "Louise", "name_last": "Trevino", "name_suffix": "Jr", "phone_number": "555-555-5555", "address_line_one": "12 Strawberry Road", "address_line_two": "Suite 101", "address_city": "Atlanta", "address_state": "GA", "address_zip": "99999-1000", "ssn": "888-88-8888", "email": "marissa@protonmail.com", "date_of_birth": "2018-06-20 09:12:30 UTC" } ] }
Response example (404)
No content

Line items

Manage individual line items for your customers in Canopy.

Get line items for a specific account.

Line Items for an Account consist of charges to the account and payments by the account holder. Results are paginated and sorted by line item effective date.

URL parameters
  • account_id Required / string(uuid)

    Account ID

  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the line items were on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

  • line_item_type string

    The type of line items you would like to view. Options are charges and payments. If not provided, no filters will be applied.

  • offset integer

    The zero-indexed starting point for paginated line item requests sorted by line item effective date.

  • limit integer

    The maximum number of line items to be returned. Defaults to 100.

Responses
  • 200 array[object]

    Array of Line Items and their corresponding balances at their effective dates and times.

    • account_id Required / string(uuid)

      The account associated with the line item

    • line_item_id Required / string(uuid)
    • line_item_status Required / string

      the corresponding Status for a line item

      Values are posted, valid, invalid, declined, authorized, void, pending, successful, and unsuccessful.

    • type Required / string

      The Line Item Type. Either charge or payment.

      Values are charge and payment.

    • originating_amount_cents Required / number

      The originating amount of money (in cents) relating to this line item.

    • balance_amount_cents Required / number

      The current balance of the line item, which accounts for interest accrued per the product's interest policy and the account's interest rate attribute.

    • total_interest_accrued_cents Required / number

      The sum (in cents) of all interest charges, if any, applied to this line item

    • total_paid_down_cents Required / number

      The sum (in cents) of all payment splits, if any, applied to this line item

    • merchant_data Required / object
      • merchant_data.name string
      • merchant_data.id string
      • merchant_data.mcc_code number
      • merchant_data.phone_number string(phonenumber)
    • effective_at Required / string(date-time)

      The Date-Time that this account became/becomes active

    • created_at Required / string(date-time)

      The Date-Time which the account was created in the API

    • product_id Required / string(uuid)

      the Product ID of the account

    • description Required / string

      A description of this particular line item if any. More common for adjustments.

    • reference_id Required / string

      User ID in your system to associate with the payment for the account defined in Canopy.

    • dispute_id Required / string(uuid)

      The ID for a dispute if present for this line item.

    • external_ids array[object]

      An array of static references to ID fields in a third party system.

      • external_ids.name string

        Name of the External Party

      • external_ids.id string

        External Account ID

    • line_item_count Required / string

      Total number of line items for the account.

  • 404

    Account not found

Definition
GET https://sandbox.canopyservicing.com/accounts/{account_id}/line_items
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/accounts/{account_id}/line_items \ -H "Content-Type: application/json"
Response example (200)
[ { "account_id": "2911ff2a-bebe-4c85-8d19-e6001015a8e3", "line_item_id": "ce9ed376-f151-435f-a59c-9e3cc183bbea", "line_item_status": "posted", "type": "charge", "originating_amount_cents": "2385", "balance_amount_cents": "2401", "total_interest_accrued_cents": "16", "total_paid_down_cents": "1125", "merchant_data": { "name": "string", "id": "string", "mcc_code": 42.0, "phone_number": "string" }, "effective_at": "2018-07-20 09:12:30 UTC", "created_at": "2018-06-20 09:12:30 UTC", "product_id": "158cd7a1-d813-42d2-90a3-9a91c43f18f8", "description": "Refund for invalid purchase", "reference_id": "e39c6b0d-5793-49c5-bee7-a2dbf8808f3a", "dispute_id": "string", "external_ids": [ { "name": "Globex Card Processing", "id": "22445702-a389-431f-927d-07b8d0750787" } ], "line_item_count": "string" } ]
Response example (404)
No content

Get information on a specific line item for a specific account

URL parameters
  • account_id Required / string(uuid)

    Account ID

  • line_item_id Required / string(uuid)

    Line Item ID

  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the products were as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses
  • 204 object

    Detailed info about a specific line item

    • account_id Required / string(uuid)

      The account associated with the line item

    • line_item_id Required / string(uuid)
    • line_item_status Required / string

      the corresponding Status for a line item

      Values are posted, valid, invalid, declined, authorized, void, pending, successful, and unsuccessful.

    • type Required / string

      The Line Item Type. Either charge or payment.

      Values are charge and payment.

    • originating_amount_cents number

      The originating amount of money (in cents) relating to this line item.

    • balance_amount_cents number

      The current balance of the line item, which accounts for interest accrued per the product's interest policy and the account's interest rate attribute.

    • total_interest_accrued_cents number

      The sum (in cents) of all interest charges, if any, applied to this line item

    • total_paid_down_cents number

      The sum (in cents) of all payment splits, if any, applied to this line item

    • rate number

      The percentage rate applied to this line item (i.e. 15.5 means 15.5%). If it was not set at the time of charge creation, its default value is the default rate of the account.

    • merchant_data object
      • merchant_data.name string
      • merchant_data.id string
      • merchant_data.mcc_code number
      • merchant_data.phone_number string(phonenumber)
    • effective_at Required / string(date-time)

      The Date-Time that this line item became/becomes active

    • created_at Required / string(date-time)

      The Date-Time which the line item was created in the API

    • product_id Required / string(uuid)

      the Product ID of the account

    • description string

      A description of this particular line item if any. More common for adjustments.

    • reference_id Required / string

      User ID in your system to associate with the payment for the account defined in Canopy.

    • dispute_id string(uuid)

      The ID for a dispute if present for this line item.

    • external_ids array[object]

      An array of static references to ID fields in a third party system.

      • external_ids.name string

        Name of the External Party

      • external_ids.id string

        External Account ID

Definition
GET https://sandbox.canopyservicing.com/accounts/{account_id}/line_items/{line_item_id}
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/accounts/17d25206-1012-4576-89f0-c5fe128edd3e/line_items/8f0a3e81-24b9-4d32-b15b-a59257ed7485 \ -H "Content-Type: application/json"
Response example (204)
{ "account_id": "2911ff2a-bebe-4c85-8d19-e6001015a8e3", "line_item_id": "ce9ed376-f151-435f-a59c-9e3cc183bbea", "line_item_status": "posted", "type": "charge", "originating_amount_cents": 42.0, "balance_amount_cents": 42.0, "total_interest_accrued_cents": "16", "total_paid_down_cents": "1125", "rate": "15.5%", "merchant_data": { "name": "string", "id": "string", "mcc_code": 42.0, "phone_number": "string" }, "effective_at": "2018-07-20 09:12:30 UTC", "created_at": "2018-06-20 09:12:30 UTC", "product_id": "158cd7a1-d813-42d2-90a3-9a91c43f18f8", "description": "Refund for invalid purchase", "reference_id": "e39c6b0d-5793-49c5-bee7-a2dbf8808f3a", "dispute_id": "string", "external_ids": [ { "name": "Globex Card Processing", "id": "22445702-a389-431f-927d-07b8d0750787" } ] }

Create a charge for a specific account

URL parameters
  • account_id Required / string(uuid)

    Account ID

Body
  • amount_cents Required / integer

    The Integer Amount of the Charge in Cents

  • effective_at Required / string(date-time)

    The Date-Time that the charge should be recorded to the account. Although the charge is being added to Canopy today, it can actually be effective as of 10 days ago.

  • rate number

    The percentage rate to be applied to this charge (i.e. 15.5 means 15.5%). If not included, defaults to the rate for the account.

  • merchant_data Required / object
    • merchant_data.name string
    • merchant_data.id string
    • merchant_data.mcc_code Required / number
    • merchant_data.phone_number string(phonenumber)
  • reference_id string

    A unique ID generated in your system to associate with the Charge.

  • external_ids array[object]

    An array of static references to ID fields in a third party system.

    • external_ids.name string

      Name of the External Party

    • external_ids.id string

      External Account ID

Responses
  • 204 object

    Charge Created

    • line_item_id Required / string(uuid)

      The ID in Canopy's system for this line item.

  • 401

    You are not authenticated

  • 403

    You are not authorized

  • 404

    Account not found

Definition
POST https://sandbox.canopyservicing.com/accounts/{account_id}/line_items/charges
cURL example
curl \ -X POST https://sandbox.canopyservicing.com/accounts/{account_id}/line_items/charges \ -H "Content-Type: application/json" \ -d '{"amount_cents":"200","effective_at":"2020-07-20T09:11:28Z","rate":"15.5%","merchant_data":{"name":"string","id":"string","mcc_code":42.0,"phone_number":"string"},"reference_id":"e39c6b0d-5793-49c5-bee7-a2dbf8808f3a","external_ids":[{"name":"Globex Card Processing","id":"22445702-a389-431f-927d-07b8d0750787"}]}'
Request payload example
{ "amount_cents": "200", "effective_at": "2020-07-20 09:11:28 UTC", "rate": "15.5%", "merchant_data": { "name": "string", "id": "string", "mcc_code": 42.0, "phone_number": "string" }, "reference_id": "e39c6b0d-5793-49c5-bee7-a2dbf8808f3a", "external_ids": [ { "name": "Globex Card Processing", "id": "22445702-a389-431f-927d-07b8d0750787" } ] }
Response example (204)
{ "line_item_id": "e58b78c3-0df8-4895-b10c-0fa88b266119" }
Response example (401)
No content
Response example (403)
No content
Response example (404)
No content

Create a payment for a specific account

URL parameters
  • account_id Required / string(uuid)

    Account ID

Body
  • amount_cents integer

    The Integer Amount of the Payment in Cents

  • effective_at string(date-time)

    The Date-Time that the payment should be recorded to the account. Although the payment is being added to Canopy today, it can actually be effective as of 10 days ago.

  • reference_id string

    A unique ID generated in your system to associate with the Payment.

  • external_ids array[object]

    An array of static references to ID fields in a third party system.

    • external_ids.name string

      Name of the External Party

    • external_ids.id string

      External Account ID

Responses
  • 204 object

    Payment Created

    • line_item_id Required / string(uuid)

      The ID in Canopy's system for this line item.

  • 404

    Account not found

Definition
POST https://sandbox.canopyservicing.com/accounts/{account_id}/line_items/payments
cURL example
curl \ -X POST https://sandbox.canopyservicing.com/accounts/{account_id}/line_items/payments \ -H "Content-Type: application/json" \ -d '{"amount_cents":"200","effective_at":"2020-07-20T09:11:28Z","reference_id":"e39c6b0d-5793-49c5-bee7-a2dbf8808f3a","external_ids":[{"name":"Globex Card Processing","id":"22445702-a389-431f-927d-07b8d0750787"}]}'
Request payload example
{ "amount_cents": "200", "effective_at": "2020-07-20 09:11:28 UTC", "reference_id": "e39c6b0d-5793-49c5-bee7-a2dbf8808f3a", "external_ids": [ { "name": "Globex Card Processing", "id": "22445702-a389-431f-927d-07b8d0750787" } ] }
Response example (204)
{ "line_item_id": "464920a3-d531-422d-adfb-ce61e52255bf" }
Response example (404)
No content

Notes

Help your customer service team track its activity across accounts.

Get All Notes for a specific Account

URL parameters
  • account_id Required / string(uuid)

    Account ID

  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the account information was on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses
  • 200 array[object]

    Successful query of history of notes for a specific account

    • note_id string(uuid)

      A Canopy-generated unique ID for the note

    • account_id string(uuid)

      The ID of the account to which the Note is assigned

    • author object
      • author.api_user_id Required / string

        The unique ID in Canopy for this API user

      • author.organization_name Required / string

        The organization to which the API user belongs.

      • author.name_first string

        The first name of the API user.

      • author.name_last string

        The last name of the API user.

      • author.email Required / string(email)

        The email address of this API User

      • author.phone string(phonenumber)

        Phone number of the API user

      • author.role Required / string

        The role of this user in the API

        Values are SERVICING, OPERATIONS, and ADMIN.

    • message string

      The contents of the note.

    • created_date string(date-time)

      The date and time the note was created.

  • 404

    Account not found

Definition
GET https://sandbox.canopyservicing.com/accounts/{account_id}/notes
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/accounts/a361c813-92e5-4765-82ea-9df368a81a89/notes \ -H "Content-Type: application/json"
Response example (200)
[ { "note_id": "7b2e189d-d6bb-41c2-95c1-1174b58246fa", "account_id": "bb6db06e-32ea-4e6a-8e6f-6e704b606a7e", "author": { "api_user_id": "44197ea2-eb78-4511-bcf2-bc28201f9c01", "organization_name": "Lever Card 3000", "name_first": "Analise", "name_last": "Goldberg", "email": "marissa@globex.com", "phone": "1-123-456-7890", "role": "SERVICING" }, "message": "Attempted to call back customer, but no response.", "created_date": "2020-05-04T09:42:00+00:00" } ]
Response example (404)
No content

Create a note for a specific account.

A note to be added to the account.

URL parameters
  • account_id Required / string(uuid)

    Account ID

Body
  • message string

    The contents of the note.

Responses
  • 200 object

    New Note Created

    • note_id string(uuid)

      A Canopy-generated unique ID for the note

    • account_id string(uuid)

      The ID of the account to which the Note is assigned

    • author object
      • author.api_user_id Required / string

        The unique ID in Canopy for this API user

      • author.organization_name Required / string

        The organization to which the API user belongs.

      • author.name_first string

        The first name of the API user.

      • author.name_last string

        The last name of the API user.

      • author.email Required / string(email)

        The email address of this API User

      • author.phone string(phonenumber)

        Phone number of the API user

      • author.role Required / string

        The role of this user in the API

        Values are SERVICING, OPERATIONS, and ADMIN.

    • message string

      The contents of the note.

    • created_date string(date-time)

      The date and time the note was created.

Definition
POST https://sandbox.canopyservicing.com/accounts/{account_id}/notes
cURL example
curl \ -X POST https://sandbox.canopyservicing.com/accounts/{account_id}/notes \ -H "Content-Type: application/json" \ -d '{"message":"Attempted to call back customer, but no response."}'
Request payload example
{ "message": "Attempted to call back customer, but no response." }
Response example (200)
{ "note_id": "7b2e189d-d6bb-41c2-95c1-1174b58246fa", "account_id": "bb6db06e-32ea-4e6a-8e6f-6e704b606a7e", "author": { "api_user_id": "44197ea2-eb78-4511-bcf2-bc28201f9c01", "organization_name": "Lever Card 3000", "name_first": "Analise", "name_last": "Goldberg", "email": "marissa@globex.com", "phone": "1-123-456-7890", "role": "SERVICING" }, "message": "Attempted to call back customer, but no response.", "created_date": "2020-05-04T09:42:00+00:00" }

Statements

Generate per billing cycle statements for your accounts in Canopy.

Get a list of all current and prior statements for a specific account

List of statements for the account. To view line items for a specific statement, use the /accounts/{account_id}/statements route

URL parameters
  • account_id Required / string(uuid)

    Account ID

  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the account information was on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

  • offset integer

    The zero-indexed starting point for paginated statements list requests sorted by reverse statement date.

  • limit integer

    The maximum number of accounts to be returned. Defaults to 100.

Responses
  • 200 object
    • account_id string(uuid)

      The Canopy-generated ID for the account

    • effective_as_of_date string(date-time)

      The Date-Time you would like the system to return the data as of. IE tell me what the account information was as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

    • statements_list array[object]

      An array of statements included in the billing cycle.

      • statements_list.statement_id string(uuid)

        A Canopy-generated ID for the statement

      • statements_list.available_credit_balance number

        The total available credit balance (in cents) for the account.

      • statements_list.total_balance number

        The total balance (in cents) associated with the account.

      • statements_list.min_pay_due_date string(date-time)

        The Date-Time at which the minimum payment is due.

      • statements_list.min_pay_amount_cents number

        The minimum amount (in cents) due for this statement.

      • statements_list.billing_cycle_start_date string(date-time)

        The inclusive starting Date-Time that defines which transations are part of this statement.

      • statements_list.billing_cycle_end_date string(date-time)

        The inclusive ending Date-Time that defines which transations are part of this statement.

Definition
GET https://sandbox.canopyservicing.com/accounts/{account_id}/statements/list
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/accounts/{account_id}/statements/list \ -H "Content-Type: application/json"
Response example (200)
{ "account_id": "111eff36-cbec-4119-b188-b76200e804d8", "effective_as_of_date": "2018-07-20 09:10:14 UTC", "statements_list": [ { "statement_id": "3627809b-ff07-4e41-b127-44260efb3b80", "available_credit_balance": "600000", "total_balance": "400000", "min_pay_due_date": "2020-05-04T09:42:00+00:00", "min_pay_amount_cents": 42.0, "billing_cycle_start_date": "2020-05-04T09:42:00+00:00", "billing_cycle_end_date": "2020-05-04T09:42:00+00:00" } ] }

Get a statement for a given date for a specific account.

This will return the most recent Statement information based on the effective_as_of_date. Relevant dates for an account's historical statements can be obtained from the accounts/{account_id}/statements/list route.

URL parameters
  • account_id Required / string(uuid)

    Account ID

  • effective_as_of_date string(date-time)

    The Date-Time you would like the system to return the data as of. IE tell me what the account information was on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses
  • 200 object
    • available_credit_balance Required / number

      The total available credit balance (in cents) for the account.

    • total_balance Required / number

      The total balance (in cents) associated with the account.

    • account_id Required / string(uuid)

      The Canopy-generated ID for the account

    • effective_as_of_date Required / string(date-time)

      The Date-Time you would like the system to return the data as of. IE tell me what the account information was as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

    • min_pay_due_date Required / string(date-time)

      The Date-Time at which the minimum payment is due.

    • min_pay_amount_cents Required / number

      The minimum amount (in cents) due for this statement.

    • billing_cycle_start_date Required / string(date-time)

      The inclusive starting Date-Time that defines which transations are part of this statement.

    • billing_cycle_end_date Required / string(date-time)

      The inclusive ending Date-Time that defines which transations are part of this statement.

    • line_items array[object]

      An array of line items included in the billing cycle.

      • line_items.account_id Required / string(uuid)

        The account associated with the line item

      • line_items.line_item_id Required / string(uuid)
      • line_items.line_item_status Required / string

        the corresponding Status for a line item

        Values are posted, valid, invalid, declined, authorized, void, pending, successful, and unsuccessful.

      • line_items.type Required / string

        The Line Item Type. Either charge or payment.

        Values are charge and payment.

      • line_items.originating_amount_cents number

        The originating amount of money (in cents) relating to this line item.

      • line_items.balance_amount_cents number

        The current balance of the line item, which accounts for interest accrued per the product's interest policy and the account's interest rate attribute.

      • line_items.total_interest_accrued_cents number

        The sum (in cents) of all interest charges, if any, applied to this line item

      • line_items.total_paid_down_cents number

        The sum (in cents) of all payment splits, if any, applied to this line item

      • line_items.rate number

        The percentage rate applied to this line item (i.e. 15.5 means 15.5%). If it was not set at the time of charge creation, its default value is the default rate of the account.

      • line_items.merchant_data object
        • line_items.merchant_data.name string
        • line_items.merchant_data.id string
        • line_items.merchant_data.mcc_code number
        • line_items.merchant_data.phone_number string(phonenumber)
      • line_items.effective_at Required / string(date-time)

        The Date-Time that this line item became/becomes active

      • line_items.created_at Required / string(date-time)

        The Date-Time which the line item was created in the API

      • line_items.product_id Required / string(uuid)

        the Product ID of the account

      • line_items.description string

        A description of this particular line item if any. More common for adjustments.

      • line_items.reference_id Required / string

        User ID in your system to associate with the payment for the account defined in Canopy.

      • line_items.dispute_id string(uuid)

        The ID for a dispute if present for this line item.

      • line_items.external_ids array[object]

        An array of static references to ID fields in a third party system.

        • line_items.external_ids.name string

          Name of the External Party

        • line_items.external_ids.id string

          External Account ID

  • 404

    Statement not found

Definition
GET https://sandbox.canopyservicing.com/accounts/{account_id}/statements
cURL example
curl \ -X GET https://sandbox.canopyservicing.com/accounts/{account_id}/statements \ -H "Content-Type: application/json"
Response example (200)
{ "available_credit_balance": "600000", "total_balance": "400000", "account_id": "111eff36-cbec-4119-b188-b76200e804d8", "effective_as_of_date": "2018-07-20 09:10:14 UTC", "min_pay_due_date": "2020-05-04T09:42:00+00:00", "min_pay_amount_cents": 42.0, "billing_cycle_start_date": "2020-05-04T09:42:00+00:00", "billing_cycle_end_date": "2020-05-04T09:42:00+00:00", "line_items": [ { "account_id": "2911ff2a-bebe-4c85-8d19-e6001015a8e3", "line_item_id": "ce9ed376-f151-435f-a59c-9e3cc183bbea", "line_item_status": "posted", "type": "charge", "originating_amount_cents": 42.0, "balance_amount_cents": 42.0, "total_interest_accrued_cents": "16", "total_paid_down_cents": "1125", "rate": "15.5%", "merchant_data": { "name": "string", "id": "string", "mcc_code": 42.0, "phone_number": "string" }, "effective_at": "2018-07-20 09:12:30 UTC", "created_at": "2018-06-20 09:12:30 UTC", "product_id": "158cd7a1-d813-42d2-90a3-9a91c43f18f8", "description": "Refund for invalid purchase", "reference_id": "e39c6b0d-5793-49c5-bee7-a2dbf8808f3a", "dispute_id": "string", "external_ids": [ { "name": "Globex Card Processing", "id": "22445702-a389-431f-927d-07b8d0750787" } ] } ] }
Response example (404)
No content