Canopy API - Latest

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 string

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'.
address_country_code string

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.
name_prefix string

Prefix to the customer's name.
name_first string

Customer's first name.
name_middle string

Customer's middle name.
name_last string

Customer's last name.
name_suffix string

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

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_).*$.
customer_type string

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.
customer_parent_id string

The customer can be a child customer to another parent customer. This is used most commonly to show a PERSON customer that is a child of a BUSINESS customer.
verification_status string

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.
international_customer_id string

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.
business_details object
- business_legal_name string Required
  
  The legal name of the Business.
- doing_business_as string Required
  
  The DBA name of the Business.
- business_ein string Required
  
  EIN of the business, expected format in NN-NNNNNNN.
- business_type string
  
  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.
- business_classification_id string
  
  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 string
  
  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'.
  
  address_country_code string
  
  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.
  
  name_prefix string
  
  Prefix to the customer's name.
  
  name_first string
  
  Customer's first name.
  
  name_middle string
  
  Customer's middle name.
  
  name_last string
  
  Customer's last name.
  
  name_suffix string
  
  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
  
  phone_number string
  
  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.
- customer_account_external_id string
  
  A unique number for the customer on the account. For instance, a credit card number. If none is provided, a Canopy-generated ID can be used.
- designation string
  
  The designation of the customer for the account.
  
  Values are INDIVIDUAL, JOINT_CONTRACTUAL_LIABILITY, AUTHORIZED_USER, COMAKER_OR_GUARANTOR, MAKER, BUSINESS_COMMERCIAL, or DECEASED.
metro2_config object

Metro2 credit reporting configs
- bloom_metadata object
  
  Bloom API fields for customers: https://docs.bloom.dev/docs/furnishment-api/b3A6MjA1NTM1MQ-create-consumer
  address_type string
  
  Status of the reported address.
  
  Values are CONFIRMED, KNOWN, NOT_CONFIRMED, MILITARY, SECONDARY, BUSINESS, UNDELIVERABLE, DEFAULT, or BILL_PAYER_SERVICE.
  
  residence_type string
  
  Optional, if not available or unknown, do not report.
  
  Values are OWNS or RENTS.
  
  account_designations array[object] | null
  
  A list of accounts associated with the customer.
  
  account_id string
  
  the ID of the account associated with the customer
  
  designation string
  
  The designation of the customer for the account.
  
  Values are INDIVIDUAL, JOINT_CONTRACTUAL_LIABILITY, AUTHORIZED_USER, COMAKER_OR_GUARANTOR, MAKER, BUSINESS_COMMERCIAL, or DECEASED.

Responses

• 200 object | null

New Customer Created
- address_line_one string Required
  
  Address line one.
- address_line_two string
  
  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'.
- address_country_code string
  
  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.
- name_prefix string
  
  Prefix to the customer's name.
- name_first string
  
  Customer's first name.
- name_middle string
  
  Customer's middle name.
- name_last string
  
  Customer's last name.
- name_suffix string
  
  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
  
  An ID for the customer.
- created_at string(date-time)
  
  The Date-Time which the customer was created in the API.
- updated_at string(date-time)
  
  The Date-Time which the customer was updated in the API.
- is_borrower_portal_user boolean
  
  Indicates whether the customer has a borrower portal login or not
- customer_type string
  
  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.
- is_active boolean
  
  Value manually maintained - defaults to true."False" generally indicates no additional credit should be granted to this customer
- verification_status string
  
  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
  
  Customer's phone number in E.164 format
- ssn string
  
  Social security number of the customer.
- international_customer_id string
  
  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
- customer_balances object
  num_active_accounts integer
  
  The number of active accounts for this customer.
  
  total_balance_cents integer
  
  The total outstanding balance (in cents) associated with all active accounts for this customer. This balance is comprised of the sum of the following six balance items.
  
  principal_cents integer
  
  The total principal balance (in cents) associated with all active accounts for this customer.
  
  interest_balance_cents integer
  
  The total interest balance (in cents) associated with all active accounts for this customer.
  
  am_interest_balance_cents integer
  
  The total AM interest balance (in cents) associated with all active accounts for this customer.
  
  Default value is 0.
  
  deferred_interest_balance_cents integer
  
  The total deferred interest balance (in cents) associated with all active accounts for this customer.
  
  Default value is 0.
  
  am_deferred_interest_balance_cents integer
  
  The total AM deferred interest balance (in cents) associated with all active accounts for this customer.
  
  Default value is 0.
  
  fees_balance_cents integer
  
  The total fees balance (in cents) associated with all active accounts for this customer.
  
  Default value is 0.
