API Overview
Canopy allows you to easily manage credit, installment, or other more complex lending programs 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 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.

Canopy additionally surfaces information around all of your lending activity through its intuitive UI which provides a customer support interface as well as at-a-glance data needed for compliance and insights.

Simply configure your product’s policies through our Create Product API endpoint, and then you can immediately begin adding customer accounts and relying on Canopy for accurate servicing information.

This is the documentation for version 1.1.1 of the API. Last update on Nov 23, 2021.

Base URL
https://sandbox-api.canopyservicing.com

Get started in three easy steps.

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

2) Create your own credentials in our public sandbox.

3) Follow the onboarding steps once you've logged into the public sandbox.

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.

To create your organization within Canopy, register for our public sandbox. You can find a full guide to authenticating in Canopy in our developer onboarding tutorial.

To get going quickly, we recommend using an API collaboration tool called Postman. You can use the buttons below to import our collection, which points to the environment you want to build against and already has our API endpoints configured. Be sure to define the required environment variables.

If you'd just like to get set up with Canopy and send some requests with pre-populated sample data, we recommend using our Quickstart collection.

When you'd like to start applying some business logic and try formulating what your actual implementation looks like, we recommend starting with our public sandbox.

Once you've explored our public sandbox and formulated your business model, you can test in our protected UAT environment.

Quickstart: Quickstart

Public Sandbox: Public Sandbox

Protected UAT: Protected UAT

Production: Run in Postman

Canopy uses a two-factor basis to drive the order of responses in GET requests with an array of results. They are first ordered by effective_at by when the entity is effective in the system, and second by an internal index to make sure the order is always universal. From the caller's perspective, you can let Canopy know where to start its pagination response by providing a starting_after or ending_before string value. If neither a starting_after nor ending_before value is provided, we'll assume you're requesting the very first page of responses. In subsequent requests, you can simply grab these values from the paging key in the response body from your previous request. If you're aiming to provide your users with a link to the previous page, use the ending_before query parameter in your next request. If going to the next page, use the starting_after value instead.


Get all API users in your organization

Returns a list of all API users in your organization.

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

      Phone number of the API user

    • role Required / integer

      The role of this user in the API

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    No Api Users found

  • 429

    Too many requests.

  • default

    Unexpected Error.

GET /api_users
curl \
 -X GET https://sandbox-api.canopyservicing.com/api_users \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
[
  {
    "api_user_id": "dc3d83c5-b31e-48eb-80e7-38f12ac1a6e5",
    "organization_name": "Lever Card 3000",
    "name_first": "Analise",
    "name_last": "Goldberg",
    "email": "marissa@globex.com",
    "phone": "1-123-456-7890",
    "role": 1
  }
]

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

    Assign a role to users to dictate permissions and API access level . Contact our team for a full list of options.

    Default value is 1.

  • 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

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 422

    Invalid input.

  • 429

    Too many requests.

  • default

    Unexpected Error.

POST /api_users
curl \
 -X POST https://sandbox-api.canopyservicing.com/api_users \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"role":3,"email":"marissa@globex.com"}'
Request example
{
  "role": 3,
  "email": "marissa@globex.com"
}
Response example (200)
{
  "email": "marissa@globex.com",
  "created_at": "2018-06-20T09:12:30+00:00",
  "expires_at": "2018-06-21T09:12:30+00:00"
}

Register a new organization and user

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

Body
  • name_first Required / string

    The first name of the API user.

  • name_last Required / string

    The last name of the API user.

  • password string

    The new password of the API user.

  • email Required / string(email)

    The email address of the API user

  • organization_name Required / string

    The organization name

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

      Phone number of the API user

    • role Required / integer

      The role of this user in the API

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not found.

  • 429

    Too many requests.

  • default

    Unexpected Error.

POST /register
curl \
 -X POST https://sandbox-api.canopyservicing.com/register \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"name_first":"Harriet","name_last":"Martins","password":"newSecretPassword123!","email":"harriet@acmecorporation.com","organization_name":"Acme Corporation"}'
Request example
{
  "name_first": "Harriet",
  "name_last": "Martins",
  "password": "newSecretPassword123!",
  "email": "harriet@acmecorporation.com",
  "organization_name": "Acme Corporation"
}
Response example (200)
{
  "api_user_id": "dc3d83c5-b31e-48eb-80e7-38f12ac1a6e5",
  "organization_name": "Lever Card 3000",
  "name_first": "Analise",
  "name_last": "Goldberg",
  "email": "marissa@globex.com",
  "phone": "1-123-456-7890",
  "role": 1
}

Get summary info for an API user

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

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

      Phone number of the API user

    • role Required / integer

      The role of this user in the API

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    No API user found.

  • 429

    Too many requests.

  • default

    Unexpected Error.

GET /api_users/summary
curl \
 -X GET https://sandbox-api.canopyservicing.com/api_users/summary \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "api_user_id": "dc3d83c5-b31e-48eb-80e7-38f12ac1a6e5",
  "organization_name": "Lever Card 3000",
  "name_first": "Analise",
  "name_last": "Goldberg",
  "email": "marissa@globex.com",
  "phone": "1-123-456-7890",
  "role": 1
}

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.

Query parameters
  • limit integer

    The maximum number of products to be returned. Defaults to 10.

    Minimum value is 0, maximum value is 100.

  • Pass the value from the paging response body in your previous request. If not provided, the zero-indexed starting point will be used. Either starting_after or ending_before may be provided, but not both.

  • ending_before string

    Pass the value from the paging response body in your previous request. If not provided, the zero-indexed starting point will be used. Either starting_after or ending_before may be provided, but not both.

