Update Customer

PATCH
/api/v1/customer/{customerId}

Update customer key details and entitlements. A supplementary submission sent with entitlements follows the rules of PATCH /customers/{customerId}/entitlements/{entitlement}/requirements: a value for an item the answers do not ask for is refused with 400, and nothing sent for that submission is stored. A value that is not valid for its country, such as a financial_profile.tax_id_number, is refused with 400 and code INVALID_FIELDS; fields names each such field.

Authorization

headerX-Api-Key<token>

API key in format: sti_env_prefix_secret

Path Parameters

customerId*string

Customer UUID

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Request Body

application/json
  1. body
entitlements?array<>

Feature-based entitlements for the customer

email?string

Email address

Match^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
Formatemail
phone?string

Phone number

Match^\+[1-9]\d{6,14}$
Formate164
metadata?

Additional metadata

first_name?string

First name of the applicant

last_name?string

Last name of the applicant

middle_name?string

Middle name of the applicant

dob?string

Date of birth in YYYY-MM-DD format

Match^\d{4}-\d{2}-\d{2}$
nationality?string

Country code

tax_id_number?string

Tax Identification Number (TIN)

address?

Postal address

proof_of_address_documents?array<>

Proof of address documents (PDF, JPEG, PNG or HEIC, up to 5MB each). Held by Stables and reviewed by compliance; satisfies the proof_of_address capability once approved.

source_of_wealth_documents?array<>

Documents evidencing the customer's source of wealth (PDF, JPEG, PNG or HEIC, up to 5MB each). Held by Stables and reviewed by compliance; satisfies the source_of_wealth capability once approved.

id_documents?array<>

Company identification documents

selfie_photo?

Selfie photo of the applicant

reason_for_use?string

Customer's self-declared intended use of the service. Held by Stables and reviewed by compliance; grants the reason_for_use capability once approved.

age_risk_acknowledged?boolean

Customer acknowledges age-related vulnerability and the risks of transacting in crypto. Held by Stables and reviewed by compliance; grants the age_risk_acknowledgement capability once approved.

financial_profile?

Self-declared financial profile. Required for the usd_virtual_account entitlement, whose provider treats expected monthly payment volume as mandatory.

account_purpose?string

What the customer will use Stables for, in their customer type's vocabulary. Individuals: PERSONAL_OR_LIVING_EXPENSES, RECEIVE_SALARY, PAYMENTS_TO_FRIENDS_OR_FAMILY_ABROAD, PURCHASE_GOODS_AND_SERVICES, RECEIVE_PAYMENTS_FOR_GOODS_AND_SERVICES, INVESTMENT_PURPOSES, PROTECT_WEALTH, CHARITABLE_DONATIONS, OTHER. A value outside the customer's own vocabulary is refused with 400.

Value in"PERSONAL_OR_LIVING_EXPENSES""RECEIVE_SALARY""PAYMENTS_TO_FRIENDS_OR_FAMILY_ABROAD""PURCHASE_GOODS_AND_SERVICES""RECEIVE_PAYMENTS_FOR_GOODS_AND_SERVICES""INVESTMENT_PURPOSES""PROTECT_WEALTH""CHARITABLE_DONATIONS""OTHER""ECOMMERCE_RETAIL_PAYMENTS""PAYROLL""TAX_OPTIMIZATION""THIRD_PARTY_MONEY_TRANSMISSION""TREASURY_MANAGEMENT"
account_purpose_other?string

Explain what you would use Stables for (required if accountPurpose is other)

expected_monthly_volume?string

Expected monthly volume in USD, as a band: 0_9999 (under $10,000), 10000_49999, 50000_99999, 100000_249999, 250000_999999, 1000000_plus ($1,000,000+). Held by Stables; grants the expected_monthly_volume capability with base verification (straight away once it is approved).

Value in"0_9999""10000_49999""50000_99999""100000_249999""250000_999999""1000000_plus"
occupation?string

The customer's occupation as a standardised code (SOC 2018 based), e.g. 132011 for accountant and auditor. Must be one of the accepted codes. Held by Stables; grants the occupation_code capability with base verification (straight away once it is approved).

annual_income?string

