Canopy Servicing Core API - Latest
1.8.44

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.8.44 of the API. Last update on Mar 11, 2022.

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

Getting Started

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.

Authentication

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.

Test it out

To get going quickly, we recommend using an API collaboration tool called Postman. You can use the buttons below to import our public collections, which point to our public test environment and already has our API endpoints configured. Be sure to define the required environment variables before sending requests.

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.

Our Use Cases collection contains some workflows that help demonstrate how our API serves business needs today.

When you'd like to start applying some business logic and try formulating what your actual implementation looks like, our Canopy API collection contains examples of all our API calls.

Once you've explored our public sandbox and formulated your business model, contact us to start the conversation on integrating Canopy with your business.

Quickstart: Quickstart

Use Cases: Use Cases

Canopy API: Canopy API

Pagination

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.

Document Versioning

Canopy currently supports two methods of identifying resources in our API endpoints. Please see your organization's features for which document describes your implementation.
If strict_entity_client_id = true, then see our latest documentation here.
Otherwise, please see our legacy documentation here


API Users

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

Get all API users in your organization

GET /api_users

Returns a list of all API users in your organization.

Responses

  • 200 array[object] | null

    Array of API Users

    • api_user_id string Required

      The unique ID in Canopy for this API user

    • organization_name string Required

      The organization to which the API user belongs.

    • name_first string Required

      The first name of the API user.

    • name_last string Required

      The last name of the API user.

    • email string(email) Required

      The email address of this API User

    • phone string | null

      Phone number of the API user

    • role integer Required

      The role of this user in the API

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    No Api Users found

  • 429

    Too many requests.

  • 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

POST /api_users

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 Required

Body of request to invite new API user. Checks permissions of invite-creator.

  • role number Required

    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 string(email) Required

    The email address of this API User.

  • name_first string Required

    The first name of the API User.

  • name_last string Required

    The last name of the API User.

  • phone string

    Phone number of API user

Responses

  • 200 object

    Successfully invited a new user

    • status string Required

      Result of API user creation request

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 422

    Invalid input.

  • 429

    Too many requests.

  • 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","name_first":"John","name_last":"Doe","phone":"1-234-567-8900"}'
Request example
{
  "role": 3,
  "email": "marissa@globex.com",
  "name_first": "John",
  "name_last": "Doe",
  "phone": "1-234-567-8900"
}
Response example (200)
{
  "status": "success"
}

Register a new organization and user

POST /register

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

Body Required

Provide valid credentials, this route updates an API User's password.

Responses

  • 200 object

    API user successfully registered

    • api_user_id string Required

      The unique ID in Canopy for this API user

    • organization_name string Required

      The organization to which the API user belongs.

    • name_first string Required

      The first name of the API user.

    • name_last string Required

      The last name of the API user.

    • email string(email) Required

      The email address of this API User

    • phone string | null

      Phone number of the API user

    • role integer Required

      The role of this user in the API

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Not found.

  • 429

    Too many requests.

  • 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

GET /api_users/summary

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

Responses

  • 200 object

    API User

    • api_user_id string Required

      The unique ID in Canopy for this API user

    • organization_name string Required

      The organization to which the API user belongs.

    • name_first string Required

      The first name of the API user.

    • name_last string Required

      The last name of the API user.

    • email string(email) Required

      The email address of this API User

    • phone string | null

      Phone number of the API user

    • role integer Required

      The role of this user in the API

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    No API user found.

  • 429

    Too many requests.

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

Products

Create and launch credit products within the Canopy system.

Get all available products

GET /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.

  • 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] | null Required

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

      Not more than 100 elements.

      • product_id string Required

        A unique ID to identify the product with for future requests. If not provided at the time of product creation, Canopy will generate one.

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

      • product_overview object Required

        A series of static fields about the product.

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

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

        • The set of policies governing fees for the product.

          • Amount of time between when a payment is due and when a late fee is assessed if no payments have been made.

            Default value is 5 days.

          • The interval at which a surcharge fee is assessed.

          • The transaction volume structure that dictates a transaction fee.

            • 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 number Required

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

            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)

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

          • Defaults to value of cycle_interval. 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 cycle_interval

          • 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

          • Being deprecated under our backwards compatibility policy in favor of close_of_business time and timezone variables. Defaults to statement cut time Interest for this policy is calculated at this time every X interval.

            Default value is 01:00:00-05:00.

          • Speaks to how interest is calculated for accounts under this product.
            cycle_end_12: interest amount = [principal] * (r/12) :: calculated once at the end of the cycle
            daily_end_365: interest amount = [principal](r/365) :: calculated at the end of each day
            daily_end_360: interest amount = [principal]
            (r/360) :: interest accrues at the end of each day
            avg_daily_12: interest amount = [avg_daily_principal] * (r/12) :: interest accrues once per cycle.

            Values are cycle_end_12, avg_daily_12, daily_end_365, or daily_end_360. Default value is cycle_end_12.

          • 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 object Required

        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, PERCENT_PRINCIPAL_INTEREST, or 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.

          Default value is false.

        • If set to true, the promo end date will be reset to end of current cycle + promo_len when the account draws its first charge during the promo period. If no charges occur during the promo period, the promo period will still end on the date set at account creation.

          Default value is false.

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

      • Summary of product information

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

          Default value is false.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Unable to get products

  • 429

    Too many requests.

  • Unexpected Error.

GET /products
curl \
 -X GET https://sandbox-api.canopyservicing.com/products \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "results": [
    {
      "product_id": "95fea111-d121-40f8-9e8e-a6c335e48a45",
      "created_at": "2019-03-20T09:12:28+00:00",
      "effective_at": "2016-11-27T13:19:56+00:00",
      "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",
          "interest_calc_method": "avg_daily_12"
        },
        "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_reset_on_first_charge": 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