Responses
  • 200 object

    Array of Products

    • results array[object]

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

      • product_id Required / string

        The Canopy-generated ID for the product.

      • created_at string(date-time)

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

      • effective_at string(date-time)

        The Date-Time as of which this product is effective on the server.

      • A unique external ID that may be used interchangeably with the Canopy-generated product ID

      • product_overview Required / object

        A series of static fields about the product.

      • product_lifecycle_policies Required / object
        • The set of policies governing payment due information for the product.

          • After this number of consecutive late events, the account status shifts to suspended with a status subtype of delinquent

            Default value is 1.

          • After this number of consecutive late events, the account status shifts to suspended with a status subtype of charged_off

            Default value is 2.

        • The set of policies governing payment pouring information for the product.

        • fee_policies object

          The set of policies governing fees for the product.

          • Defaults to 0 days. The amount of time after a payment is late after which you would like for a late fee to be incurred.

            Default value is 0 days.

          • The interval at which a surcharge fee is assessed.

          • The transaction volume structure that dictates a transaction fee.

            • surcharge_start_inclusive_cents Required / integer

              Indicates the starting transaction volume at which this fee will apply.

            • Indicates the ending transaction volume at which this fee will apply. If not provided, the surcharge will apply to any transaction volume above the defined start.

              Default value is 100000000000000000000.

            • percent_surcharge Required / number

              Indicates the surcharge fee as a percent of total transaction volume that will be applied to the account if the total transaction volume during the surcharge interval falls within the provided start and end range.

        • The set of policies governing the billing cycle for the product.

          • cycle_interval Required / string

            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)

          • Defaults to 0 days. The amount of time before statement cut that the payment should be due for the billing cycle. If positive, it will count days from the start of the cycle. Note, this field has a signage convention: if negative, it will count days back from the end of the cycle. IE '25 days' indicates that payments are due 25 days after the statement is cut. -5 days indicates that payments will be due five days prior to the cut of the next cycle. Cannot exceed the duration of the billing cycle.

            Default value is 0 days.

          • Defaults to 0 days. If applicable, the amount of time you would like between origination and the first statement cut. IE '10 days'. If you would like the first billing cycle to be the same length as all other billing cycles, either do not include this field in the request, or set its value to the same as billing_cycle_period

            Default value is 0 days.

          • close_of_business_time string(time)

            Defaults to EST Midnight. Time of the close of business. Note* this value will be converted into the product_time_zone This is used for statement cuts and partner-level and issuing bank-level reconciliation

            Default value is 23:59:59-05:00.

          • Timezone denoted as an Olson-style timezone defining the timezone for the product. All times in any response data for accounts using this product will be denominated in this timezone. Shifts due to daylight savings will be accounted for where relevant, and all output timestamps will be denoted as UTC offsets normalized based on this value. Defaults to America/New_York if not provided.

            Default value is America/New_York.

        • The Interest Policy Object

          • default_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.

            Default value is 0.

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

            Default value is 0.

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

            Default value is 0.

      • promotional_policies Required / object

        If applicable, a promotional configuration for the product.

        • promo_len integer

          The number of billing cycles from account origination during which accounts on this product are on a promotional period.

          Default value is 0.

        • Current due calculation method for the promotional period.

          Values are AM, PERCENT_INTEREST, PERCENT_PRINCIPAL, and NONE. Default value is NONE.

        • If applicable, the number of billing cycles from account origination under which this product falls under a purchas window period.

          Default value is 0.

        • Defaults to 100. The percent of new interest in the cycle used to determine the minimum payment.

          Default value is 100.

        • Indicates whether interest accrued during the promotional period is deferred interest.

        • The rate that serves as the active interest rate for accounts during the promotional period.

          Default value is 0.

        • Optional lower bound for APR Range for the product (i.e. 2 = 2%).

          Default value is 0.

        • Optional upper bound for APR Range for the product (i.e. 5 = 5%).

          Default value is 0.

      • post_promotional_policies Required / object
      • Summary of product information

      • admin object
        • migration_mode boolean

          If migration mode is on, Canopy will stop auto-generating statements for this account.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Unable to get products

  • 429

    Too many requests.

  • default

    Unexpected Error.

GET /products
curl \
 -X GET https://sandbox-api.canopyservicing.com/products \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "results": [
    {
      "product_id": "31mNprzLd2bKl6koVna68ARM",
      "created_at": "2019-03-20T09:12:28+00:00",
      "effective_at": "2016-11-27T13:19:56+00:00",
      "external_product_id": "95fea111-d121-40f8-9e8e-a6c335e48a45",
      "product_overview": {
        "product_name": "Blue Cash Express",
        "product_type": "REVOLVING",
        "product_short_description": "12mm3apr.",
        "product_long_description": "Student credit card.",
        "product_color": "#0000FF",
        "external_fields": [
          {
            "key": "client_product_id",
            "value": "3e93a899-d267-4193-8509-6dba53c13b7b"
          }
        ]
      },
      "product_lifecycle_policies": {
        "payment_due_policies": {
          "delinquent_on_n_consecutive_late_fees": 2,
          "charge_off_on_n_consecutive_late_fees": 5
        },
        "payment_pouring_policies": {
          "pending_pmt_affects_avail_credit": true
        },
        "fee_policies": {
          "late_fee_grace": "5 days",
          "surcharge_fee_interval": "1 month",
          "default_surcharge_fee_structure": [
            {
              "surcharge_start_inclusive_cents": 0,
              "surcharge_end_exclusive_cents": 0,
              "percent_surcharge": 0
            }
          ]
        },
        "billing_cycle_policies": {
          "cycle_interval": "1 month",
          "cycle_due_interval": "-5 days",
          "first_cycle_interval": "25 days",
          "close_of_business_time": "17:00:00-05:00",
          "product_time_zone": "America/Chicago"
        },
        "interest_policies": {
          "interest_calc_time": "11:21:04-08:00"
        },
        "default_attributes": {
          "default_credit_limit_cents": 600000,
          "default_late_fee_cents": 50000,
          "default_payment_reversal_fee_cents": 10000
        }
      },
      "promotional_policies": {
        "promo_len": 6,
        "promo_min_pay_type": "PERCENT_PRINCIPAL",
        "promo_purchase_window_len": 5,
        "promo_min_pay_percent": 100,
        "promo_interest_deferred": true,
        "promo_default_interest_rate_percent": 3,
        "promo_apr_range_inclusive_lower": 2,
        "promo_apr_range_inclusive_upper": 5
      },
      "post_promotional_policies": {
        "post_promo_len": 48,
        "post_promo_am_len_range_inclusive_lower": 2,
        "post_promo_am_len_range_inclusive_upper": 5,
        "post_promo_min_pay_type": "AM",
        "post_promo_default_interest_rate_percent": 3,
        "post_promo_apr_range_inclusive_lower": 2,
        "post_promo_apr_range_inclusive_upper": 5
      },
      "product_summary": {
        "accounts_overview": {
          "account_count_total": 10005
        }
      },
      "admin": {
        "migration_mode": true
      }
    }
  ]
}

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 sending an excel file detailing your preferred configurations to the Canopy team; however, you can also configure and manage products programmatically using this API documentation.

Request body for creating a new product.

