Customers
/
Create Customer

Create Customer

POST
https://api.vivamo.co/v1/customers

Create a new customer record. Required before creating payment or disbursement intents. Minimum fields: externalCustomerId and data.email. Returns 400 if a customer with the same externalCustomerId or data.email already exists.

KYC verification: To start or inspect verification for a customer, call Get Customer KYC Info — that endpoint is the canonical entry point and returns the clientSecretKey your frontend passes to vivamo.createKycElements(). The legacy verifyAfterCreation flag is deprecated and will be removed in a future release; do not use it in new integrations.

Note: Customers in non-production environments can be created using disposable or +suffix addresses, however due to a number of gateway/processor restrictions, payments are likely to fail. A warning will be included in the response indicating such.

Request body

    externalCustomerId
    string
    Required
    The unique identifier of the customer in your system. Must be unique within your integration.
    Examples:user_123
    verifyAfterCreation
    boolean
    Deprecated
    Defaults: false

    Deprecated. Do not use in new integrations. Call Get Customer KYC Info after creating the customer to initiate verification and obtain the clientSecretKey for the SDK. This flag will be removed in a future release.

    data
    object
    Required

    Customer profile fields. Only email is required — all other fields are collected during SDK flows where needed.

      email
      string
      Required

      Customer email address. Must not use a disposable domain or contain a + suffix.

      Examples:demo@vivamo.co
      phone
      string

      Customer mobile number in international format (e.g. +15551234567). Must be a valid mobile number — landlines and VOIP numbers are rejected. If provided without a + prefix and with at least 10 digits, +1 (US) is prepended automatically. Recommended if available — customers without a phone number are prompted to enter one during the SDK flow.

      Examples:+15551234567
      firstName
      string
      Customer's first name.
      Examples:John
      lastName
      string
      Customer's last name.
      Examples:Smith
      street
      string
      Street address.
      Examples:123 42nd St
      street2
      string
      Additional street address (apartment, suite, etc.).
      Examples:Suite 42
      state
      string
      2-character state code for US addresses.
      Examples:NY
      city
      string
      City name.
      Examples:New York
      zip
      string
      ZIP or postal code.
      Examples:10001
      country
      string
      2-character ISO 3166 Alpha-2 country code.
      Examples:US

Response

Customer created successfully.
    externalCustomerId
    string
    The customer identifier you provided.
    data
    object

    Customer profile fields. Only email is required — all other fields are collected during SDK flows where needed.

      email
      string
      Required

      Customer email address. Must not use a disposable domain or contain a + suffix.

      Examples:demo@vivamo.co
      phone
      string

      Customer mobile number in international format (e.g. +15551234567). Must be a valid mobile number — landlines and VOIP numbers are rejected. If provided without a + prefix and with at least 10 digits, +1 (US) is prepended automatically. Recommended if available — customers without a phone number are prompted to enter one during the SDK flow.

      Examples:+15551234567
      firstName
      string
      Customer's first name.
      Examples:John
      lastName
      string
      Customer's last name.
      Examples:Smith
      street
      string
      Street address.
      Examples:123 42nd St
      street2
      string
      Additional street address (apartment, suite, etc.).
      Examples:Suite 42
      state
      string
      2-character state code for US addresses.
      Examples:NY
      city
      string
      City name.
      Examples:New York
      zip
      string
      ZIP or postal code.
      Examples:10001
      country
      string
      2-character ISO 3166 Alpha-2 country code.
      Examples:US
    kycVerifications
    array of object
    A KYC verification record for a customer.
      type
      string
      The type of verification. Currently, only `proof_of_id` is supported.
      Examples:proof_of_id
        proof_of_id
        string
      status
      string
      Current verification status.
      Examples:pending
        pending
        string
        verified
        string
        under_review
        string
        rejected
        string
        expired
        string
        verified_manually
        string
        rejected_manually
        string
      createdAt
      string
      Timestamp when the verification was initiated.
      Examples:2025-06-17T00:16:31.155Z
    createdAt
    string
    Timestamp when the customer was created.
    verificationLink
    string
    Deprecated

    Deprecated. Only present when the (deprecated) verifyAfterCreation flag was sent. Use Get Customer KYC Info instead.

    driversLicenseVerificationLink
    string
    Deprecated

    Deprecated. See verificationLink.

    passportVerificationLink
    string
    Deprecated

    Deprecated. See verificationLink.

    verificationLinkError
    string
    Deprecated

    Deprecated. Error message if the legacy verification link could not be generated. Only present when verifyAfterCreation was sent.

Built with