Annual income in USD, as a band: 0_24999 (under $25,000), 25000_49999, 50000_99999, 100000_249999, 250000_499999, 500000_999999, 1000000_plus ($1,000,000+). Held by Stables; grants the annual_income capability with base verification (straight away once it is approved).

Value in"0_24999""25000_49999""50000_99999""100000_249999""250000_499999""500000_999999""1000000_plus"
company_name?string

Company name

country?string

Country code (ISO 3166-1 alpha-2)

registration_number?string

Registration number

legal_address?

Postal address

incorporated_on?string

Date of incorporation in YYYY-MM-DD format

Match^\d{4}-\d{2}-\d{2}$
type?string

Company type

tax_id?string

Tax ID

registration_location?string

Registration location (country-specific, e.g., state for USA)

website?string

Website URL

Formaturi
postal_address?

Postal address

alternative_names?array<string>

Alternative names (brand names or local language variants)

beneficiaries?array<>

Company beneficiaries (UBOs, shareholders, directors)

company_registration_documents?array<>

Company registration documents (INFORMATION_STATEMENT and INCORPORATION_CERT)

describe_business?string

Description of the business

conduct_money_services?boolean

Whether the company conducts money services

describe_compliance_controls?string

Description of compliance controls

describe_money_services?string

Describe the money services your business conducts (required if conductMoneyServices is true)

expected_annual_revenue?string

Estimated annual revenue in USD

Value in"0_99999""100000_999999""1000000_9999999""10000000_49999999""50000000_249999999""250000000_plus"
expected_monthly_payments?string

Expected monthly payments in USD (numeric)

source_of_funds?string

Source of funds

Value in"BUSINESS_LOANS""GRANTS""INTER_COMPANY_FUNDS""INVESTMENT_PROCEEDS""LEGAL_SETTLEMENT""OWNERS_CAPITAL""PENSION_RETIREMENT""SALE_OF_ASSETS""SALES_OF_GOODS_AND_SERVICES""THIRD_PARTY_FUNDS""TREASURY_RESERVES"
source_of_funds_description?string

Describe where your business funds come from

operate_in_prohibited_country?boolean

Does your business operate in any prohibited countries?

does_your_business_engage_in_high_risk_activities?string

Does your business potentially engage in any High Risk activities?

Value in"yes""no"
high_risk_activities?array<>

High risk activities (required if doesYourBusinessEngageInHighRiskActivities is yes)

accept_terms?boolean

Accept Stables' terms of service and privacy policy

bank_statement_file_data?string

Bank statement file data (base64 encoded data URL, e.g., data:image/jpeg;base64,...)

flow_of_funds_file_data?string

Flow of funds document file data (base64 encoded data URL, required if conductMoneyServices is true)

trade_license?

Structured trade licence details. Required by some local-currency corridors (e.g. AED) in addition to the trade licence document itself.

enhanced_due_diligence?

Enhanced due diligence answers and supporting documents. Submitted cumulatively: each request merges into the current draft, so a partial body is valid and only adds what it carries. Use a fresh Idempotency-Key for each part, since replaying one returns the earlier response without storing anything.

Response Body

Default Response

application/json
  1. response
customer_id*CustomerId

Customer UUID

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
external_customer_id*string|null
customer_type*string

Type of customer in display format

Value in"individual""business"
email*string

Customer email

phone?string

Phone number in E.164 format (e.g., +14155552671)

Match^\+[1-9]\d{6,14}$
Formate164
entitlements?array<>

Feature-based entitlements for the customer with status

first_name?string

First name (for individuals)

last_name?string

Last name (for individuals)

company_name?string

Company name (for businesses)

created_at*string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Formatdate-time
updated_at*string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Formatdate-time
metadata?
verification_levels*array<>

All KYC level records for this customer

doc_images?

Verification document image data, returned when requested via include

age_risk_questionnaire?

Age-risk step-up questionnaire answers, present once the customer has completed the step-up

account_purpose?string

An individual's account purpose, present once given