Body
  • effective_at string(date-time)

    The Date-Time as of which this product is effective on the server. Your product should be older than all accounts enrolled in it.

    Default value is 1900-01-01T12:00:00+00:00.

  • A unique external ID that may be used interchangeably with the Canopy-generated product ID

  • product_overview Required / object

    A series of static fields about the product.

    • product_name Required / string

      Name of Product, i.e. BNPL 24 Month Standard.

    • product_type Required / string

      The Type of Product

      Values are REVOLVING, INSTALLMENT, MIXED_RATE_INSTALLMENT, DEFERRED_INSTALLMENT, and FIXED_RATE_INSTALLMENT. Default value is REVOLVING.

    • product_short_description Required / string

      A short description of the product ranging from 0 - 60 characters.

    • product_long_description Required / string

      Description of the Product ranging from 0 - 1000.

    • product_color string

      A color to be associated with the product for UI purposes.

      Default value is #4867FF.

  • product_lifecycle_policies Required / object
    • The set of policies governing payment due information for the product.

      • After this number of consecutive late events, the account status shifts to suspended with a status subtype of delinquent

        Default value is 1.

      • After this number of consecutive late events, the account status shifts to suspended with a status subtype of charged_off

        Default value is 2.

    • The set of policies governing payment pouring information for the product.

    • fee_policies object

      The set of policies governing fees for the product.

      • Defaults to 0 days. The amount of time after a payment is late after which you would like for a late fee to be incurred.

        Default value is 0 days.

      • The interval at which a surcharge fee is assessed.

      • The transaction volume structure that dictates a transaction fee.

        • surcharge_start_inclusive_cents Required / integer

          Indicates the starting transaction volume at which this fee will apply.

        • Indicates the ending transaction volume at which this fee will apply. If not provided, the surcharge will apply to any transaction volume above the defined start.

          Default value is 100000000000000000000.

        • percent_surcharge Required / number

          Indicates the surcharge fee as a percent of total transaction volume that will be applied to the account if the total transaction volume during the surcharge interval falls within the provided start and end range.

    • The set of policies governing the billing cycle for the product.

      • cycle_interval Required / string

        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)

      • Defaults to 0 days. The amount of time before statement cut that the payment should be due for the billing cycle. If positive, it will count days from the start of the cycle. Note, this field has a signage convention: if negative, it will count days back from the end of the cycle. IE '25 days' indicates that payments are due 25 days after the statement is cut. -5 days indicates that payments will be due five days prior to the cut of the next cycle. Cannot exceed the duration of the billing cycle.

        Default value is 0 days.

      • Defaults to 0 days. If applicable, the amount of time you would like between origination and the first statement cut. IE '10 days'. If you would like the first billing cycle to be the same length as all other billing cycles, either do not include this field in the request, or set its value to the same as billing_cycle_period

        Default value is 0 days.

      • close_of_business_time string(time)

        Defaults to EST Midnight. Time of the close of business. Note* this value will be converted into the product_time_zone This is used for statement cuts and partner-level and issuing bank-level reconciliation

        Default value is 23:59:59-05:00.

      • Timezone denoted as an Olson-style timezone defining the timezone for the product. All times in any response data for accounts using this product will be denominated in this timezone. Shifts due to daylight savings will be accounted for where relevant, and all output timestamps will be denoted as UTC offsets normalized based on this value. Defaults to America/New_York if not provided.

        Default value is America/New_York.

    • The Interest Policy Object

      • default_credit_limit_cents Required / integer

        The default maximum principal credit (in cents) available for a customer account. For risk-based-pricing, 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 in the Create Account call. Credit limits for an account can also be updated post-account creation.

        Default value is 0.

      • The default late fee for accounts enrolled in this product. This will be used if no late fee is provided at account creation.

        Default value is 0.

      • The default payment reversa fee for accounts enrolled in this product. This will be used if no late fee is provided at account creation.

        Default value is 0.

  • promotional_policies Required / object

    If applicable, a promotional configuration for the product.

    • promo_len integer

      Defaults to 0. The number of billing cycles from account origination during which accounts on this product are on a promotional period.

      Default value is 0.

    • Current due calculation method for the promotional period.

      Values are AM, PERCENT_INTEREST, PERCENT_PRINCIPAL, and NONE. Default value is NONE.

    • If applicable, the number of billing cycles from account origination under which this product falls under a purchas window period.

      Default value is 0.

    • Indicates whether interest accrued during the promotional period is deferred interest.

    • The rate that serves as the active interest rate for accounts during the promotional period.

      Default value is 0.

    • Defaults to 100. The percent of new interest in the cycle used to determine the minimum payment.

      Default value is 100.

    • Optional lower bound for APR Range for the product (i.e. 2 = 2%).

      Default value is 0.

    • Optional upper bound for APR Range for the product (i.e. 5 = 5%).

      Default value is 0.

  • post_promotional_policies Required / object
  • admin object
    • migration_mode boolean

      If migration mode is on, Canopy will stop auto-generating statements for this account.

Responses
  • 200 object

    Product

    • product_id Required / string

      The Canopy-generated ID for the product.

    • created_at string(date-time)

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

    • effective_at string(date-time)

      The Date-Time as of which this product is effective on the server.

    • A unique external ID that may be used interchangeably with the Canopy-generated product ID

    • product_overview Required / object

      A series of static fields about the product.

    • product_lifecycle_policies Required / object
      • The set of policies governing payment due information for the product.

        • After this number of consecutive late events, the account status shifts to suspended with a status subtype of delinquent

          Default value is 1.

        • After this number of consecutive late events, the account status shifts to suspended with a status subtype of charged_off

          Default value is 2.

      • The set of policies governing payment pouring information for the product.

      • fee_policies object

        The set of policies governing fees for the product.

        • Defaults to 0 days. The amount of time after a payment is late after which you would like for a late fee to be incurred.

          Default value is 0 days.

        • The interval at which a surcharge fee is assessed.

        • The transaction volume structure that dictates a transaction fee.

          • surcharge_start_inclusive_cents Required / integer

            Indicates the starting transaction volume at which this fee will apply.

          • Indicates the ending transaction volume at which this fee will apply. If not provided, the surcharge will apply to any transaction volume above the defined start.

            Default value is 100000000000000000000.

          • percent_surcharge Required / number

            Indicates the surcharge fee as a percent of total transaction volume that will be applied to the account if the total transaction volume during the surcharge interval falls within the provided start and end range.

      • The set of policies governing the billing cycle for the product.

        • cycle_interval Required / string

          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)

        • Defaults to 0 days. The amount of time before statement cut that the payment should be due for the billing cycle. If positive, it will count days from the start of the cycle. Note, this field has a signage convention: if negative, it will count days back from the end of the cycle. IE '25 days' indicates that payments are due 25 days after the statement is cut. -5 days indicates that payments will be due five days prior to the cut of the next cycle. Cannot exceed the duration of the billing cycle.

          Default value is 0 days.

        • Defaults to 0 days. If applicable, the amount of time you would like between origination and the first statement cut. IE '10 days'. If you would like the first billing cycle to be the same length as all other billing cycles, either do not include this field in the request, or set its value to the same as billing_cycle_period

          Default value is 0 days.

        • close_of_business_time string(time)

          Defaults to EST Midnight. Time of the close of business. Note* this value will be converted into the product_time_zone This is used for statement cuts and partner-level and issuing bank-level reconciliation

          Default value is 23:59:59-05:00.

        • Timezone denoted as an Olson-style timezone defining the timezone for the product. All times in any response data for accounts using this product will be denominated in this timezone. Shifts due to daylight savings will be accounted for where relevant, and all output timestamps will be denoted as UTC offsets normalized based on this value. Defaults to America/New_York if not provided.

          Default value is America/New_York.

      • The Interest Policy Object

        • default_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.

          Default value is 0.

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

          Default value is 0.

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

          Default value is 0.

    • promotional_policies Required / object

      If applicable, a promotional configuration for the product.

      • promo_len integer

        The number of billing cycles from account origination during which accounts on this product are on a promotional period.

        Default value is 0.

      • Current due calculation method for the promotional period.

        Values are AM, PERCENT_INTEREST, PERCENT_PRINCIPAL, and NONE. Default value is NONE.

      • If applicable, the number of billing cycles from account origination under which this product falls under a purchas window period.

        Default value is 0.

      • Defaults to 100. The percent of new interest in the cycle used to determine the minimum payment.

        Default value is 100.

      • Indicates whether interest accrued during the promotional period is deferred interest.

      • The rate that serves as the active interest rate for accounts during the promotional period.

        Default value is 0.

      • Optional lower bound for APR Range for the product (i.e. 2 = 2%).

        Default value is 0.

      • Optional upper bound for APR Range for the product (i.e. 5 = 5%).

        Default value is 0.

    • post_promotional_policies Required / object
    • Summary of product information

    • admin object
      • migration_mode boolean

        If migration mode is on, Canopy will stop auto-generating statements for this account.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 422

    Invalid input

  • 429

    Too many requests.

  • default

    Unexpected Error.

POST /products
curl \
 -X POST https://sandbox-api.canopyservicing.com/products \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"effective_at":"2016-11-27T13:19:56+00:00","external_product_id":"95fea111-d121-40f8-9e8e-a6c335e48a45","product_overview":{"product_name":"BNPL 24 Month Standard","product_type":"REVOLVING","product_short_description":"12mm3apr.","product_long_description":"Student credit card.","product_color":"#0000FF"},"product_lifecycle_policies":{"payment_due_policies":{"delinquent_on_n_consecutive_late_fees":2,"charge_off_on_n_consecutive_late_fees":5},"payment_pouring_policies":{"pending_pmt_affects...}'
