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

  • beneficial_owner_id string

    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.

  • phone_number string

    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 string

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

    • beneficial_owner_id string

      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.

    • phone_number string

      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 string

      Date of Birth in YYYY-MM-DD format

  • • 401

    Unauthorized.

  • • 403

    Forbidden.

  • • 404

    Payment Processor not found

  • • 429

    Too many requests.

  • • default

    Unexpected Error.

POST /customers/{customer_id}/beneficial_owners 
curl \
 -X POST https://<your_environment_name>-uat-api.canopyservicing.com/customers/cust_30189/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"
}