> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithsoap.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Upsert KYC
> Creates or updates KYC identity data for a customer
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.
## 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) |
```json Curl theme={null}
curl -X POST "https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert" \
-H "Authorization: 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": "your_kyc_provider",
"verified": true,
"last_four_ssn": "1234"
}'
```
```ruby Ruby theme={null}
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'] = '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: 'your_kyc_provider',
verified: true,
last_four_ssn: '1234'
}.to_json
response = http.request(request)
puts response.body
```
```javascript JavaScript theme={null}
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: 'your_kyc_provider',
verified: true,
last_four_ssn: '1234'
}, {
headers: {
'Authorization': 'YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
upsertKyc();
```
```python Python theme={null}
import requests
import json
url = "https://api-sandbox.paywithsoap.com/api/v1/kyc/upsert"
headers = {
"Authorization": "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())
```
```json Response theme={null}
{
"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": "your_kyc_provider",
"verified": true,
"last_four_ssn": "1234"
}
```
## OpenAPI
````yaml POST /api/v1/kyc/upsert
openapi: 3.1.0
info:
title: Soap API
description: >-
API documentation for Soap - AI-native payments infrastructure for complex,
compliance-heavy payment flows
license:
name: MIT
version: 1.4.0
servers:
- url: https://api-sandbox.paywithsoap.com
security:
- bearerAuth: []
paths:
/api/v1/kyc/upsert:
post:
tags:
- KYC
summary: Creates or updates KYC identity data for a customer
requestBody:
content:
application/json:
schema:
type: object
properties:
customer_id:
type: string
description: Unique identifier for the customer
example: cus_vi57KegYgcRqcGHqip8q6UZiqtrwMT870
first_name:
type: string
minLength: 1
description: Customer's first name
example: John
last_name:
type: string
minLength: 1
description: Customer's last name
example: Doe
email:
type:
- string
- 'null'
description: Customer's email address
example: john@example.com
phone_number:
type:
- string
- 'null'
description: Customer's phone number
example: '5551234567'
date_of_birth:
type: string
description: Customer's date of birth (YYYY-MM-DD)
example: '1990-01-15'
address_line_1:
type: string
minLength: 1
description: Primary address line
example: 123 Main Street
address_line_2:
type:
- string
- 'null'
description: Secondary address line (apartment, suite, etc.)
example: Apt 4B
city:
type: string
minLength: 1
description: City name
example: San Francisco
state:
type: string
pattern: ^[A-Z]{2}$
description: Two-letter state code (uppercase)
example: CA
postal_code:
type: string
description: Postal or ZIP code
example: '94102'
country:
type: string
pattern: ^[A-Z]{3}$
description: Three-letter country code (uppercase), defaults to USA
example: USA
default: USA
provider:
type: string
description: KYC provider identifier used for verification
example: plaid
verified:
type: boolean
description: >-
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
last_four_ssn:
type:
- string
- 'null'
pattern: ^[0-9]{4}$
minLength: 4
maxLength: 4
description: Last four digits of the customer's SSN (optional)
example: '1234'
required:
- customer_id
- first_name
- last_name
- date_of_birth
- address_line_1
- city
- state
- postal_code
- country
- provider
- verified
responses:
'200':
description: KYC identity created or updated successfully
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Unique identifier for the KYC identity record
example: id_A3GuXEbThpqk2t6UTxEuoceVJyUEAX7V
first_name:
type: string
example: John
last_name:
type: string
example: Doe
email:
type:
- string
- 'null'
example: john@example.com
phone_number:
type:
- string
- 'null'
example: '5551234567'
date_of_birth:
type: string
example: '1990-01-15'
address_line_1:
type: string
example: 123 Main Street
address_line_2:
type:
- string
- 'null'
example: null
city:
type: string
example: San Francisco
state:
type: string
example: CA
postal_code:
type: string
example: '94102'
country:
type: string
example: USA
provider:
type: string
example: your_kyc_provider
verified:
type: boolean
example: true
last_four_ssn:
type:
- string
- 'null'
example: '1234'
'401':
description: Unauthorized - Invalid or missing API key
'422':
description: Invalid request parameters
content:
application/json:
schema:
type: object
properties:
error:
type: string
hint:
type: string
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication using your API key
````