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

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

  • name_prefix string

    Prefix to the customer's name.

  • name_first string Required

    Customer's first name.

  • name_middle string

    Customer's middle name.

  • name_last string Required

    Customer's last name.

  • name_suffix string

    Suffix to the customer's name.

  • phone_number string Required

    Customer's phone number in E.164 format.

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

  • 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
    Hide business_details attributes Show business_details attributes object
    • doing_business_as string Required

      The DBA name of the Business.

    • business_ein string Required

      EIN of the business.

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

    Hide assign_to_accounts attributes Show assign_to_accounts attributes array[object] | null
    • 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.

    • customer_account_issuer_processor_config object
      Hide customer_account_issuer_processor_config attributes Show customer_account_issuer_processor_config attributes object
      • 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
        Hide lithic attributes Show lithic attributes object
        • memo string

          Friendly name to identify the card.

        • type string

          The type of card created by Lithic.

          Values are SINGLE_USE, MERCHANT_LOCKED, or UNLOCKED.

        • state string

          The state of the new card.

          Values are OPEN or PAUSED.

        • card_program_token string(uuid)

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

Responses

  • 429

    Too many requests.

  • default

    Unexpected Error.

  • 200

    New Customer Created

    Hide response attributes Show response attributes object
    • customer_id string Required

      A Canopy-generated ID for the customer.

    • name_prefix string

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

    • name_first string

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

    • name_middle string

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

    • name_last string

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

    • name_suffix string

      Suffix to the customer's name

    • phone_number string

      Customer's phone number in E.164 format

    • address_line_one string

      Address line one.

    • address_line_two string

      Address line two.

    • address_city string

      Address city.

    • address_state string

      Address state.

    • address_zip string

      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.

    • 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

    • business_details object
      Hide business_details attributes Show business_details attributes object
      • doing_business_as string

        The DBA name of the Business

      • business_ein string

        EIN of the business

  • 401

    Unauthorized.

  • 403

    Forbidden.

  • 422

    Invalid input

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