Request example
{
  "effective_at": "2016-11-27T13:19:56+00:00",
  "external_product_id": "95fea111-d121-40f8-9e8e-a6c335e48a45",
  "product_overview": {
    "product_name": "BNPL 24 Month Standard",
    "product_type": "REVOLVING",
    "product_short_description": "12mm3apr.",
    "product_long_description": "Student credit card.",
    "product_color": "#0000FF"
  },
  "product_lifecycle_policies": {
    "payment_due_policies": {
      "delinquent_on_n_consecutive_late_fees": 2,
      "charge_off_on_n_consecutive_late_fees": 5
    },
    "payment_pouring_policies": {
      "pending_pmt_affects_avail_credit": true
    },
    "fee_policies": {
      "late_fee_grace": "5 days",
      "surcharge_fee_interval": "1 month",
      "default_surcharge_fee_structure": [
        {
          "surcharge_start_inclusive_cents": 0,
          "surcharge_end_exclusive_cents": 0,
          "percent_surcharge": 0
        }
      ]
    },
    "billing_cycle_policies": {
      "cycle_interval": "1 month",
      "cycle_due_interval": "-5 days",
      "first_cycle_interval": "25 days",
      "close_of_business_time": "17:00:00-05:00",
      "product_time_zone": "America/Chicago"
    },
    "interest_policies": {
      "interest_calc_time": "11:21:04-08:00"
    },
    "default_attributes": {
      "default_credit_limit_cents": 600000,
      "default_late_fee_cents": 3000,
      "default_payment_reversal_fee_cents": 3000
    }
  },
  "promotional_policies": {
    "promo_len": 6,
    "promo_min_pay_type": "PERCENT_PRINCIPAL",
    "promo_purchase_window_len": 5,
    "promo_interest_deferred": true,
    "promo_default_interest_rate_percent": 3,
    "promo_min_pay_percent": 100,
    "promo_apr_range_inclusive_lower": 2,
    "promo_apr_range_inclusive_upper": 5
  },
  "post_promotional_policies": {
    "post_promo_len": 48,
    "post_promo_am_len_range_inclusive_lower": 2,
    "post_promo_am_len_range_inclusive_upper": 5,
    "post_promo_min_pay_type": "AM",
    "post_promo_default_interest_rate_percent": 3,
    "post_promo_apr_range_inclusive_lower": 2,
    "post_promo_apr_range_inclusive_upper": 5
  },
  "admin": {
    "migration_mode": true
  }
}
Response example (200)
{
  "product_id": "31mNprzLd2bKl6koVna68ARM",
  "created_at": "2019-03-20T09:12:28+00:00",
  "effective_at": "2016-11-27T13:19:56+00:00",
  "external_product_id": "95fea111-d121-40f8-9e8e-a6c335e48a45",
  "product_overview": {
    "product_name": "Blue Cash Express",
    "product_type": "REVOLVING",
    "product_short_description": "12mm3apr.",
    "product_long_description": "Student credit card.",
    "product_color": "#0000FF",
    "external_fields": [
      {
        "key": "client_product_id",
        "value": "3e93a899-d267-4193-8509-6dba53c13b7b"
      }
    ]
  },
  "product_lifecycle_policies": {
    "payment_due_policies": {
      "delinquent_on_n_consecutive_late_fees": 2,
      "charge_off_on_n_consecutive_late_fees": 5
    },
    "payment_pouring_policies": {
      "pending_pmt_affects_avail_credit": true
    },
    "fee_policies": {
      "late_fee_grace": "5 days",
      "surcharge_fee_interval": "1 month",
      "default_surcharge_fee_structure": [
        {
          "surcharge_start_inclusive_cents": 0,
          "surcharge_end_exclusive_cents": 0,
          "percent_surcharge": 0
        }
      ]
    },
    "billing_cycle_policies": {
      "cycle_interval": "1 month",
      "cycle_due_interval": "-5 days",
      "first_cycle_interval": "25 days",
      "close_of_business_time": "17:00:00-05:00",
      "product_time_zone": "America/Chicago"
    },
    "interest_policies": {
      "interest_calc_time": "11:21:04-08:00"
    },
    "default_attributes": {
      "default_credit_limit_cents": 600000,
      "default_late_fee_cents": 50000,
      "default_payment_reversal_fee_cents": 10000
    }
  },
  "promotional_policies": {
    "promo_len": 6,
    "promo_min_pay_type": "PERCENT_PRINCIPAL",
    "promo_purchase_window_len": 5,
    "promo_min_pay_percent": 100,
    "promo_interest_deferred": true,
    "promo_default_interest_rate_percent": 3,
    "promo_apr_range_inclusive_lower": 2,
    "promo_apr_range_inclusive_upper": 5
  },
  "post_promotional_policies": {
    "post_promo_len": 48,
    "post_promo_am_len_range_inclusive_lower": 2,
    "post_promo_am_len_range_inclusive_upper": 5,
    "post_promo_min_pay_type": "AM",
    "post_promo_default_interest_rate_percent": 3,
    "post_promo_apr_range_inclusive_lower": 2,
    "post_promo_apr_range_inclusive_upper": 5
  },
  "product_summary": {
    "accounts_overview": {
      "account_count_total": 10005
    }
  },
  "admin": {
    "migration_mode": true
  }
}

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.

Query parameters
  • limit integer

    The maximum number of customer accounts to be returned. Defaults to 30.

    Minimum value is 0, maximum value is 100.

  • Pass the value from the paging response body in your previous request. If not provided, the zero-indexed starting point will be used. Either starting_after or ending_before may be provided, but not both.

  • ending_before string

    Pass the value from the paging response body in your previous request. If not provided, the zero-indexed starting point will be used. Either starting_after or ending_before may be provided, but not both.

  • Currently, this API only supports searching by name_first or name_last. Based on the input search parameter, the top responses from our API search, up to or less than the provided limit will be returned.

