> ## 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

> Submits a KYC identity record for a customer

Submits Know Your Customer (KYC) identity information for an existing customer. Each call creates a new KYC record for the customer — nothing is updated in place — and hosted checkout uses the most recent one. 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`, `idology`, `seon`, `footprint`, `socure`, `geo_comply`, `acuity`, `surt`, `persona`, and `shufti`.

Every Soap API request is authenticated with a bearer token in the `Authorization` header:

```bash theme={null}
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.

> [!NOTE]
>
> KYC upsert is enabled by default and can be switched off per account. If it is disabled for yours, the endpoint responds with a `404` and the hint `KYC upsert is disabled for this business. Contact Soap to enable it.`

## How upserted records are used

* A customer can have several KYC records. Hosted checkout reads the **most recent** one, whether Soap created it during in-checkout verification or you submitted it here.
* Upserting `verified: false` for a customer who already passed in-checkout verification therefore sends them back through verification on their next checkout that requires KYC.
* In production, when KYC is enabled for a checkout type, every checkout of that type with a verified record checks that the verified identity's name is consistent with the customer profile's current `first_name` and `last_name`. This applies to records you submit here just as it does to Soap's own verification. Keep the profile on the customer's legal first name and surname as shown on their ID, with no nicknames, middle names, initials or suffixes. A mismatch restricts the customer with reason code [`KYC_DOES_NOT_MATCH_PROFILE_NAME`](https://docs.paywithsoap.com/api-reference/api-v1/webhooks/customer-restricted#reason-codes); fix the profile with [Update Customer](https://docs.paywithsoap.com/api-reference/api-v1/customers/update.md) and lift the restriction in the dashboard.

## 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` (accepted and stored, but not echoed back in the response)

| Field | Format |
| - | - |
| `state` | Two uppercase letters (e.g., `CA`, `NY`) |
| `country` | Three uppercase letters (e.g., `USA`). Required; there is no default. |
| `last_four_ssn` | Exactly 4 digits (optional) |

```bash Curl theme={null}
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"
  }'
```

```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'] = '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
```

```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: '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();
```

```python Python theme={null}
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",
    "provider": "plaid",
    "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": "plaid",
  "verified": true
}
```


## 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: Submit a KYC identity record for a customer
      description: >-
        Creates a new KYC identity record for an existing customer. Each call
        inserts a new record; hosted checkout reads the customer's most recent
        one.
      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 uppercase country code, for example USA.
                    Required — there is no default.
                  example: USA
                provider:
                  type: string
                  description: KYC provider identifier used for verification
                  enum:
                    - plaid
                    - veriff
                    - didit
                    - sumsub
                    - idology
                    - seon
                    - footprint
                    - socure
                    - geo_comply
                    - acuity
                    - surt
                    - persona
                    - shufti
                  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`. Hosted checkout reads the
                    customer's most recent KYC record, so `false` sends an
                    already-verified customer back through verification on their
                    next checkout that requires KYC.
                  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
        required: true
      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
        '404':
          description: The feature is disabled for this account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not found
                  hint:
                    type: string
                    example: >-
                      KYC upsert is disabled for this business. Contact Soap to
                      enable it.
        '422':
          description: >-
            Invalid request — a malformed body, an invalid field value, or a
            missing/invalid API key. Authentication failures return 422 with
            `{"error": "API key not found."}`, not 401.
          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 (key_...). Used for every
        endpoint except POST /api/v1/device_pings.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.