POST /products

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 Required

  • 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 ID to identify the product with for future requests. If not provided at the time of product creation, Canopy will generate one.

    Format should match the following pattern: ^(?!can_).*$.

  • product_overview object Required

    A series of static fields about the product.

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

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

    • The set of policies governing fees for the product.

      • Amount of time between when a payment is due and when a late fee is assessed if no payments have been made.

        Default value is 5 days.

      • The interval at which a surcharge fee is assessed.

      • The transaction volume structure that dictates a transaction fee.

        • 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 number Required

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

        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)

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

      • Defaults to value of cycle_interval. 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 cycle_interval

      • 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

      • Being deprecated under our backwards compatibility policy in favor of close_of_business time and timezone variables. Defaults to statement cut time Interest for this policy is calculated at this time every X interval.

        Default value is 01:00:00-05:00.

      • Speaks to how interest is calculated for accounts under this product.
        cycle_end_12: interest amount = [principal] * (r/12) :: calculated once at the end of the cycle
        daily_end_365: interest amount = [principal](r/365) :: calculated at the end of each day
        daily_end_360: interest amount = [principal]
        (r/360) :: interest accrues at the end of each day
        avg_daily_12: interest amount = [avg_daily_principal] * (r/12) :: interest accrues once per cycle.

        Values are cycle_end_12, avg_daily_12, daily_end_365, or daily_end_360. Default value is cycle_end_12.

      • 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 object Required

    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, PERCENT_PRINCIPAL_INTEREST, or 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.

      Default value is false.

    • If set to true, the promo end date will be reset to end of current cycle + promo_len when the account draws its first charge during the promo period. If no charges occur during the promo period, the promo period will still end on the date set at account creation.

      Default value is false.

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

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

      Default value is false.

Responses

  • 200 object

    Product

    • product_id string Required

      A unique ID to identify the product with for future requests. If not provided at the time of product creation, Canopy will generate one.

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

    • product_overview object Required

      A series of static fields about the product.

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

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

      • The set of policies governing fees for the product.

        • Amount of time between when a payment is due and when a late fee is assessed if no payments have been made.

          Default value is 5 days.

        • The interval at which a surcharge fee is assessed.

        • The transaction volume structure that dictates a transaction fee.

          • 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 number Required

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

          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)

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

        • Defaults to value of cycle_interval. 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 cycle_interval

        • 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

        • Being deprecated under our backwards compatibility policy in favor of close_of_business time and timezone variables. Defaults to statement cut time Interest for this policy is calculated at this time every X interval.

          Default value is 01:00:00-05:00.

        • Speaks to how interest is calculated for accounts under this product.
          cycle_end_12: interest amount = [principal] * (r/12) :: calculated once at the end of the cycle
          daily_end_365: interest amount = [principal](r/365) :: calculated at the end of each day
          daily_end_360: interest amount = [principal]
          (r/360) :: interest accrues at the end of each day
          avg_daily_12: interest amount = [avg_daily_principal] * (r/12) :: interest accrues once per cycle.

          Values are cycle_end_12, avg_daily_12, daily_end_365, or daily_end_360. Default value is cycle_end_12.

        • 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 object Required

      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, PERCENT_PRINCIPAL_INTEREST, or 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.

        Default value is false.

      • If set to true, the promo end date will be reset to end of current cycle + promo_len when the account draws its first charge during the promo period. If no charges occur during the promo period, the promo period will still end on the date set at account creation.

        Default value is false.

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

    • Summary of product information

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

        Default value is false.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 422

    Invalid input

  • 429

    Too many requests.

  • 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","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","interest_calc_method":"avg_daily_12"},"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_INTEREST","promo_purchase_window_len":5,"promo_interest_deferred":true,"promo_reset_on_first_charge":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}}'
Request example
{
  "effective_at": "2016-11-27T13:19:56+00:00",
  "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",
      "interest_calc_method": "avg_daily_12"
    },
    "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_INTEREST",
    "promo_purchase_window_len": 5,
    "promo_interest_deferred": true,
    "promo_reset_on_first_charge": 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": "95fea111-d121-40f8-9e8e-a6c335e48a45",
  "created_at": "2019-03-20T09:12:28+00:00",
  "effective_at": "2016-11-27T13:19:56+00:00",
  "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",
      "interest_calc_method": "avg_daily_12"
    },
    "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_reset_on_first_charge": 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
  }
}

Customers

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

Get all accounts for all customers