Responses
  • 200 object

    Array of Customers and their corresponding Accounts

    • results array[object]

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

      • customer_id Required / string

        A Canopy-generated ID for the customer.

      • name_prefix string

        Prefix to the customer's name. Primary account holder or controlling officer name for Business customers.

      • name_first string

        Customer's first name. Primary account holder or controlling officer name for Business customers.

      • name_middle string

        Customer's middle name. Primary account holder or controlling officer name for Business customers.

      • name_last string

        Customer's last name. Primary account holder or controlling officer name for Business customers.

      • name_suffix string

        Suffix to the customer's name

      • phone_number string

        Customer's phone number in E.164 format

      • Address line one.

      • Address line two.

      • address_city string

        Address city.

      • address_state string

        Address state.

      • address_zip string

        Five digit zipcode or nine digit 'ZIP+4'

      • ISO 3166-1 alpha-2 country code for the customer.

        Values are US, GB, CA, AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AN, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SK, SI, SB, SO, ZA, GS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, and ZW.

      • ssn string

        Social security number of the customer.

      • Any country-specific unique identifier for the customer.

      • email string(email)

        The email address of this Customer

      • date_of_birth string(date)

        Customer's date of birth in ISO 8601 format

      • The role of the customer for the account.

        Default value is PRIMARY.

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

        • lithic object
          • lithic_card object
            • last_four string

              Last four digits of the card number

            • memo string

              Friendly name to identify the card

            • type string

              The type of card created by Lithic

              Values are SINGLE_USE, MERCHANT_LOCKED, and UNLOCKED.

      • account object
        • account_id Required / string

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

        • created_at string(date-time)

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

        • effective_at string(date-time)

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

        • Note: The value passed here must be unique. This ties to a reference of your account in an external system. For example, you may have a ten digit loan number you use to reference the account.

          • account_status Required / string

            The Status of the Account. Active upon account creation.

            Default value is active.

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

        • The product associated with the account.

          • product_id Required / integer

            The Canopy-generated ID for the product.

          • A unique external ID that may be used interchangeably with the Canopy-generated product ID

            • product_name Required / string

              Name of Product, i.e. Express Card.

            • product_color string

              A color to be associated with the product for UI purposes.

              Default value is #4867FF.

            • Short description of the Product - max of 30 characters.

            • product_long_description Required / string

              Description of the Product.

            • Timezone denoted as an Olson-style timezone defining the timezone for the product. All times in any response data for accounts using this product will be denominated in this timezone. Shifts due to daylight savings will be accounted for where relevant, and all output timestamps will be denoted as UTC offsets normalized based on this value.

              Default value is America/New_York.

            • product_type Required / string

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

            • late_fee_impl_cents Required / integer

              The fee charged for late payments on the account.

              Default value is 0.

            • payment_reversal_fee_impl_cents Required / integer

              The fee charged for payment reversals on the account.

              Default value is 0.

            • The fee charged at the time of account origination

              Default value is 0.

            • An annual fee to be charged yearly from the date of account creation. It will reflect on the subsequent statement once incurred.

              Default value is 0.

            • A monthly fee to be charged monthly from the date of account creation. It will reflect on the subsequent statement once incurred.

              Default value is 0.

            • loan_end_date string(date-time)

              If applicable, the account's loan repayment date.

            • If applicable, the start date for a purchase window for the account

            • If applicable, the end date for a purchase window for the account

            • promo_inclusive_start string(date-time)

              If applicable, the start date for a promotional period for the account.

            • promo_exclusive_end string(date-time)

              If applicable, the start date for a promotional period for the account.

            • The percentage interest applied to the account during the promotional period (i.e. 6.2%)

              Default value is 0.

            • promo_len integer

              Defaults to 0. The number of billing cycles from account origination during which accounts on this product are on a promotional period.

            • promo_len integer

              The number of billing cycles from account origination during which accounts on this product are on a promotional period.

              Default value is 0.

            • If applicable, the number of billing cycles from account origination under which this product falls under a purchas window period.

              Default value is 0.

        • external_fields array[object]

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

          • key string

            key: i.e. Name of the External Party

          • value string

            value: i.e. External Account ID

          • statement_min_pay_cents Required / integer

            Total amount due for the billing cycle, summing cycle principal, interest, deferred interest, and fees outstanding.

            Default value is 0.

          • min_pay_due_at string(date-time)

            The Date-Time the payment for this billing cycle is due.

          • ach object

            ACH processing configuration.

          • debit_card object

            Debit processing configuration.

            • payment_processor_name Required / string

              Indicates the active payment processor whose configuration will be used for Debit card payments made from the account.

              Values are NONE and REPAY. Default value is NONE.

            • repay_config object
          • credit_card object

            Credit processing configuration.

            • payment_processor_name Required / string

              Indicates the active payment processor whose configuration will be used for Credit card payments made from the account.

              Values are NONE and CHECKOUT. Default value is NONE.

              • source_id string

                A Checkout.com payment source id or customer id.

              • card_token string

                The tokenized card number.

              • last_four string

                The last 4 digits of the card number.

              • expires_on string

                Expiration time for the card token.

          • autopay_enabled boolean

            Indicates whether autopay is enabled for this account. Currently, autopay is triggered 1 day prior to a payment due date. If default_payment_processor is set to NONE, autopay will not be triggered for account regardless of this field's value.

          • Configures the payment processor to be used for manual or autopay payments. This cannot be set to a value different from NONE if no valid ACH or Debit Card configs are provided.

            Values are ACH, DEBIT_CARD, CREDIT_CARD, and NONE. Default value is NONE.

          • lithic object
            • account_token string(uuid)

              The external unique identifier of the Lithic account against which charges are made.

        • cycle_type object
          • Interval for a first cycle for this account.

          • The amount of time after a payment is late after which you would like for a late fee to be incurred. If not provided, defaults to product's fee policy's late fee grace value

        • discounts object
        • summary object
          • The total balance (in cents) associated with the account.

          • principal_cents integer

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

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

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

            Default value is 0.

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

            Default value is 0.

          • The total AM deferred interest balance (in cents) associated with the account.

            Default value is 0.

          • The total sum of payments made to date (in cents) associated with the account.

          • The total sum of interest allocations for payments made to date (in cents) associated with the account.

          • credit_limit_cents Required / integer

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

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

            Default value is 0.

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

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

            Default value is 0.

          • If applicable, the total amount of available funds for continued purchase following a purchase window pattern, where payments made do not replenish amount available for purchase.

            Default value is 0.

          • The total amount needed to pay off the loan at this exact moment.

            Default value is 0.

          • Any number as a percentage (e.g. 5=> 5%). This is the maximum late fee that can be charged in this account: as determined by late_fee_cap_percent * minimum payment.

          • Any number as a percentage (e.g. 5=> 5%). This is the maximum reversal fee that can be charged in this account, as determined by payment_reversal_fee_cap_percent * account principal as if the payment never occurred (as opposed to after the payment but before it's reversed)

          • merchant_name string

            A merchant name associated with the account

          • lender_name string

            A lender name associated with the account

        • plaid_config object

          Plaid configurations.

            • valid_config Required / boolean

              Indicates whether Canopy has a valid Plaid access token.

            • valid_config Required / boolean

              Indicates whether Canopy has a valid Plaid account ID.

          • Indicates whether the balance check functionality is enabled with along side the payment processing. If set to true, the payment processing is enabled and the plaid access token and plaid account ID are valid, actions such as notifications etc. will be triggered.

    • paging object

      Pagination Information.

      • Use this to drive your next request if you want the next page of results

      • ending_before string

        Use this to drive your next request if you want the previous page of results

      • has_more boolean

        Indicates whether there are additional values beyond the ending index of the paginated results.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Unable to get customers

  • 429

    Too many requests.

  • default

    Unexpected Error.

GET /customers/accounts
curl \
 -X GET https://sandbox-api.canopyservicing.com/customers/accounts \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "results": [
    {
      "customer_id": "31mNprzLd2bKl6koVna68ARM",
      "name_prefix": "Dr.",
      "name_first": "Miriam",
      "name_middle": "Louise",
      "name_last": "Trevino",
      "name_suffix": "Jr",
      "phone_number": "+14105556789",
      "address_line_one": "12 Strawberry Road",
      "address_line_two": "Suite 101",
      "address_city": "Atlanta",
      "address_state": "GA",
      "address_zip": "99999-1000",
      "address_country_code": "US",
      "ssn": "888888888",
      "international_customer_id": "9999999999",
      "email": "marissa@protonmail.com",
      "date_of_birth": "1985-06-20",
      "business_details": {
        "business_legal_name": "Umbrella Corporation",
        "doing_business_as": "Umbrella",
        "business_ein": "888-88-8888"
      },
      "customer_account_role": "PRIMARY",
      "customer_account_external_id": "4465220133024156",
      "customer_account_issuer_processor_config": {
        "lithic": {
          "lithic_card": {
            "last_four": "1234",
            "memo": "Primary College Card",
            "type": "MERCHANT_LOCKED"
          }
        }
      },
      "account": {
        "account_id": "31mNprzLd2bKl6koVna68ARM",
        "created_at": "2017-06-20T09:12:14+00:00",
        "effective_at": "2018-03-20T09:12:28+00:00",
        "external_account_id": "95fea111-d121-40f8-9e8e-a6c335e48a45",
        "account_overview": {
          "account_status": "suspended",
          "account_status_subtype": "suspended-bankruptcy"
        },
        "account_product": {
          "product_id": 4,
          "external_product_id": "95fea111-d121-40f8-9e8e-a6c335e48a45",
          "product_overview": {
            "product_name": "Blue Cash Express",
            "product_color": "#0000FF",
            "product_short_description": "Consumer credit card",
            "product_long_description": "Student credit card.",
            "product_time_zone": "America/Chicago",
            "product_type": "REVOLVING"
          },
          "product_lifecycle": {
            "late_fee_impl_cents": 2900,
            "payment_reversal_fee_impl_cents": 2900,
            "origination_fee_impl_cents": 2000,
            "annual_fee_impl_cents": 1000,
            "monthly_fee_impl_cents": 500,
            "loan_end_date": "2013-01-13T05:25:13.813+00:00"
          },
          "promo_overview": {
            "promo_purchase_window_inclusive_start": "2013-01-13T05:25:13.813+00:00",
            "promo_purchase_window_exclusive_end": "2013-01-13T05:25:13.813+00:00",
            "promo_inclusive_start": "2013-01-13T05:25:13.813+00:00",
            "promo_exclusive_end": "2013-01-13T05:25:13.813+00:00",
            "promo_impl_interest_rate_percent": 6.2,
            "promo_len": 6
          },
          "post_promo_overview": {
            "post_promo_inclusive_start": "2013-01-13T05:25:13.813+00:00",
            "post_promo_exclusive_end": "2013-01-13T05:25:13.813+00:00",
            "post_promo_impl_interest_rate_percent": 6.2,
            "post_promo_len": 48
          },
          "product_duration_information": {
            "promo_len": 6,
            "promo_purchase_window_len": 5
          }
        },
        "external_fields": [
          {
            "key": "Umbrella Corporation",
            "value": "22445702-a389-431f-927d-07b8d0750787"
          }
        ],
        "min_pay_due_cents": {
          "statement_min_pay_cents": 160000,
          "min_pay_due_at": "2019-10-18T23:04:48.321+00:00"
        },
        "additional_statement_min_pay_details": {
          "statement_min_pay_charges_principal_cents": 100000,
          "statement_min_pay_interest_cents": 30000,
          "statement_min_pay_am_interest_cents": 200,
          "statement_min_pay_deferred_cents": 10000,
          "statement_min_pay_am_deferred_interest_cents": 200,
          "statement_min_pay_fees_cents": 20000,
          "previous_statement_min_pay_cents": 400000
        },
        "payment_processor_config": {
          "ach": {
            "payment_processor_name": "REPAY",
            "repay_config": {
              "ach_token": "string"
            },
            "dwolla_config": {
              "ach_token": "string"
            },
            "modern_treasury_config": {
              "ach_token": "string"
            }
          },
          "debit_card": {
            "payment_processor_name": "REPAY",
            "repay_config": {
              "card_token": "string"
            }
          },
          "credit_card": {
            "payment_processor_name": "CHECKOUT",
            "checkout_config": {
              "source_id": "cus_6artgoevd77u7ojah2wled32s",
              "card_token": "string",
              "last_four": "string",
              "expires_on": "string"
            }
          },
          "autopay_enabled": true,
          "default_payment_processor_method": "ACH"
        },
        "issuer_processor_details": {
          "lithic": {
            "account_token": "349e2031-20de-40c6-87a3-214895077522"
          }
        },
        "cycle_type": {
          "first_cycle_interval": "11 days",
          "late_fee_grace": "2 days"
        },
        "discounts": {
          "prepayment_discount_config": {
            "loan_discount_cents": 800000,
            "loan_discount_at": "2018-03-20T09:12:28+00:00"
          }
        },
        "summary": {
          "total_balance_cents": 300000,
          "principal_cents": 200000,
          "interest_balance_cents": 60000,
          "am_interest_balance_cents": 0,
          "deferred_interest_balance_cents": 40000,
          "am_deferred_interest_balance_cents": 0,
          "total_paid_to_date_cents": 40000,
          "total_interest_paid_to_date_cents": 10000,
          "credit_limit_cents": 400000,
          "max_approved_credit_limit_cents": 400000,
          "interest_rate_percent": 3,
          "available_credit_cents": 100000,
          "open_to_buy_cents": 5000,
          "total_payoff_cents": 900000,
          "late_fee_cap_percent": 12.5,
          "payment_reversal_fee_cap_percent": 6.2
        },
        "associated_entities": {
          "merchant_name": "Acme Corporation",
          "lender_name": "Globex Lending Corp"
        },
        "plaid_config": {
          "plaid_access_token": {
            "valid_config": true
          },
          "plaid_account_id": {
            "valid_config": true
          },
          "check_balance_enabled": true
        }
      }
    }
  ],
  "paging": {
    "starting_after": "31mNprzLd2bKl6koVna68ARM",
    "ending_before": "31mNprzLd2bKl6koVna68ARM",
    "has_more": false
  }
}

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 Required / string

    Customer's first name.

  • name_middle string

    Customer's middle name.

  • name_last Required / string

    Customer's last name.

  • name_suffix string

    Suffix to the customer's name.

  • phone_number Required / string

    Customer's phone number in E.164 format.

  • address_line_one Required / string

    Address line one.

  • Address line two.

  • address_city Required / string

    Address city.

  • address_state Required / string

    Address state.

  • address_zip Required / string

    Five digit zipcode or nine digit 'ZIP+4'.

  • ISO 3166-1 alpha-2 country code for the customer.

    Values are US, GB, CA, AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AN, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SK, SI, SB, SO, ZA, GS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, and ZW.

  • ssn string

    Social security number of the customer.

  • Any country-specific unique identifier for the customer.

  • email Required / string(email)

    The Customer's email address.

  • date_of_birth Required / string(date)

    Customer's date of birth in ISO 8601 format.

  • assign_to_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.

    • account_id string

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

    • The role of the customer for the account.

      Values are PRIMARY, SECONDARY, and CARDHOLDER. Default value is PRIMARY.

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

      • spend_limit integer

        Spending limit of card (in cents). If not provided, spending is still subject to the spend limit set at the issuer processor account (if any).

        Minimum value is 1.

      • lithic object
        • memo string

          Friendly name to identify the card.

        • type string

          The type of card created by Lithic.

          Values are SINGLE_USE, MERCHANT_LOCKED, and UNLOCKED.

        • state string

          The state of the new card.

          Values are OPEN and PAUSED.

        • card_program_token string(uuid)

          Token belonging to the card program under which to create the card.