Value in"PERSONAL_OR_LIVING_EXPENSES""RECEIVE_SALARY""PAYMENTS_TO_FRIENDS_OR_FAMILY_ABROAD""PURCHASE_GOODS_AND_SERVICES""RECEIVE_PAYMENTS_FOR_GOODS_AND_SERVICES""INVESTMENT_PURPOSES""PROTECT_WEALTH""CHARITABLE_DONATIONS""OTHER"
account_purpose_other?string

Free-text account purpose, when account_purpose is OTHER

expected_monthly_volume?string

An individual's expected monthly volume band, present once given

Value in"0_9999""10000_49999""50000_99999""100000_249999""250000_999999""1000000_plus"
occupation?string

An individual's occupation code (SOC 2018 based), present once given

occupation_title?string

Readable title of occupation, present with it

annual_income?string

An individual's annual income band, present once given

Value in"0_24999""25000_49999""50000_99999""100000_249999""250000_499999""500000_999999""1000000_plus"
status?string

Customer compliance status

compliance_lock?

Active compliance lock details, present when customer is locked

[key: string]?unknown
Example Request
curl -X PATCH 'https://api.sandbox.stables.money/api/v1/customer/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",  "external_customer_id": "string",  "customer_type": "individual",  "email": "string",  "phone": "string",  "entitlements": [    {      "name": "string",      "status": "pending",      "phase": "requires_action",      "requirements": {        "submitted": [          "string"        ],        "missing": [          "string"        ],        "issues": [          "string"        ],        "actions": [          {            "type": "verification_link",            "requirement": "string",            "verification_type": "proof_of_address",            "url": "http://example.com",            "expires_at": "2019-08-24T14:15:22Z"          }        ],        "review": {          "status": "pending",          "reason": "string",          "decided_at": "2019-08-24T14:15:22Z",          "version": -9007199254740991        },        "parties": [          {            "ref": "string",            "display_name": "string",            "category": "string",            "is_individual": true,            "has_identity": true,            "has_tax_id": true,            "has_proof_of_address": true          }        ],        "submission": {          "state": "none",          "version": -9007199254740991,          "updated_at": "2019-08-24T14:15:22Z",          "submitted_at": "2019-08-24T14:15:22Z"        }      },      "onboarding": {        "stage": "verification_required",        "next_action": "complete_verification",        "reasons": [          {            "code": "string",            "resolution": "requirements"          }        ],        "since": "2019-08-24T14:15:22Z",        "expected_wait": "minutes"      }    }  ],  "first_name": "string",  "last_name": "string",  "company_name": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "metadata": {    "property1": "string",    "property2": "string"  },  "verification_levels": [    {      "level": "kyc_level_0",      "status": "in_progress",      "sub_status": [        "BAD_PROOF_OF_IDENTITY"      ],      "stage": "collecting",      "submitted_at": "2019-08-24T14:15:22Z",      "missing_fields": [        "string"      ],      "missing_field_details": [        {          "field": "string",          "request_path": "string",          "description": "string"        }      ],      "in_review": true,      "details": [        {          "reasons": [            {              "code": "string",              "description": "string"            }          ],          "requirements": [            "string"          ]        }      ],      "review": {        "labels": [          {            "label": "string",            "description": "string",            "step": "string",            "reason_code": "string",            "requirements": [              "string"            ]          }        ],        "moderation_comment": "string",        "reviewed_at": "2019-08-24T14:15:22Z"      }    }  ],  "doc_images": {    "documents": [      {        "type": "string",        "country": "string",        "document_number": "string",        "expiry_date": "string",        "front_image_data": "string",        "back_image_data": "string",        "image_data": "string",        "outcome": "string"      }    ],    "selfie_image_data": "string"  },  "age_risk_questionnaire": {    "reason_for_use": "string",    "age_acknowledged": true  },  "account_purpose": "PERSONAL_OR_LIVING_EXPENSES",  "account_purpose_other": "string",  "expected_monthly_volume": "0_9999",  "occupation": "string",  "occupation_title": "string",  "annual_income": "0_24999",  "status": "string",  "compliance_lock": {    "locked_at": "2019-08-24T14:15:22Z",    "locked_by_user_id": "string",    "locked_by_user_name": "string",    "locked_by_user_email": "string",    "lock_reason": "string"  },  "property1": null,  "property2": null}