GET /customers/accounts

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.

  • 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 | null] Required

      Passport information. required if country is not US

      Not more than 1000 elements.

      • address_line_one string Required

        Address line one.

      • Address line two.

      • address_city string Required

        Address city.

      • address_state string Required

        Address state.

      • address_zip string Required

        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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

      • Prefix to the customer's name.

      • Customer's first name.

      • Customer's middle name.

      • Customer's last name.

      • Suffix to the customer's name.

      • passport object
        • number string Required

          Number on the passport

        • country string Required

          ISO 3166-1 Two letter code for the issuing country

      • customer_id string Required

        A Canopy-generated ID for the customer.

      • The customer can be either a person or a business. This is used to explicitly set that and adjust behavior such as validation.

        Values are person or business.

      • The verification status of this customer. The default is 'unverified'. Depending on the system's configuration verification with third parties will happen and the status will be updated based on the result.

        Values are unverified, verified, retry, or document.

      • title string

        Title of the customer if a person OR title of the admin if a business

      • Customer's phone number in E.164 format

      • 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 DBA name of the Business

        • EIN of the business, expected format in NN-NNNNNNN.

        • Type of business is used in determining the appropriate validation.

          Values are sole_proprietorship, llc, unincorporated_association, trust, corporation, corporation_public, non_profile, or partnership.

        • UUID that references the business classification. This will eventually be supported by a reference api, however, for now refer to dwolla's specific UUID.

        • website string

          URL for the buesiness's website. This should be publicly resolvable

        • controller object | null

          Passport information. required if country is not US

          • address_line_one string Required

            Address line one.

          • Address line two.

          • address_city string Required

            Address city.

          • address_state string Required

            Address state.

          • address_zip string Required

            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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

          • Prefix to the customer's name.

          • Customer's first name.

          • Customer's middle name.

          • Customer's last name.

          • Suffix to the customer's name.

          • passport object
            • number string Required

              Number on the passport

            • country string Required

              ISO 3166-1 Two letter code for the issuing country

          • title string

            Title of the customer if a person OR title of the admin if a business

          • Customer's phone number in E.164 format.

          • ssn string

            Social security number of the customer.

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

      • account object
        • account_id string Required

          This is the ID used to identify the account in your system. For most use-cases, we strongly recommend using the ID from the system the account was originally created in -- for most use-cases, this is created as part of the origination system that approves a borrower. This will be the account that is used to refer to the borrower for all subsequent requests. Note: both strings and integers are accepted.

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

          • account_status string Required

            The Status of the Account. Active upon account creation.

            Values are ACTIVE, SUSPENDED, or CLOSED. Default value is ACTIVE.

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

            Values are , INACTIVITY, INELIGIBLE, DELINQUENT, CHARGE_OFF, GRANTOR_REQUEST, BANKRUPTCY, PAID_OFF, SURPLUS_BALANCE, CUSTOMER_REQUEST_PENDING_PAYOFF, GRANTOR_REQUEST_PENDING_PAYOFF, DECEASED, RISK_REVIEW, FRAUD, CUSTOMER_REQUEST, RISK, HARDSHIP/EXEMPTIONS, or SETTLEMENT. Default value is empty.

          • Denotes whether an account has active SCRA benefits

        • The product associated with the account.

          • product_id string Required

            The Canopy-generated ID for the product.

            • product_name string Required

              Name of Product, i.e. Express Card.

            • 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 string | null Required

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

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

            • late_fee_impl_cents integer Required

              The fee charged for late payments on the account.

              Default value is 0.

            • Default late fee described by the account's product. This value will be overridden by 'late_fee_impl_cents` for determining fee amounts

            • The fee charged for payment reversals on the account.

              Default value is 0.

            • Default payment reversal fee described by the account's product. This value will be overridden by payment_reversal_fee_impl_cents for determining fee amounts.

            • 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) | null

              If applicable, the account's loan repayment date.

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

            • promo_purchase_window_exclusive_end string(date-time) | null

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

            • promo_inclusive_start string(date-time) | null

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

            • promo_exclusive_end string(date-time) | null

              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.

            • Default interest rate described by the account's product (i.e. 6.2%). This value will be overridden by promo_impl_interest_rate_percent for determining interest rate.

            • 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 promotional length described by the account's product. This will be overridden by promo_len for determining length of the promotional period.

            • post_promo_inclusive_start string(date-time) | null

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

            • post_promo_exclusive_end string(date-time) | null

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

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

              Default value is 0.

            • Default interest rate described by the account's product (i.e. 6.2%). This value will be overridden by post_promo_impl_interest_rate_percent for determining interest rate for the account.

              Default value is 0.

            • If applicable, post-promotional amortization length in cycles.

              Default value is 0.

            • Default post promotional amortization length in cycles described by this account's product. This value will be overridden by post_promo_len to determine the post promotional length for this account.

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

          Not more than 1000 elements.

          • key string

            key: i.e. Name of the External Party

          • value string

            value: i.e. External Account ID

          • statement_min_pay_cents integer Required

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

            Default value is 0.

          • Real time total amount due including payments made since the start of 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.

          • Total fees due for the billing cycle accounting for payments since the billing cycle start.

            Default value is 0.

          • Portion of the real-time minimum payment that comes from current cycle balances.

          • Portion of the real-time minimum payment that comes from unpaid balances.

            Default value is 0.

          • ach object

            ACH processing configuration.

            • payment_processor_name string Required

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

              Values are NONE, REPAY, DWOLLA, MODERN_TREASURY, or CANOPY_NACHA. Default value is NONE.

            • repay_config object | null
              • ach_token string | null

                The tokenized ACH details.

              • last_four string | null

                The last four digits of the account number

            • dwolla_config object | null
              • ach_token string | null

                The tokenized ACH details.

              • last_four string | null

                The last four digits of the account number

              • ach_token string | null

                The tokenized ACH details.

              • last_four string | null

                The last four digits of the account number

            • canopy_nacha_config object | null

              Canopy will create a NACHA file for each borrower ACH payment to be sent to your bank for ACH execution.

              • bank_routing_number string Required

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

              • bank_account_number string Required

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

              • The type of bank account being used by the borrower.

                Values are CHECKING, SAVINGS, or GL.

          • Debit processing configuration.

          • Credit processing configuration.

            • payment_processor_name string Required

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

              Values are NONE or CHECKOUT. Default value is NONE.

            • checkout_config object | null
              • A Checkout.com payment source id or customer id.

              • The tokenized card number.

              • last_four string | null

                The last 4 digits of the card number.

              • expires_on string | null

                Expiration time for the card token.

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

            Default value is false.

          • 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, or NONE. Default value is NONE.

          • The payout_entity_id for this payout entity (typically a lender).

          • Provide a disbursement breakdown if draw downs from a borrower are meant to be distributed across multiple payout entities (lenders, merchants). Borrower payout breakdown. These numbers must add up to 100%. Borrower payout breakdowns will get reflected in daily reconciliation reports.

            • principal array[object]
              • The payout_entity_id for this payout entity.

              • The percentage of borrower payouts towards principal to be allocated to this payout entity. Sum of splits for a borrower must = 100%.

            • principal array[object] Required
              • payout_entity_id string Required

                The payout_entity_id of the payout_entity.

              • split_percent number Required

                The percentage of borrower payouts/disbursements to be allocated to this associated entity. Sum of splits for a borrower must = 100%. No decimals allowed.

            • interest array[object] Required
              • payout_entity_id string Required

                The payout_entity_id of the payout_entity.

              • split_percent number Required

                The percentage of borrower payouts/disbursements to be allocated to this associated entity. Sum of splits for a borrower must = 100%. No decimals allowed.

            • fee array[object] Required
              • payout_entity_id string Required

                The payout_entity_id of the payout_entity.

              • split_percent number Required

                The percentage of borrower payouts/disbursements to be allocated to this associated entity. Sum of splits for a borrower must = 100%. No decimals allowed.

          • lithic object
            • account_token string(uuid)

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

          • 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

        • summary object
          • The total balance (in cents) associated with the account. This balance is comprised of the sum of the following six balance items.

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

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

          • The interval at which interest accrues on the account. Ex: '1 day', '1 week', '2 weeks', '1 month' .Defaults to the product interest_accrual_interval if not specified

          • 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 fees 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 integer Required

            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)

        • associated_entities object | null

          (to be depricated) -- use payout_entities instead to provide more granular detail.

        • Plaid configurations.

            • valid_config boolean Required

              Indicates whether Canopy has a valid Plaid access token.

            • valid_config boolean Required

              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.

            Default value is false.

        • payout_entities array[object] | null

          An array of payout entities who have been assigned to the account

          Not more than 1000 elements.

          • payout_entity_id string Required

            The ID to be associated with the payout entity for future requests. If not provided on payout entity creation, Canopy will generate this field.

          • Type of associated entity

            Values are merchant, lender, sponsor, organization, or clearing.

          • Entity's name.

          • external_fields array[object]

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

            Not more than 1000 elements.

            • key string

              key: i.e. Name of the External Party

            • value string

              value: i.e. External Account ID

          • A Canopy-generated ID for the parent of this associated entity to establish a parent-child relationship.

          • Account number of the bank account for payment distributions.

          • Routing number of the bank account for payment distributions.

          • The type of bank account being stored for the payout entity.

            Values are CHECKING, SAVINGS, or GL.

        • cards array[object] | null

          Card data. Field names match the ones in Lithic's card schema

          • spend_limit integer | null

            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 string(uuid)

              Unique external identifier for the card

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

            • Last four digits of the card

            • type string

              The type of card being returned

              Values are UNLOCKED, MERCHANT_LOCKED, or SINGLE_USE.

            • state string

              The current state of the card

              Values are OPEN, PAUSED, or CLOSED.

            • memo string

              Friendly name to identify the card

    • paging object

      Pagination Information.

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

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

  • Unexpected Error.

GET /customers/accounts
curl \
 -X GET https://sandbox-api.canopyservicing.com/customers/accounts \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "results": [
    {
      "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",
      "name_prefix": "Dr.",
      "name_first": "Miriam",
      "name_middle": "Louise",
      "name_last": "Trevino",
      "name_suffix": "Jr",
      "passport": {
        "number": "string",
        "country": "JP"
      },
      "customer_id": "31mNprzLd2bKl6koVna68ARM",
      "customer_type": "person",
      "verification_status": "verified",
      "title": "CFO",
      "phone_number": "+14105556789",
      "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-888888",
        "business_type": "llc",
        "business_classification_id": "794D9D5E-B547-4B3B-8289-76484C1AFC5F",
        "website": "https://example.com",
        "controller": {
          "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",
          "name_prefix": "Dr.",
          "name_first": "Miriam",
          "name_middle": "Louise",
          "name_last": "Trevino",
          "name_suffix": "Jr",
          "passport": {
            "number": "string",
            "country": "JP"
          },
          "title": "CFO",
          "phone_number": "+14105556789",
          "ssn": "888888888"
        }
      },
      "customer_account_role": "PRIMARY",
      "customer_account_external_id": "4465220133024156",
      "account": {
        "account_id": "31mNprzLd2bKl6koVna68ARM",
        "created_at": "2017-06-20T09:12:14+00:00",
        "effective_at": "2018-03-20T09:12:28+00:00",
        "account_overview": {
          "account_status": "SUSPENDED",
          "account_status_subtype": "BANKRUPTCY",
          "is_active_scra": "false"
        },
        "account_product": {
          "product_id": "prod_4p1sc",
          "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,
            "default_product_late_fee_cents": 2900,
            "payment_reversal_fee_impl_cents": 2900,
            "default_product_payment_reversal_fee_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,
            "default_product_promo_interest_rate": 6.2,
            "promo_len": 6,
            "default_product_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,
            "default_product_post_promo_interest_rate": 6.2,
            "post_promo_len": 48,
            "default_product_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_cents": 160000,
          "min_pay_due_at": "2019-10-18T23:04:48.321+00:00"
        },
        "additional_min_pay_details": {
          "min_pay_fees_cents": 20000,
          "current_min_pay_cents": 400000,
          "unpaid_min_pay_cents": 400000
        },
        "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,
          "statement_payments_cents": 20000,
          "previous_statement_min_pay_cents": 400000,
          "statement_current_min_pay_cents": 400000,
          "statement_unpaid_min_pay_cents": 400000
        },
        "payment_processor_config": {
          "ach": {
            "payment_processor_name": "REPAY",
            "repay_config": {
              "ach_token": "string",
              "last_four": "string"
            },
            "dwolla_config": {
              "ach_token": "string",
              "last_four": "string"
            },
            "modern_treasury_config": {
              "ach_token": "string",
              "last_four": "string"
            },
            "canopy_nacha_config": {
              "bank_routing_number": "999999992",
              "bank_account_number": "987654321",
              "bank_account_type": "CHECKING"
            }
          },
          "debit_card": {
            "payment_processor_name": "REPAY",
            "repay_config": {
              "card_token": "string",
              "last_four": "string"
            },
            "authorize_net_config": {
              "customer_profile_id": "527262",
              "customer_payment_profile_ids": [
                "86"
              ]
            }
          },
          "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"
        },
        "disbursements_config": {
          "disbursement_source_payout_entity_id": 1009,
          "disbursement_split_percentages": {
            "principal": [
              {
                "payout_entity_id": 1009,
                "split_percent": 25
              }
            ]
          }
        },
        "payouts_config": {
          "payout_split_percentages": {
            "principal": [
              {
                "payout_entity_id": 1009,
                "split_percent": 25
              }
            ],
            "interest": [
              {
                "payout_entity_id": 1009,
                "split_percent": 25
              }
            ],
            "fee": [
              {
                "payout_entity_id": 1009,
                "split_percent": 25
              }
            ]
          }
        },
        "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,
          "interest_accrual_interval": "1 day",
          "am_interest_balance_cents": 0,
          "deferred_interest_balance_cents": 40000,
          "am_deferred_interest_balance_cents": 0,
          "fees_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
        },
        "payout_entities": [
          {
            "payout_entity_id": "0x1234",
            "payout_entity_type": "lender",
            "payout_entity_name": "Wonka Industries",
            "external_fields": [
              {
                "key": "Umbrella Corporation",
                "value": "22445702-a389-431f-927d-07b8d0750787"
              }
            ],
            "parent_payout_entity_id": "31mNprzLd2bKl6koVna68ARM",
            "bank_account_number": "1001001234",
            "bank_routing_number": "012345678",
            "bank_account_type": "CHECKING"
          }
        ],
        "cards": [
          {
            "spend_limit": 8000000,
            "lithic": {
              "token": "adccd28d-532e-480b-a063-a46a77a15570",
              "card_program_token": "a5e38341-cc95-4a9b-a21c-751aeca67e9c",
              "last_four": "0339",
              "type": "UNLOCKED",
              "state": "OPEN",
              "memo": "Conference Event Card"
            }
          }
        ]
      }
    }
  ],
  "paging": {
    "starting_after": "31mNprzLd2bKl6koVna68ARM",
    "ending_before": "31mNprzLd2bKl6koVna68ARM",
    "has_more": false
  }
}

Create a new customer

POST /customers

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 Required

Create a new customer

  • address_line_one string Required

    Address line one.

  • Address line two.

  • address_city string Required

    Address city.

  • address_state string Required

    Address state.

  • address_zip string Required

    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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

  • Prefix to the customer's name.

  • Customer's first name.

  • Customer's middle name.

  • Customer's last name.

  • Suffix to the customer's name.

  • passport object
    • number string Required

      Number on the passport

    • country string Required

      ISO 3166-1 Two letter code for the issuing country

  • The ID associated to be with the customer for future requests. If not provided on customer creation, Canopy will generate this field.

    Format should match the following pattern: ^(?!can_).*$.

  • The customer can be either a person or a business. This is used to explicitly set that and adjust behavior such as validation.

    Values are person or business.

  • The verification status of this customer. The default is 'unverified'. Depending on the system's configuration verification with third parties will happen and the status will be updated based on the result.

    Values are unverified, verified, retry, or document.

  • title string

    Title of the customer if a person OR title of the admin if a business

  • phone_number string Required

    Customer's phone number in E.164 format.

  • ssn string

    Social security number of the customer.

  • Any country-specific unique identifier for the customer.

  • email string(email) Required

    The Customer's email address.

  • date_of_birth string(date) Required

    Customer's date of birth in ISO 8601 format.

    • doing_business_as string Required

      The DBA name of the Business.

    • business_ein string Required

      EIN of the business, expected format in NN-NNNNNNN.

    • Type of business is used in determining the appropriate validation.

      Values are sole_proprietorship, llc, unincorporated_association, trust, corporation, corporation_public, non_profile, or partnership.

    • UUID that references the business classification. This will eventually be supported by a reference api, however, for now refer to dwolla's specific UUID.

    • website string

      URL for the buesiness's website. This should be publicly resolvable

    • controller object | null

      Passport information. required if country is not US

      • address_line_one string Required

        Address line one.

      • Address line two.

      • address_city string Required

        Address city.

      • address_state string Required

        Address state.

      • address_zip string Required

        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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

      • Prefix to the customer's name.

      • Customer's first name.

      • Customer's middle name.

      • Customer's last name.

      • Suffix to the customer's name.

      • passport object
        • number string Required

          Number on the passport

        • country string Required

          ISO 3166-1 Two letter code for the issuing country

      • title string

        Title of the customer if a person OR title of the admin if a business

      • Customer's phone number in E.164 format.

      • ssn string

        Social security number of the customer.

  • assign_to_accounts array[object] | null

    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.

    Not more than 100 elements.

    • account_id string Required

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

    • customer_account_role string Required

      The role of the customer for the account.

      Values are PRIMARY or SECONDARY. 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.

Responses

  • 200 object | null

    New Customer Created

    • address_line_one string Required

      Address line one.

    • Address line two.

    • address_city string Required

      Address city.

    • address_state string Required

      Address state.

    • address_zip string Required

      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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

    • Prefix to the customer's name.

    • Customer's first name.

    • Customer's middle name.

    • Customer's last name.

    • Suffix to the customer's name.

    • passport object
      • number string Required

        Number on the passport

      • country string Required

        ISO 3166-1 Two letter code for the issuing country

    • customer_id string Required

      A Canopy-generated ID for the customer.

    • The customer can be either a person or a business. This is used to explicitly set that and adjust behavior such as validation.

      Values are person or business.

    • The verification status of this customer. The default is 'unverified'. Depending on the system's configuration verification with third parties will happen and the status will be updated based on the result.

      Values are unverified, verified, retry, or document.

    • title string

      Title of the customer if a person OR title of the admin if a business

    • Customer's phone number in E.164 format

    • 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 DBA name of the Business

      • EIN of the business, expected format in NN-NNNNNNN.

      • Type of business is used in determining the appropriate validation.

        Values are sole_proprietorship, llc, unincorporated_association, trust, corporation, corporation_public, non_profile, or partnership.

      • UUID that references the business classification. This will eventually be supported by a reference api, however, for now refer to dwolla's specific UUID.

      • website string

        URL for the buesiness's website. This should be publicly resolvable

      • controller object | null

        Passport information. required if country is not US

        • address_line_one string Required

          Address line one.

        • Address line two.

        • address_city string Required

          Address city.

        • address_state string Required

          Address state.

        • address_zip string Required

          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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

        • Prefix to the customer's name.

        • Customer's first name.

        • Customer's middle name.

        • Customer's last name.

        • Suffix to the customer's name.

        • passport object
          • number string Required

            Number on the passport

          • country string Required

            ISO 3166-1 Two letter code for the issuing country

        • title string

          Title of the customer if a person OR title of the admin if a business

        • Customer's phone number in E.164 format.

        • ssn string

          Social security number of the customer.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 422

    Invalid input

  • 429

    Too many requests.

  • Unexpected Error.

POST /customers
curl \
 -X POST https://sandbox-api.canopyservicing.com/customers \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"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","name_prefix":"Dr.","name_first":"Miriam","name_middle":"Louise","name_last":"Trevino","name_suffix":"Jr","passport":{"number":"string","country":"JP"},"customer_id":"0x1234","customer_type":"person","verification_status":"verified","title":"CFO","phone_number":"+14105556789","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-888888","business_type":"llc","business_classification_id":"794D9D5E-B547-4B3B-8289-76484C1AFC5F","website":"https://example.com","controller":{"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","name_prefix":"Dr.","name_first":"Miriam","name_middle":"Louise","name_last":"Trevino","name_suffix":"Jr","passport":{"number":"string","country":"JP"},"title":"CFO","phone_number":"+14105556789","ssn":"888888888"}},"assign_to_accounts":[{"account_id":"31mNprzLd2bKl6koVna68ARM","customer_account_role":"PRIMARY","customer_account_external_id":"4465220133024156"}]}'
Request example
{
  "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",
  "name_prefix": "Dr.",
  "name_first": "Miriam",
  "name_middle": "Louise",
  "name_last": "Trevino",
  "name_suffix": "Jr",
  "passport": {
    "number": "string",
    "country": "JP"
  },
  "customer_id": "0x1234",
  "customer_type": "person",
  "verification_status": "verified",
  "title": "CFO",
  "phone_number": "+14105556789",
  "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-888888",
    "business_type": "llc",
    "business_classification_id": "794D9D5E-B547-4B3B-8289-76484C1AFC5F",
    "website": "https://example.com",
    "controller": {
      "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",
      "name_prefix": "Dr.",
      "name_first": "Miriam",
      "name_middle": "Louise",
      "name_last": "Trevino",
      "name_suffix": "Jr",
      "passport": {
        "number": "string",
        "country": "JP"
      },
      "title": "CFO",
      "phone_number": "+14105556789",
      "ssn": "888888888"
    }
  },
  "assign_to_accounts": [
    {
      "account_id": "31mNprzLd2bKl6koVna68ARM",
      "customer_account_role": "PRIMARY",
      "customer_account_external_id": "4465220133024156"
    }
  ]
}
Response example (200)
{
  "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",
  "name_prefix": "Dr.",
  "name_first": "Miriam",
  "name_middle": "Louise",
  "name_last": "Trevino",
  "name_suffix": "Jr",
  "passport": {
    "number": "string",
    "country": "JP"
  },
  "customer_id": "31mNprzLd2bKl6koVna68ARM",
  "customer_type": "person",
  "verification_status": "verified",
  "title": "CFO",
  "phone_number": "+14105556789",
  "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-888888",
    "business_type": "llc",
    "business_classification_id": "794D9D5E-B547-4B3B-8289-76484C1AFC5F",
    "website": "https://example.com",
    "controller": {
      "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",
      "name_prefix": "Dr.",
      "name_first": "Miriam",
      "name_middle": "Louise",
      "name_last": "Trevino",
      "name_suffix": "Jr",
      "passport": {
        "number": "string",
        "country": "JP"
      },
      "title": "CFO",
      "phone_number": "+14105556789",
      "ssn": "888888888"
    }
  }
}

Update a specific customer's information

PUT /customers/{customer_id}

Path parameters

Body

Update an existing customer

  • address_line_one string Required

    Address line one.

  • Address line two.

  • address_city string Required

    Address city.

  • address_state string Required

    Address state.

  • address_zip string Required

    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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

  • Prefix to the customer's name.

  • Customer's first name.

  • Customer's middle name.

  • Customer's last name.

  • Suffix to the customer's name.

  • The customer can be either a person or a business. This is used to explicitly set that and adjust behavior such as validation.

    Values are person or business.

  • The verification status of this customer. The default is 'unverified'. Depending on the system's configuration verification with third parties will happen and the status will be updated based on the result.

    Values are unverified, verified, retry, or document.

  • Customer's phone number in E.164 format.

  • ssn string

    Social security number of the customer.

  • title string

    Title of the customer if a person OR title of the admin if a business

  • Any country-specific unique identifier for the customer.

  • email string(email)

    The Customer's email address.

  • date_of_birth string(date)

    Customer's date of birth in ISO 8601 format.

    • doing_business_as string Required

      The DBA name of the Business.

    • business_ein string Required

      EIN of the business, expected format in NN-NNNNNNN.

    • Type of business is used in determining the appropriate validation.

      Values are sole_proprietorship, llc, unincorporated_association, trust, corporation, corporation_public, non_profile, or partnership.

    • UUID that references the business classification. This will eventually be supported by a reference api, however, for now refer to dwolla's specific UUID.

    • website string

      URL for the buesiness's website. This should be publicly resolvable

    • controller object | null

      Passport information. required if country is not US

      • address_line_one string Required

        Address line one.

      • Address line two.

      • address_city string Required

        Address city.

      • address_state string Required

        Address state.

      • address_zip string Required

        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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

      • Prefix to the customer's name.

      • Customer's first name.

      • Customer's middle name.

      • Customer's last name.

      • Suffix to the customer's name.

      • passport object
        • number string Required

          Number on the passport

        • country string Required

          ISO 3166-1 Two letter code for the issuing country

      • title string

        Title of the customer if a person OR title of the admin if a business

      • Customer's phone number in E.164 format.

      • ssn string

        Social security number of the customer.

Responses

  • 200 object | null

    Successful query of information for a specific customer

    • address_line_one string Required

      Address line one.

    • Address line two.

    • address_city string Required

      Address city.

    • address_state string Required

      Address state.

    • address_zip string Required

      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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

    • Prefix to the customer's name.

    • Customer's first name.

    • Customer's middle name.

    • Customer's last name.

    • Suffix to the customer's name.

    • passport object
      • number string Required

        Number on the passport

      • country string Required

        ISO 3166-1 Two letter code for the issuing country

    • customer_id string Required

      A Canopy-generated ID for the customer.

    • The customer can be either a person or a business. This is used to explicitly set that and adjust behavior such as validation.

      Values are person or business.

    • The verification status of this customer. The default is 'unverified'. Depending on the system's configuration verification with third parties will happen and the status will be updated based on the result.

      Values are unverified, verified, retry, or document.

    • title string

      Title of the customer if a person OR title of the admin if a business

    • Customer's phone number in E.164 format

    • 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 DBA name of the Business

      • EIN of the business, expected format in NN-NNNNNNN.

      • Type of business is used in determining the appropriate validation.

        Values are sole_proprietorship, llc, unincorporated_association, trust, corporation, corporation_public, non_profile, or partnership.

      • UUID that references the business classification. This will eventually be supported by a reference api, however, for now refer to dwolla's specific UUID.

      • website string

        URL for the buesiness's website. This should be publicly resolvable

      • controller object | null

        Passport information. required if country is not US

        • address_line_one string Required

          Address line one.

        • Address line two.

        • address_city string Required

          Address city.

        • address_state string Required

          Address state.

        • address_zip string Required

          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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

        • Prefix to the customer's name.

        • Customer's first name.

        • Customer's middle name.

        • Customer's last name.

        • Suffix to the customer's name.

        • passport object
          • number string Required

            Number on the passport

          • country string Required

            ISO 3166-1 Two letter code for the issuing country

        • title string

          Title of the customer if a person OR title of the admin if a business

        • Customer's phone number in E.164 format.

        • ssn string

          Social security number of the customer.

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Customer not found

  • 422

    Invalid input

  • 429

    Too many requests.

  • Unexpected Error.

PUT /customers/{customer_id}
curl \
 -X PUT https://sandbox-api.canopyservicing.com/customers/1001 \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"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","name_prefix":"Dr.","name_first":"Miriam","name_middle":"Louise","name_last":"Trevino","name_suffix":"Jr","customer_type":"person","verification_status":"verified","phone_number":"+14105556789","ssn":"888888888","title":"CFO","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-888888","business_type":"llc","business_classification_id":"794D9D5E-B547-4B3B-8289-76484C1AFC5F","website":"https://example.com","controller":{"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","name_prefix":"Dr.","name_first":"Miriam","name_middle":"Louise","name_last":"Trevino","name_suffix":"Jr","passport":{"number":"string","country":"JP"},"title":"CFO","phone_number":"+14105556789","ssn":"888888888"}}}'
Request example
{
  "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",
  "name_prefix": "Dr.",
  "name_first": "Miriam",
  "name_middle": "Louise",
  "name_last": "Trevino",
  "name_suffix": "Jr",
  "customer_type": "person",
  "verification_status": "verified",
  "phone_number": "+14105556789",
  "ssn": "888888888",
  "title": "CFO",
  "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-888888",
    "business_type": "llc",
    "business_classification_id": "794D9D5E-B547-4B3B-8289-76484C1AFC5F",
    "website": "https://example.com",
    "controller": {
      "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",
      "name_prefix": "Dr.",
      "name_first": "Miriam",
      "name_middle": "Louise",
      "name_last": "Trevino",
      "name_suffix": "Jr",
      "passport": {
        "number": "string",
        "country": "JP"
      },
      "title": "CFO",
      "phone_number": "+14105556789",
      "ssn": "888888888"
    }
  }
}
Response example (200)
{
  "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",
  "name_prefix": "Dr.",
  "name_first": "Miriam",
  "name_middle": "Louise",
  "name_last": "Trevino",
  "name_suffix": "Jr",
  "passport": {
    "number": "string",
    "country": "JP"
  },
  "customer_id": "31mNprzLd2bKl6koVna68ARM",
  "customer_type": "person",
  "verification_status": "verified",
  "title": "CFO",
  "phone_number": "+14105556789",
  "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-888888",
    "business_type": "llc",
    "business_classification_id": "794D9D5E-B547-4B3B-8289-76484C1AFC5F",
    "website": "https://example.com",
    "controller": {
      "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",
      "name_prefix": "Dr.",
      "name_first": "Miriam",
      "name_middle": "Louise",
      "name_last": "Trevino",
      "name_suffix": "Jr",
      "passport": {
        "number": "string",
        "country": "JP"
      },
      "title": "CFO",
      "phone_number": "+14105556789",
      "ssn": "888888888"
    }
  }
}

List beneficial owners of a business

GET /customers/{customer_id}/beneficial_owners

The list of people who are registered as a benificial own for the business.

Path parameters

Responses

  • 200 array[object | null] | null

    List of Beneficial Owners

    • address_line_one string Required

      Address line one.

    • Address line two.

    • address_city string Required

      Address city.

    • address_state string Required

      Address state.

    • address_zip string Required

      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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

    • Prefix to the customer's name.

    • Customer's first name.

    • Customer's middle name.

    • Customer's last name.

    • Suffix to the customer's name.

    • passport object
      • number string Required

        Number on the passport

      • country string Required

        ISO 3166-1 Two letter code for the issuing country

    • The ID associated to be with the beneficial owner for future requests. If not provided on creation, Canopy will generate this field.

      Format should match the following pattern: ^(?!can_).*$.

    • verification_status string | null

      Status of the verification process

      Values are uncertified or certified.

    • Customer's phone number in E.164 format.

    • email string(email)

      The Customer's email address.

    • ssn string | null

      Full nine digits of their social security number.

    • Date of Birth in YYYY-MM-DD format

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Payment Processor not found

  • 429

    Too many requests.

  • Unexpected Error.

GET /customers/{customer_id}/beneficial_owners
curl \
 -X GET https://sandbox-api.canopyservicing.com/customers/31mNprzLd2bKl6koVna68ARM/beneficial_owners \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
[
  {
    "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",
    "name_prefix": "Dr.",
    "name_first": "Miriam",
    "name_middle": "Louise",
    "name_last": "Trevino",
    "name_suffix": "Jr",
    "passport": {
      "number": "string",
      "country": "JP"
    },
    "beneficial_owner_id": "0x1234",
    "verification_status": "uncertified",
    "phone_number": "+14105556789",
    "email": "marissa@protonmail.com",
    "ssn": "000-00-0000",
    "date_of_birth": "2004-01-30"
  }
]

Create a new beneficial owner for the business

POST /customers/{customer_id}/beneficial_owners

This will create a new beneficial owner in an unverified state.

Path parameters

Body Required

Create a new beneficial owner

  • address_line_one string Required

    Address line one.

  • Address line two.

  • address_city string Required

    Address city.

  • address_state string Required

    Address state.

  • address_zip string Required

    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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

  • Prefix to the customer's name.

  • Customer's first name.

  • Customer's middle name.

  • Customer's last name.

  • Suffix to the customer's name.

  • passport object
    • number string Required

      Number on the passport

    • country string Required

      ISO 3166-1 Two letter code for the issuing country

  • The ID associated to be with the beneficial owner for future requests. If not provided on creation, Canopy will generate this field.

    Format should match the following pattern: ^(?!can_).*$.

  • verification_status string | null

    Status of the verification process

    Values are uncertified or certified.

  • Customer's phone number in E.164 format.

  • email string(email)

    The Customer's email address.

  • ssn string | null

    Full nine digits of their social security number.

  • Date of Birth in YYYY-MM-DD format

Responses

  • 200 object | null

    Successful query of information for a specific beneficial owner

    • address_line_one string Required

      Address line one.

    • Address line two.

    • address_city string Required

      Address city.

    • address_state string Required

      Address state.

    • address_zip string Required

      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, 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, 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, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, or ZW.

    • Prefix to the customer's name.

    • Customer's first name.

    • Customer's middle name.

    • Customer's last name.

    • Suffix to the customer's name.

    • passport object
      • number string Required

        Number on the passport

      • country string Required

        ISO 3166-1 Two letter code for the issuing country

    • The ID associated to be with the beneficial owner for future requests. If not provided on creation, Canopy will generate this field.

      Format should match the following pattern: ^(?!can_).*$.

    • verification_status string | null

      Status of the verification process

      Values are uncertified or certified.

    • Customer's phone number in E.164 format.

    • email string(email)

      The Customer's email address.

    • ssn string | null

      Full nine digits of their social security number.

    • Date of Birth in YYYY-MM-DD format

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 404

    Payment Processor not found

  • 429

    Too many requests.

  • Unexpected Error.

POST /customers/{customer_id}/beneficial_owners
curl \
 -X POST https://sandbox-api.canopyservicing.com/customers/31mNprzLd2bKl6koVna68ARM/beneficial_owners \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"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","name_prefix":"Dr.","name_first":"Miriam","name_middle":"Louise","name_last":"Trevino","name_suffix":"Jr","passport":{"number":"string","country":"JP"},"beneficial_owner_id":"0x1234","verification_status":"uncertified","phone_number":"+14105556789","email":"marissa@protonmail.com","ssn":"000-00-0000","date_of_birth":"2004-01-30"}'
Request example
{
  "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",
  "name_prefix": "Dr.",
  "name_first": "Miriam",
  "name_middle": "Louise",
  "name_last": "Trevino",
  "name_suffix": "Jr",
  "passport": {
    "number": "string",
    "country": "JP"
  },
  "beneficial_owner_id": "0x1234",
  "verification_status": "uncertified",
  "phone_number": "+14105556789",
  "email": "marissa@protonmail.com",
  "ssn": "000-00-0000",
  "date_of_birth": "2004-01-30"
}
Response example (200)
{
  "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",
  "name_prefix": "Dr.",
  "name_first": "Miriam",
  "name_middle": "Louise",
  "name_last": "Trevino",
  "name_suffix": "Jr",
  "passport": {
    "number": "string",
    "country": "JP"
  },
  "beneficial_owner_id": "0x1234",
  "verification_status": "uncertified",
  "phone_number": "+14105556789",
  "email": "marissa@protonmail.com",
  "ssn": "000-00-0000",
  "date_of_birth": "2004-01-30"
}

Accounts

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

Create a new account

POST /accounts

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

Create a new account

  • effective_at string(date-time)

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

  • account_id string Required

    This is the ID used to identify the account in your system. For most use-cases, we strongly recommend using the ID from the system the account was originally created in -- for most use-cases, this is created as part of the origination system that approves a borrower. This will be the account that is used to refer to the borrower for all subsequent requests. Note: both strings and integers are accepted.

    Format should match the following pattern: ^(?!can_).*$.

  • product_id string Required

    The product ID that ties to the product onto which this account is being onboarded.

  • external_fields array[object] | null

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

    Not more than 100 elements.

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

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

        Values are NONE, REPAY, DWOLLA, MODERN_TREASURY, or CANOPY_NACHA. Default value is NONE.

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

        • repay_check_type string Required

          Type of checking account: Personal or Business.

          Values are PERSONAL or BUSINESS.

        • repay_account_type string Required

          Type of account: Savings or Checking.

          Values are SAVINGS or CHECKING.

        • repay_transit_number string Required

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

        • repay_account_number string Required

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

        • repay_name_on_check string Required

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

      • Dwolla account verified and tokenized using Plaid.

      • Store bank details or a secured token for payments.

        • name string Required

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

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

        • Type of account: Savings or Checking.

          Values are SAVINGS or 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.

      • Canopy will create a NACHA file for each borrower ACH payment to be sent to your bank for ACH execution.

        • bank_routing_number string Required

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

        • bank_account_number string Required

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

        • The type of bank account being used by the borrower.

          Values are CHECKING, SAVINGS, or GL.

    • Debit processing configuration.

      • payment_processor_name string Required

        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, REPAY, or AUTHORIZE_NET. Default value is NONE.

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

        • repay_card_number string Required

          16 digit debit card number.

          Minimum length is 16, maximum length is 16. Format should match the following pattern: ^[0-9]{16}$.

        • repay_exp_date string Required

          The card expiration date in the format MMYY.

          Minimum length is 4, maximum length is 4. Format should match the following pattern: ^[0-9]{4}$.

        • repay_name_on_card string Required

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

        • repay_street string Required

          The card holder's billing street address.

        • repay_zip string Required

          The card holder's billing zip code.

      • Sensitive credit or debit card information will be stored as a secured token for payments in place of the raw account details. Note: This leverages credit card payment gateways, and Canopy cannot differentiate between credit or debit cards used in this payment integration. See authorize.net payment profiles for further details.

        • card_number string Required

          16 digit debit card number.

          Minimum length is 16, maximum length is 16. Format should match the following pattern: ^[0-9]{16}$.

        • The card expiration month.

          Minimum length is 2, maximum length is 2. Format should match the following pattern: ^[0-9]{2}$.

        • The card expiration year.

          Minimum length is 4, maximum length is 4. Format should match the following pattern: ^[0-9]{4}$.

        • cvv string

          The card cvv, i.e. security code.

          Minimum length is 3, maximum length is 4.

    • Credit processing configuration.

      • payment_processor_name string Required

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

        Values are NONE or CHECKOUT. Default value is NONE.

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

      Default value is false.

    • 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, or NONE. Default value is NONE.

    • The payout_entity_id for this payout entity (typically a lender). The ID provided must also be linked to the account.

    • Provide a disbursement breakdown if draw downs from a borrower are meant to be distributed across multiple payout entities (lenders, merchants). Borrower payout breakdown. These numbers must add up to 100%. Borrower payout breakdowns will get reflected in daily reconciliation reports.

      • principal array[object]
        • payout_entity_id string Required

          The payout_entity_id of the payout_entity.

        • split_percent number Required

          The percentage of borrower payouts/disbursements to be allocated to this associated entity. Sum of splits for a borrower must = 100%. No decimals allowed.

      • principal array[object] Required
        • payout_entity_id string Required

          The payout_entity_id of the payout_entity.

        • split_percent number Required

          The percentage of borrower payouts/disbursements to be allocated to this associated entity. Sum of splits for a borrower must = 100%. No decimals allowed.

      • interest array[object] Required
        • payout_entity_id string Required

          The payout_entity_id of the payout_entity.

        • split_percent number Required

          The percentage of borrower payouts/disbursements to be allocated to this associated entity. Sum of splits for a borrower must = 100%. No decimals allowed.

      • fee array[object] Required
        • payout_entity_id string Required

          The payout_entity_id of the payout_entity.

        • split_percent number Required

          The percentage of borrower payouts/disbursements to be allocated to this associated entity. Sum of splits for a borrower must = 100%. No decimals allowed.

    • 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

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

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

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

    • The interval at which interest accrues on the account. Ex: '1 day', '1 week', '2 weeks', '1 month' .Defaults to the product interest_accrual_interval if not specified

    • promo_len integer

      If applicable, promo length in cycles. If not provided, the product promo_len will be used.

    • Current due calculation method for the promotional period. If not provided, product's promo_min_pay_type will be used

      Values are AM, PERCENT_INTEREST, PERCENT_PRINCIPAL, PERCENT_PRINCIPAL_INTEREST, or NONE. Default value is NONE.

    • Only for multi-advance installment loans with a purchase window. If applicable, promo length in cycles. If not provided, the product promo_len will be used.

    • Defaults to product promo_min_pay_percent. The percent of the interest calculation type used. For example, if PERCENT_INTEREST is the interest calculation type, and this value is 50, 50% of interest accrued during the cycle will be reflected as the required minimum payment.

      Default value is 100.

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

    • The percentage interest applied to the account during the post-promotional period (e.g. 6.2). If not provide, will default to associated product's post_promo_default_interest_rate_percent value.

    • If applicable, post-promotional amortization length in cycles.

  • (to be depricated) -- use payout_entities instead to provide more granular detail.

  • Plaid configurations.

    • plaid_access_token string Required

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

    • plaid_account_id string Required

      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.

      Default value is false.

  • assign_customers array[object] | null

    Array of existing customer IDs to be added to the account. Canopy recommends assigning a customer to the account during account creation.

    Not more than 10 elements.