Responses
  • 200 object

    New Customer Created

    • customer_id Required / string

      A Canopy-generated ID for the customer.

    • name_prefix string

      Prefix to the customer's name. Primary account holder or controlling officer name for Business customers.

    • name_first string

      Customer's first name. Primary account holder or controlling officer name for Business customers.

    • name_middle string

      Customer's middle name. Primary account holder or controlling officer name for Business customers.

    • name_last string

      Customer's last name. Primary account holder or controlling officer name for Business customers.

    • name_suffix string

      Suffix to the customer's name

    • phone_number string

      Customer's phone number in E.164 format

    • Address line one.

    • Address line two.

    • address_city string

      Address city.

    • address_state string

      Address state.

    • address_zip string

      Five digit zipcode or nine digit 'ZIP+4'

    • ISO 3166-1 alpha-2 country code for the customer.

      Values are US, GB, CA, AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AN, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SK, SI, SB, SO, ZA, GS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, and ZW.

    • ssn string

      Social security number of the customer.

    • Any country-specific unique identifier for the customer.

    • email string(email)

      The email address of this Customer

    • date_of_birth string(date)

      Customer's date of birth in ISO 8601 format

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 422

    Invalid input

  • 429

    Too many requests.

  • default

    Unexpected Error.

POST /customers
curl \
 -X POST https://sandbox-api.canopyservicing.com/customers \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"name_prefix":"Dr.","name_first":"Miriam","name_middle":"Louise","name_last":"Trevino","name_suffix":"Jr","phone_number":"+14105556789","address_line_one":"12 Strawberry Road","address_line_two":"Suite 101","address_city":"Atlanta","address_state":"GA","address_zip":"99999-1000","address_country_code":"US","ssn":"888888888","international_customer_id":"9999999999","email":"marissa@protonmail.com","date_of_birth":"1985-06-20","business_details":{"business_legal_name":"Umbrella Corporation","...}'
