Upsert KYC

curl -X POST "https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone_number": "5551234567",
    "date_of_birth": "1990-01-15",
    "address_line_1": "123 Main Street",
    "address_line_2": null,
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "USA",
    "provider": "plaid",
    "verified": true,
    "last_four_ssn": "1234"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse('https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  customer_id: 'cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870',
  first_name: 'John',
  last_name: 'Doe',
  email: 'john@example.com',
  phone_number: '5551234567',
  date_of_birth: '1990-01-15',
  address_line_1: '123 Main Street',
  address_line_2: nil,
  city: 'San Francisco',
  state: 'CA',
  postal_code: '94102',
  country: 'USA',
  provider: 'plaid',
  verified: true,
  last_four_ssn: '1234'
}.to_json

response = http.request(request)
puts response.body

const axios = require('axios');

const upsertKyc = async () => {
  try {
    const response = await axios.post('https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert', {
      customer_id: 'cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870',
      first_name: 'John',
      last_name: 'Doe',
      email: 'john@example.com',
      phone_number: '5551234567',
      date_of_birth: '1990-01-15',
      address_line_1: '123 Main Street',
      address_line_2: null,
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94102',
      country: 'USA',
      provider: 'plaid',
      verified: true,
      last_four_ssn: '1234'
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

upsertKyc();

import requests
import json

url = "https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert"

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone_number": "5551234567",
    "date_of_birth": "1990-01-15",
    "address_line_1": "123 Main Street",
    "address_line_2": None,
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "USA",
    "verified": True,
    "last_four_ssn": "1234"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

{
  "id": "id_A3GuXEbThpqk2t6UTxEuoceVJyUEAX7V",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone_number": "5551234567",
  "date_of_birth": "1990-01-15",
  "address_line_1": "123 Main Street",
  "address_line_2": null,
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94102",
  "country": "USA",
  "provider": "plaid",
  "verified": true,
  "last_four_ssn": "1234"
}

POST

api

kyc

upsert

curl -X POST "https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone_number": "5551234567",
    "date_of_birth": "1990-01-15",
    "address_line_1": "123 Main Street",
    "address_line_2": null,
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "USA",
    "provider": "plaid",
    "verified": true,
    "last_four_ssn": "1234"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse('https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  customer_id: 'cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870',
  first_name: 'John',
  last_name: 'Doe',
  email: 'john@example.com',
  phone_number: '5551234567',
  date_of_birth: '1990-01-15',
  address_line_1: '123 Main Street',
  address_line_2: nil,
  city: 'San Francisco',
  state: 'CA',
  postal_code: '94102',
  country: 'USA',
  provider: 'plaid',
  verified: true,
  last_four_ssn: '1234'
}.to_json

response = http.request(request)
puts response.body

const axios = require('axios');

const upsertKyc = async () => {
  try {
    const response = await axios.post('https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert', {
      customer_id: 'cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870',
      first_name: 'John',
      last_name: 'Doe',
      email: 'john@example.com',
      phone_number: '5551234567',
      date_of_birth: '1990-01-15',
      address_line_1: '123 Main Street',
      address_line_2: null,
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94102',
      country: 'USA',
      provider: 'plaid',
      verified: true,
      last_four_ssn: '1234'
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

upsertKyc();

import requests
import json

url = "https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert"

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone_number": "5551234567",
    "date_of_birth": "1990-01-15",
    "address_line_1": "123 Main Street",
    "address_line_2": None,
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "USA",
    "verified": True,
    "last_four_ssn": "1234"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

{
  "id": "id_A3GuXEbThpqk2t6UTxEuoceVJyUEAX7V",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone_number": "5551234567",
  "date_of_birth": "1990-01-15",
  "address_line_1": "123 Main Street",
  "address_line_2": null,
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94102",
  "country": "USA",
  "provider": "plaid",
  "verified": true,
  "last_four_ssn": "1234"
}

Creates or updates Know Your Customer (KYC) identity information for an existing customer. Use this endpoint when you have already verified customer identity through your own KYC provider and want to sync that data with Soap. The provider field identifies which KYC provider performed the verification. Accepted values are plaid, veriff, didit, sumsub, seon, socure, geo_comply, surt, and persona. Every Soap API request is authenticated with a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Your API key is in the Soap Dashboard under the Developers section. It looks like key_.... Requests with a missing or invalid API key return 422 — never 401 — with a JSON error field, usually {"error": "API key not found."}. Branch on the status code rather than the message: GET /api/v1/device_pings/latest_geo_check does not yet return the same wording. Never expose your API key in client-side code — it is server-side only.

Required Fields

Required: customer_id, first_name, last_name, date_of_birth, address_line_1, city, state, postal_code, country, provider, verified Optional: address_line_2, phone_number, email, last_four_ssn

Field	Format
`state`	Two uppercase letters (e.g., `CA`, `NY`)
`country`	Three uppercase letters (e.g., `USA`)
`last_four_ssn`	Exactly 4 digits (optional)

curl -X POST "https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone_number": "5551234567",
    "date_of_birth": "1990-01-15",
    "address_line_1": "123 Main Street",
    "address_line_2": null,
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "USA",
    "provider": "plaid",
    "verified": true,
    "last_four_ssn": "1234"
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse('https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  customer_id: 'cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870',
  first_name: 'John',
  last_name: 'Doe',
  email: 'john@example.com',
  phone_number: '5551234567',
  date_of_birth: '1990-01-15',
  address_line_1: '123 Main Street',
  address_line_2: nil,
  city: 'San Francisco',
  state: 'CA',
  postal_code: '94102',
  country: 'USA',
  provider: 'plaid',
  verified: true,
  last_four_ssn: '1234'
}.to_json

response = http.request(request)
puts response.body

const axios = require('axios');

const upsertKyc = async () => {
  try {
    const response = await axios.post('https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert', {
      customer_id: 'cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870',
      first_name: 'John',
      last_name: 'Doe',
      email: 'john@example.com',
      phone_number: '5551234567',
      date_of_birth: '1990-01-15',
      address_line_1: '123 Main Street',
      address_line_2: null,
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94102',
      country: 'USA',
      provider: 'plaid',
      verified: true,
      last_four_ssn: '1234'
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
};

upsertKyc();

import requests
import json

url = "https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert"

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "customer_id": "cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone_number": "5551234567",
    "date_of_birth": "1990-01-15",
    "address_line_1": "123 Main Street",
    "address_line_2": None,
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "USA",
    "verified": True,
    "last_four_ssn": "1234"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

{
  "id": "id_A3GuXEbThpqk2t6UTxEuoceVJyUEAX7V",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone_number": "5551234567",
  "date_of_birth": "1990-01-15",
  "address_line_1": "123 Main Street",
  "address_line_2": null,
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94102",
  "country": "USA",
  "provider": "plaid",
  "verified": true,
  "last_four_ssn": "1234"
}

Authorizations

Authorization

string

header

required

Bearer token authentication using your API key (key_...). Used for every endpoint except POST /api/v1/device_pings.

Body

application/json

customer_id

string

required

Unique identifier for the customer

Example:

"cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870"

first_name

string

required

Customer's first name

Minimum string length: 1

Example:

"John"

last_name

string

required

Customer's last name

Minimum string length: 1

Example:

"Doe"

date_of_birth

string

required

Customer's date of birth (YYYY-MM-DD)

Example:

"1990-01-15"

address_line_1

string

required

Primary address line

Minimum string length: 1

Example:

"123 Main Street"

city

string

required

City name

Minimum string length: 1

Example:

"San Francisco"

state

string

required

Two-letter state code (uppercase)

Pattern: ^[A-Z]{2}$

Example:

"CA"

postal_code

string

required

Postal or ZIP code

Example:

"94102"

country

string

default:USA

required

Three-letter country code (uppercase), defaults to USA

Pattern: ^[A-Z]{3}$

Example:

"USA"

provider

enum<string>

required

KYC provider identifier used for verification

Available options:

plaid,

veriff,

didit,

sumsub,

seon,

socure,

geo_comply,

surt,

persona

Example:

"plaid"

verified

boolean

required

Whether the customer has been verified by the KYC provider. You can choose to provide an unverified identity by setting this field value to false

Example:

true

string | null

Customer's email address

Example:

"john@example.com"

phone_number

string | null

Customer's phone number

Example:

"5551234567"

address_line_2

string | null

Secondary address line (apartment, suite, etc.)

Example:

"Apt 4B"

last_four_ssn

string | null

Last four digits of the customer's SSN (optional)

Required string length: 4

Pattern: ^[0-9]{4}$

Example:

"1234"

Response

KYC identity created or updated successfully

string

Unique identifier for the KYC identity record

Example:

"id_A3GuXEbThpqk2t6UTxEuoceVJyUEAX7V"

first_name

string

Example:

"John"

last_name

string

Example:

"Doe"

string | null

Example:

"john@example.com"

phone_number

string | null

Example:

"5551234567"

date_of_birth

string

Example:

"1990-01-15"

address_line_1

string

Example:

"123 Main Street"

address_line_2

string | null

Example:

null

city

string

Example:

"San Francisco"

state

string

Example:

"CA"

postal_code

string

Example:

"94102"

country

string

Example:

"USA"

provider

string

Example:

"your_kyc_provider"

verified

boolean

Example:

true

last_four_ssn

string | null

Example:

"1234"

API Documentation

API Endpoints

Webhooks

Testing

Required Fields

Authorizations

Body

Response

​Required Fields

Authorizations

Body

Response

Required Fields