- business_details object
  business_legal_name string
  
  The legal name of the Business
  
  doing_business_as string
  
  The DBA name of the Business
  
  business_ein string
  
  EIN of the business, expected format in NN-NNNNNNN.
  
  business_type string
  
  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.
  
  business_classification_id string
  
  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 string
  
  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'.
  
  address_country_code string
  
  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.
  
  name_prefix string
  
  Prefix to the customer's name.
  
  name_first string
  
  Customer's first name.
  
  name_middle string
  
  Customer's middle name.
  
  name_last string
  
  Customer's last name.
  
  name_suffix string
  
  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
  
  phone_number string
  
  Customer's phone number in E.164 format.
  
  ssn string
  
  Social security number of the customer.
- metro2_config object
  
  Metro2 credit reporting configs
  bloom_metadata object
  
  Bloom API fields for customers: https://docs.bloom.dev/docs/furnishment-api/b3A6MjA1NTM1MQ-create-consumer
  
  address_type string
  
  Status of the reported address.
  
  Values are CONFIRMED, KNOWN, NOT_CONFIRMED, MILITARY, SECONDARY, BUSINESS, UNDELIVERABLE, DEFAULT, or BILL_PAYER_SERVICE.
  
  residence_type string
  
  Optional, if not available or unknown, do not report.
  
  Values are OWNS or RENTS.
  
  account_designations array[object] | null
  
  A list of accounts associated with the customer.
  
  account_id string
  
  the ID of the account associated with the customer
  
  designation string
  
  The designation of the customer for the account.
  
  Values are INDIVIDUAL, JOINT_CONTRACTUAL_LIABILITY, AUTHORIZED_USER, COMAKER_OR_GUARANTOR, MAKER, BUSINESS_COMMERCIAL, or DECEASED.
• 401

Unauthorized.
• 403

Forbidden.
• 422

Invalid input
• 429

Too many requests.
• default

Unexpected Error.

POST /customers

curl \
 -X POST https://<your_environment_name>-uat-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","customer_parent_id":"cust_583","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","designation":"INDIVIDUAL"}],"metro2_config":{"bloom_metadata":{"address_type":"CONFIRMED","residence_type":"OWNS","account_designations":[{"account_id":"string","designation":"INDIVIDUAL"}]}}}'

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",
  "customer_parent_id": "cust_583",
  "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",
      "designation": "INDIVIDUAL"
    }
  ],
  "metro2_config": {
    "bloom_metadata": {
      "address_type": "CONFIRMED",
      "residence_type": "OWNS",
      "account_designations": [
        {
          "account_id": "string",
          "designation": "INDIVIDUAL"
        }
      ]
    }
  }
}

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",
  "created_at": "2017-06-20T09:12:14+00:00",
  "updated_at": "2019-02-20T09:12:14+00:00",
  "is_borrower_portal_user": true,
  "customer_type": "person",
  "is_active": true,
  "verification_status": "verified",
  "title": "CFO",
  "phone_number": "+14105556789",
  "ssn": "888888888",
  "international_customer_id": "9999999999",
  "email": "marissa@protonmail.com",
  "date_of_birth": "1985-06-20",
  "customer_balances": {
    "num_active_accounts": 2,
    "total_balance_cents": 300000,
    "principal_cents": 200000,
    "interest_balance_cents": 60000,
    "am_interest_balance_cents": 0,
    "deferred_interest_balance_cents": 40000,
    "am_deferred_interest_balance_cents": 0,
    "fees_balance_cents": 0
  },
  "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"
    }
  },
  "metro2_config": {
    "bloom_metadata": {
      "address_type": "CONFIRMED",
      "residence_type": "OWNS",
      "account_designations": [
        {
          "account_id": "string",
          "designation": "INDIVIDUAL"
        }
      ]
    }
  }
}