Request example
{
  "name_prefix": "Dr.",
  "name_first": "Miriam",
  "name_middle": "Louise",
  "name_last": "Trevino",
  "name_suffix": "Jr",
  "phone_number": "+14105556789",
  "address_line_one": "12 Strawberry Road",
  "address_line_two": "Suite 101",
  "address_city": "Atlanta",
  "address_state": "GA",
  "address_zip": "99999-1000",
  "address_country_code": "US",
  "ssn": "888888888",
  "international_customer_id": "9999999999",
  "email": "marissa@protonmail.com",
  "date_of_birth": "1985-06-20",
  "business_details": {
    "business_legal_name": "Umbrella Corporation",
    "doing_business_as": "Umbrella",
    "business_ein": "888-88-8888"
  },
  "assign_to_accounts": [
    {
      "account_id": "31mNprzLd2bKl6koVna68ARM",
      "customer_account_role": "PRIMARY",
      "customer_account_external_id": "4465220133024156",
      "customer_account_issuer_processor_config": {
        "spend_limit": 8000000,
        "lithic": {
          "memo": "Primary College Card",
          "type": "MERCHANT_LOCKED",
          "state": "OPEN",
          "card_program_token": "a5e38341-cc95-4a9b-a21c-751aeca67e9c"
        }
      }
    }
  ]
}
Response example (200)
{
  "customer_id": "31mNprzLd2bKl6koVna68ARM",
  "name_prefix": "Dr.",
  "name_first": "Miriam",
  "name_middle": "Louise",
  "name_last": "Trevino",
  "name_suffix": "Jr",
  "phone_number": "+14105556789",
  "address_line_one": "12 Strawberry Road",
  "address_line_two": "Suite 101",
  "address_city": "Atlanta",
  "address_state": "GA",
  "address_zip": "99999-1000",
  "address_country_code": "US",
  "ssn": "888888888",
  "international_customer_id": "9999999999",
  "email": "marissa@protonmail.com",
  "date_of_birth": "1985-06-20",
  "business_details": {
    "business_legal_name": "Umbrella Corporation",
    "doing_business_as": "Umbrella",
    "business_ein": "888-88-8888"
  }
}
Path parameters
Body
  • spend_limit integer

    Spending limit of card (in cents). If not provided, spending is still subject to the spend limit set at the issuer processor account (if any).

    Minimum value is 1.

  • lithic object
    • token Required / string

      External identifier for card in Lithic.

    • memo string

      Friendly name to identify the card

    • state string

      The new state of the card. Note: "CLOSED" cannot be undone.

      Values are OPEN, PAUSED, and CLOSED.

Responses
  • 200 array[object]

    Successfully created a new card for the customer.

    • spend_limit integer

      Spending limit of card (in cents). If not provided, spending is still subject to the spend limit set at the issuer processor account (if any).

      Minimum value is 1.

    • lithic object
      • type string

        The type of card being returned

        Values are UNLOCKED, MERCHANT_LOCKED, and SINGLE_USE.

      • state string

        The current state of the card

        Values are OPEN, PAUSED, and CLOSED.

      • token string(uuid)

        Unique external identifier for the card

      • last_four string

        Last four digits of the card

      • memo string

        Friendly name to identify the card

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 422

    Invalid input

  • 429

    Too many requests.

  • default

    Unexpected Error.

PUT /accounts/{account_id}/customers/{customer_id}/cards
curl \
 -X PUT https://sandbox-api.canopyservicing.com/accounts/31mNprzLd2bKl6koVna68ARM/customers/jNxDp2ybR5M72LaBA83e06md/cards \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"spend_limit":8000000,"lithic":{"token":"5c7678a6-db0e-4c24-9ad4-73eb0f719724","memo":"Primary Business Card","state":"OPEN"}}'
Request example
{
  "spend_limit": 8000000,
  "lithic": {
    "token": "5c7678a6-db0e-4c24-9ad4-73eb0f719724",
    "memo": "Primary Business Card",
    "state": "OPEN"
  }
}
Response example (200)
[
  {
    "spend_limit": 8000000,
    "lithic": [
      {
        "type": "UNLOCKED",
        "state": "OPEN",
        "token": "adccd28d-532e-480b-a063-a46a77a15570",
        "last_four": "0690",
        "memo": "Conference Event Card"
      }
    ]
  }
]
Path parameters
Body
  • spend_limit integer

    Spending limit of card (in cents). If not provided, spending is still subject to the spend limit set at the issuer processor account (if any).

    Minimum value is 1.

  • lithic object
    • memo string

      Friendly name to identify the card

    • type string

      The type of card created by Lithic

      Values are SINGLE_USE, MERCHANT_LOCKED, and UNLOCKED.

    • state string

      The state of the new card

      Values are OPEN and PAUSED.

    • card_program_token string(uuid)

      Token belonging to the card program under which to create the card.

Responses
  • 200 array[object]

    Successfully created a new card for the customer.

    • spend_limit integer

      Spending limit of card (in cents). If not provided, spending is still subject to the spend limit set at the issuer processor account (if any).

      Minimum value is 1.

    • lithic object
      • type string

        The type of card being returned

        Values are UNLOCKED, MERCHANT_LOCKED, and SINGLE_USE.

      • state string

        The current state of the card

        Values are OPEN, PAUSED, and CLOSED.

      • token string(uuid)

        Unique external identifier for the card

      • last_four string

        Last four digits of the card

      • memo string

        Friendly name to identify the card

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 422

    Invalid input

  • 429

    Too many requests.

  • default

    Unexpected Error.

POST /accounts/{account_id}/customers/{customer_id}/cards
curl \
 -X POST https://sandbox-api.canopyservicing.com/accounts/31mNprzLd2bKl6koVna68ARM/customers/jNxDp2ybR5M72LaBA83e06md/cards \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"spend_limit":8000000,"lithic":{"memo":"Primary College Card","type":"MERCHANT_LOCKED","state":"OPEN","card_program_token":"a5e38341-cc95-4a9b-a21c-751aeca67e9c"}}'
