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. Optionally triggers KYC verification via verifyAfterCreation. 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
    Defaults: false

    Set to true to initiate KYC verification after customer creation. A verification link is returned in the response. Ignored if KYC is not enabled for your integration.

    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

    URL for the customer to complete KYC verification. Only present when verifyAfterCreation is true.

    driversLicenseVerificationLink
    string

    Direct URL for driver's license verification. Only present when verifyAfterCreation is true.

    passportVerificationLink
    string

    Direct URL for passport verification. Only present when verifyAfterCreation is true.

    verificationLinkError
    string
    Error message if the verification link could not be generated.
Built with