Request example
{
  "spend_limit": 8000000,
  "lithic": {
    "memo": "Primary College Card",
    "type": "MERCHANT_LOCKED",
    "state": "OPEN",
    "card_program_token": "a5e38341-cc95-4a9b-a21c-751aeca67e9c"
  }
}
Response example (200)
[
  {
    "spend_limit": 8000000,
    "lithic": [
      {
        "type": "UNLOCKED",
        "state": "OPEN",
        "token": "adccd28d-532e-480b-a063-a46a77a15570",
        "last_four": "0690",
        "memo": "Conference Event Card"
      }
    ]
  }
]

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
  • effective_at string(date-time)

    The Date-Time as of which this account is effective on the server.

  • product_id string

    A unique product ID generated by Canopy.

  • Note: The value passed here must be unique. A unique external ID that may be used interchangeably with the Canopy-generated product ID. Either external ID or Canopy product ID must be passed at the time of account creation.

  • Note: The value passed here must be unique. This ties to a reference of your account in an external system. For example, you may have a ten digit loan number you use to reference the account.

  • external_fields array[object]

    External fields can be used to relate accounts created in Canopy to entities in your or any external system.

    • key string

      key: i.e. Name of the External Party

    • value string

      value: i.e. External Account ID

    • ach object

      ACH processing configuration.

      • payment_processor_name Required / string

        Indicates the active payment processor whose configuration will be used for ACH/Debit card payments made from the account.

        Values are NONE, REPAY, DWOLLA, and MODERN_TREASURY. Default value is NONE.

      • repay_config object

        Sensitive bank information will be stored as a secured token for payments in place of the raw account details.

        • repay_check_type Required / string

          Type of checking account: Personal or Business.

          Values are PERSONAL and BUSINESS.

        • repay_account_type Required / string

          Type of account: Savings or Checking.

          Values are SAVINGS and CHECKING.

        • repay_transit_number Required / string

          Transit number is a nine-digit code based on the U.S. Bank location where your account was opened.

        • repay_account_number Required / string

          Account number is an eight to ten digit number that identifies a specific account.

        • repay_name_on_check Required / string

          Account holder's name as it appears on the account.

      • dwolla_config object

        Dwolla account verified and tokenized using Plaid.

      • Store bank details or a secured token for payments.

        • name Required / string

          Account holder's name as it appears on the account.

        • Account number is an eight to ten digit number that identifies a specific account.

        • account_type string

          Type of account: Savings or Checking.

          Values are SAVINGS and CHECKING.

        • Routing number is a nine-digit code based on the U.S. Bank location where your account was opened.

        • Plaid processor token retrieved from Plaid Link.

    • debit_card object

      Debit processing configuration.

      • payment_processor_name Required / string

        Indicates the active payment processor whose configuration will be used for payments made from the account. If NONE, Canopy will not trigger payments to an external payment processor when they occur.

        Values are NONE and REPAY. Default value is NONE.

      • repay_config object

        Sensitive debit card information will be stored as a secured token for payments in place of the raw account details.

        • repay_card_number Required / string

          16 digit debit card number.

        • repay_exp_date Required / string

          The card expiration date in the format MMYY.

        • repay_name_on_card Required / string

          The card holder's name as it appears on the card.

        • repay_street Required / string

          The card holder's billing street address.

        • repay_zip Required / string

          The card holder's billing zip code.

    • credit_card object

      Credit processing configuration.

      • payment_processor_name Required / string

        Indicates the active payment processor whose configuration will be used for Credit card payments made from the account.

        Values are NONE and CHECKOUT. Default value is NONE.

    • autopay_enabled boolean

      Indicates whether autopay is enabled for this account. Currently, autopay is triggered 1 day prior to a payment due date. If default_payment_processor is set to NONE, autopay will not be triggered for account regardless of this field's value.

    • Configures the payment processor to be used for manual or autopay payments. This cannot be set to a value different from NONE if no valid ACH or Debit Card configs are provided.

      Values are ACH, DEBIT_CARD, CREDIT_CARD, and NONE. Default value is NONE.

  • cycle_type object
    • Interval for a first cycle for this account.

    • The amount of time after a payment is late after which you would like for a late fee to be incurred. If not provided, defaults to product's fee policy's late fee grace value

  • discounts object
  • summary object
    • Total amount (in cents) that this account can borrow.

    • Total amount (in cents) that this account can borrow.

    • late_fee_cents integer

      The fee charged for late payments on the account.

    • The fee charged for payment reversals on the account.

    • The fee charged at the time of account origination

      Default value is 0.

    • An annual fee to be charged yearly from the date of account creation. It will reflect on the subsequent statement once incurred.

      Default value is 0.

    • A monthly fee to be charged monthly from the date of account creation. It will reflect on the subsequent statement once incurred.

      Default value is 0.

    • The initial principal balance (in cents) for the account.

    • Any number as a percentage (e.g. 5=> 5%). This is the maximum late fee that can be charged in this account: as determined by late_fee_cap_percent * minimum payment.

    • Any number as a percentage (e.g. 5=> 5%). This is the maximum reversal fee that can be charged in this account, as determined by payment_reversal_fee_cap_percent * account principal as if the payment never occurred (as opposed to after the payment but before it's reversed)

    • merchant_name string

      A merchant name associated with the account

    • lender_name string

      A lender name associated with the account

  • plaid_config object

    Plaid configurations.

    • plaid_access_token Required / string

      The access token generated by Plaid after the bank account validation.

    • plaid_account_id Required / string

      The account ID returned by Plaid for the particular account selected by the user at the time of bank account validation.

    • Indicates whether the balance check functionality is enabled with along side the payment processing. If set to true, the payment processing is enabled and the plaid access token and plaid account ID are valid, actions such as notifications etc. will be triggered.

  • assign_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.

    • customer_id Required / string

      A unique account ID generated by Canopy.

    • The role of the customer for the account.

      Values are PRIMARY and SECONDARY.

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

      • spend_limit integer

        Spending limit of card (in cents). If not provided, spending is still subject to the spend limit set at the issuer processor account (if any).

        Minimum value is 1.

      • lithic object
        • memo string

          Friendly name to identify the card

        • type string

          The type of card created by Lithic

          Values are SINGLE_USE, MERCHANT_LOCKED, and UNLOCKED.

        • state string

          The state of the new card

          Values are OPEN and PAUSED.

        • card_program_token string(uuid)

          Token belonging to the card program under which to create the card.

Responses
  • 200 object

    Successful query of information for a specific account

    • account_id string

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

    • created_at string(date-time)

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

    • effective_at string(date-time)

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

    • Note: The value passed here must be unique. This ties to a reference of your account in an external system. For example, you may have a ten digit loan number you use to reference the account.

      • account_status Required / string

        The Status of the Account. Active upon account creation.

        Default value is active.

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

    • The product associated with the account.

      • product_id Required / integer

        The Canopy-generated ID for the product.

      • A unique external ID that may be used interchangeably with the Canopy-generated product ID

        • product_name Required / string

          Name of Product, i.e. Express Card.

        • product_color string

          A color to be associated with the product for UI purposes.

          Default value is #4867FF.

        • Short description of the Product - max of 30 characters.

        • product_long_description Required / string

          Description of the Product.

        • Timezone denoted as an Olson-style timezone defining the timezone for the product. All times in any response data for accounts using this product will be denominated in this timezone. Shifts due to daylight savings will be accounted for where relevant, and all output timestamps will be denoted as UTC offsets normalized based on this value.

          Default value is America/New_York.

        • product_type Required / string

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

        • late_fee_impl_cents Required / integer

          The fee charged for late payments on the account.

          Default value is 0.

        • payment_reversal_fee_impl_cents Required / integer

          The fee charged for payment reversals on the account.

          Default value is 0.

        • The fee charged at the time of account origination

          Default value is 0.

        • An annual fee to be charged yearly from the date of account creation. It will reflect on the subsequent statement once incurred.

          Default value is 0.

        • A monthly fee to be charged monthly from the date of account creation. It will reflect on the subsequent statement once incurred.

          Default value is 0.

        • loan_end_date string(date-time)

          If applicable, the account's loan repayment date.

        • If applicable, the start date for a purchase window for the account

        • If applicable, the end date for a purchase window for the account

        • promo_inclusive_start string(date-time)

          If applicable, the start date for a promotional period for the account.

        • promo_exclusive_end string(date-time)

          If applicable, the start date for a promotional period for the account.

        • The percentage interest applied to the account during the promotional period (i.e. 6.2%)

          Default value is 0.

        • promo_len integer

          Defaults to 0. The number of billing cycles from account origination during which accounts on this product are on a promotional period.