> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verifying customers and KYC

> Manage customers who send or receive payments through Straddle, including KYC identity verification, risk decisions, and reasons for review.

Customers are the foundation of every payment flow in Straddle—representing the individuals or businesses who send and receive money through your platform. When you create a customer, Straddle automatically triggers identity verification, fraud screening, and compliance checks in real-time, enabling instant onboarding while maintaining security.

## What This Guide Covers

This comprehensive guide provides everything you need to implement customer management:

* **Customer lifecycle**: From creation through verification to ongoing monitoring
* **Identity verification**: How automated KYC/AML checks work behind the scenes
* **Review process**: Understanding and decisioning customers flagged for review
* **Business customers**: Special requirements for company verification
* **Best practices**: Optimizing approval rates while preventing fraud

## The Customer Object

Every customer in Straddle represents either an `individual` person or a `business` entity. The customer object contains identity information, verification status, and metadata that enables secure payment processing.

### Core Fields

| Field         | Type   | Description                                                                          |
| ------------- | ------ | :----------------------------------------------------------------------------------- |
| `id`          | string | Unique identifier for the customer, generated by Straddle                            |
| `name`        | string | Full name of the individual or business name                                         |
| `type`        | string | Type of customer: `individual` or `business`                                         |
| `email`       | string | Customer's email address                                                             |
| `phone`       | string | Customer's phone number in E.164 format (+1234567890)                                |
| `external_id` | string | Your system's unique identifier for this customer                                    |
| `status`      | string | Current verification status: `pending`, `review`, `verified`, `rejected`, `inactive` |

### Address Object

| Field              | Type   | Description                        |
| ------------------ | ------ | :--------------------------------- |
| `address.address1` | string | Primary address line               |
| `address.address2` | string | Secondary address line (optional)  |
| `address.city`     | string | City name                          |
| `address.state`    | string | State code (2-letter abbreviation) |
| `address.zip`      | string | ZIP code (5 or 9 digits)           |

### Compliance Profile

| Field                                    | Type   | Description                                               | Applies To |
| ---------------------------------------- | ------ | :-------------------------------------------------------- | :--------- |
| `compliance_profile.dob`                 | string | Date of birth (YYYY-MM-DD format)                         | Individual |
| `compliance_profile.ssn`                 | string | Full or last 4 digits of SSN (always masked in responses) | Individual |
| `compliance_profile.ein`                 | string | Employer Identification Number                            | Business   |
| `compliance_profile.legal_business_name` | string | Legal entity name as registered                           | Business   |
| `compliance_profile.website`             | string | Company's official website URL                            | Business   |
| `compliance_profile.representatives`     | array  | List of authorized representatives with ownership details | Business   |

### Additional Fields

| Field               | Type     | Description                                                                            |
| ------------------- | -------- | :------------------------------------------------------------------------------------- |
| `device.ip_address` | string   | IP address (IPv4 or IPv6) captured during customer creation (used for fraud detection) |
| `config`            | object   | Configuration options including sandbox testing outcomes                               |
| `metadata`          | object   | Custom key-value pairs for your reference                                              |
| `created_at`        | datetime | ISO 8601 timestamp of creation                                                         |
| `updated_at`        | datetime | ISO 8601 timestamp of last update                                                      |

## Automatic Identity Verification

When you create a customer, Straddle automatically triggers a comprehensive verification pipeline that includes:

<AccordionGroup>
  <Accordion title="Identity" icon="fingerprint">
    <ul>
      <li><strong>Fraud:</strong> Straddle employs a machine learning model trained with hundreds of predictors to detect the likelihood of identity fraud. Provides 98% instant risk decisions without the need for selfies.</li>
      <li><strong>Synthetic Identities:</strong> Purpose-built and trained with consortium data to tackle fake and randomized synthetic identity patterns. Produces highly accurate, real-time, actionable risk scores and reason codes, with 90% auto-capture in the riskiest 3% of users.</li>
      <li><strong>Email / Phone / Address Risk:</strong> Provides a risk score and correlation value for email addresses, phone numbers, and physical addresses. Risk scores use ML models trained on specific variables and layered with 800 million rows of known good and bad outcomes to predict the likelihood of fraud.</li>
      <li><strong>Device Risk (Coming Soon):</strong> Predicts risk associated with a device using data attributes such as IP, geolocation, device type, and device software. Device is the first application fraud solution that "binds" a device to the individual using it to counter application fraud and validate customer logins.</li>
    </ul>
  </Accordion>

  <Accordion title="KYC" icon="id-card">
    <p><strong>Know Your Customer (KYC)</strong> matches consumer-provided PII against the closest single identity on record or best-matched entity and returns a true or false value indicating the likelihood of a match. KYC is a legal requirement for financial institutions and financial services companies to establish a consumer's identity and identify risk factors.</p>
    <p>Straddle KYC is accurately auditable and fully compliant with Section 326 of the US Patriot Act, the Customer Identification Program (CIP), and FinCEN's expanded Customer Due Diligence (CDD) program.</p>
    <Note> Include `dob` and `ssn` in the “Compliance Profile” of an API request when creating a customer to trigger KYC validation</Note>
  </Accordion>

  <Accordion title="AML and Watchlist Monitoring" icon="shield-check">
    <p><strong>Global Watchlist Screening with Monitoring</strong> identifies risk by matching person and non-person entities against sanctions and enforcement lists, as well as Politically Exposed Persons (PEP) and adverse media registries worldwide.</p>
    <h4>Features</h4>

    <ul>
      <li><strong>Sanctions and Enforcements Screening:</strong> Screen consumers and businesses during onboarding to identify if they are sanctioned or flagged by enforcement authorities.</li>
      <li><strong>PEP Screening:</strong> Screen individuals against PEP lists to identify those who could pose a higher Anti-Money Laundering (AML) risk.</li>
      <li><strong>Adverse Media Screening:</strong> Protect your company's reputation by identifying individuals associated with news items related to financial crimes.</li>
      <li><strong>Real-Time Monitoring:</strong> Continuously monitor existing customers in real time to determine if they appear on updated sanctions or PEP lists.</li>
    </ul>

    <CardGroup cols={2}>
      <Card title="OFAC SDN and consolidated lists" icon="list-check" />

      <Card title="US, Canada, and global lists" icon="globe" />

      <Card title="Enforcement lists" icon="gavel" />

      <Card title="311 Special Measures" icon="scale-balanced" />

      <Card title="OIG exclusion lists" icon="ban" />

      <Card title="EPLS, HIDTA, HIFCA" icon="building-shield" />
    </CardGroup>
  </Accordion>
</AccordionGroup>

## Customer Status Lifecycle

Every customer progresses through a defined verification lifecycle:

| Status     | Description                              | Next Actions                                                              |
| ---------- | ---------------------------------------- | ------------------------------------------------------------------------- |
| `pending`  | Initial state, verification in progress  | Wait for automatic verification to complete                               |
| `review`   | Manual review required (rare edge cases) | Use `/review` endpoint to see details, then `/decision` to approve/reject |
| `verified` | Passed all verification checks           | Ready to process payments                                                 |
| `rejected` | Failed verification requirements         | Cannot process payments, may need new customer                            |
| `inactive` | Deactivated customer account             | No longer able to transact                                                |

<Note>
  **Security**: SSN values are always masked in API responses. Use the `/unmasked` endpoint only when absolutely necessary and ensure proper access controls.
</Note>

## Creating a Customer

To create a customer, you'll use the `POST /v1/customers` endpoint. Here's an example of how to create a customer using the Straddle API:

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://api.straddle.com/v1/customers \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "John Doe",
      "type": "individual",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "address": {
        "address1": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345",
        "type": "residential"
      },
      "compliance_profile": {
        "dob": "1990-01-01",
        "ssn": "123-45-6789"
      },
      "external_id": "cust_123",
      "metadata": {
        "user_id": "user_123"
      }
    }'
  ```

  ```javascript theme={null}
  const createCustomer = async () => {
    try {
      const res = await fetch('https://api.straddle.com/v1/customers', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          name: "John Doe",
          type: "individual",
          email: "john.doe@example.com",
          phone: "+1234567890",
          address: {
            address1: "123 Main St",
            city: "Anytown",
            state: "CA",
            zip: "12345",
            type: "residential"
          },
          compliance_profile: {
            dob: "1990-01-01",
            ssn: "123-45-6789"
          },
          external_id: "cust_123",
          metadata: {
            user_id: "user_123"
          }
        })
      });
      const data = await res.json();
      console.log(data);
    } catch (error) {
      console.error(error);
    }
  };

  createCustomer();
  ```
</CodeGroup>

This request creates a new customer with the provided information. The response will include a unique `id` for the customer, which you'll use for future operations.

<Note>
  Ensure that you handle sensitive information like SSNs securely and in compliance with relevant regulations.
</Note>

## Retrieving Customer Information

To retrieve information about a customer, use the `GET /v1/customers/{id}` endpoint:

<CodeGroup>
  ```bash theme={null}
  curl https://api.straddle.com/v1/customers/{id} \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript theme={null}
  const getCustomer = async (id) => {
    try {
      const res = await fetch(`https://api.straddle.com/v1/customers/${id}`, {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      });
      const data = await res.json();
      console.log(data);
    } catch (error) {
      console.error(error);
    }
  };

  getCustomer('cust_123');
  ```
</CodeGroup>

## Updating Customer Information

You can update a customer's information using the `PUT /v1/customers/{id}` endpoint:

<CodeGroup>
  ```bash theme={null}
  curl -X PUT https://api.straddle.com/v1/customers/{id} \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "John Smith",
      "email": "john.smith@example.com"
    }'
  ```

  ```javascript theme={null}
  const updateCustomer = async (id) => {
    try {
      const res = await fetch(`https://api.straddle.com/v1/customers/${id}`, {
        method: 'PUT',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          name: "John Smith",
          email: "john.smith@example.com"
        })
      });
      const data = await res.json();
      console.log(data);
    } catch (error) {
      console.error(error);
    }
  };

  updateCustomer('cust_123');
  ```
</CodeGroup>

<Warning>
  Updating certain fields may trigger a re-verification process, which could change the customer's status.
</Warning>

## Listing Customers

To retrieve a list of customers, use the `GET /v1/customers` endpoint. This endpoint supports pagination and various filter options:

<CodeGroup>
  ```bash theme={null}
  curl "https://api.straddle.com/v1/customers?page_number=1&page_size=10&sort_by=created_at&sort_order=desc" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript theme={null}
  const listCustomers = async () => {
    try {
      const res = await fetch('https://api.straddle.com/v1/customers?page_number=1&page_size=10&sort_by=created_at&sort_order=desc', {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      });
      const data = await res.json();
      console.log(data);
    } catch (error) {
      console.error(error);
    }
  };

  listCustomers();
  ```
</CodeGroup>

You can filter customers by various parameters such as `status`, `type`, `created_from`, `created_to`, and more. Refer to the API reference for a complete list of available filters.

## Handling Review Status

When customers require manual review (status = `review`), use two endpoints to handle the review process:

### 1. Get Review Details

Retrieve detailed verification results using `GET /v1/customers/{id}/review`:

<CodeGroup>
  ```bash theme={null}
  curl https://api.straddle.com/v1/customers/{id}/review \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript theme={null}
  const getCustomerReview = async (id) => {
    try {
      const res = await fetch(`https://api.straddle.com/v1/customers/${id}/review`, {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      });
      const data = await res.json();
      console.log(data);
    } catch (error) {
      console.error(error);
    }
  };

  getCustomerReview('cust_123');
  ```
</CodeGroup>

The review response includes:

* `identity_details`: Complete identity verification results including KYC, watchlist, reputation scores
* `customer_details`: Current customer information
* `messages`: Specific issues or requirements
* `network_alerts`: Any consortium fraud signals

### 2. Make a Decision

After reviewing the details, make a decision using `PATCH /v1/customers/{id}/review`:

<CodeGroup>
  ```bash theme={null}
  curl -X PATCH https://api.straddle.com/v1/customers/{id}/review \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "verified"  // or "rejected"
    }'
  ```

  ```javascript theme={null}
  const updateCustomerReview = async (id) => {
    try {
      const res = await fetch(`https://api.straddle.com/v1/customers/${id}/review`, {
        method: 'PATCH',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ status: 'verified' }) // or 'rejected'
      });
      const data = await res.json();
      console.log(data);
    } catch (error) {
      console.error(error);
    }
  };

  updateCustomerReview('cust_123');
  ```
</CodeGroup>

## Accessing Sensitive Data

<Warning>
  **Compliance Alert**: Access to unmasked data requires special permissions and generates audit logs. Only use when absolutely necessary for regulatory compliance or customer support.
</Warning>

### Retrieve Unmasked Data

Use `GET /v1/customers/{id}/unmasked` to access full sensitive information:

<CodeGroup>
  ```bash theme={null}
  curl https://api.straddle.com/v1/customers/{id}/unmasked \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript theme={null}
  const getUnmaskedCustomer = async (id) => {
    try {
      const res = await fetch(`https://api.straddle.com/v1/customers/${id}/unmasked`, {
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      });
      const data = await res.json();
      console.log(data);
    } catch (error) {
      console.error(error);
    }
  };

  getUnmaskedCustomer('cust_123');
  ```
</CodeGroup>

The unmasked endpoint returns:

* Full SSN (not just last 4 digits)
* Complete compliance profile data
* All sensitive fields in plaintext

## Best Practices

<CardGroup cols={2}>
  <Card title="Optimize Approval Rates" icon="chart-line">
    * Include full address (address1, city, state, zip)
    * Provide accurate phone numbers in E.164 format
    * Use legal names matching government IDs
    * Include SSN for immediate KYC verification
  </Card>

  <Card title="Handle Reviews Properly" icon="eye">
    * Use `/review` endpoint to understand issues
    * Make timely decisions with `/review` PATCH
    * Document decision rationale for compliance
    * Monitor review rates to identify patterns
  </Card>

  <Card title="Maintain Security" icon="shield-check">
    * Never log or store unmasked SSN data
    * Use `/unmasked` endpoint sparingly
    * Implement audit logging for sensitive access
    * Rotate API keys regularly
  </Card>

  <Card title="Use Webhooks" icon="webhook">
    * Set up customer status change notifications
    * React to review status immediately
    * Track verification success rates
    * Monitor for unusual patterns
  </Card>
</CardGroup>

## Understanding Verification Results

The `/review` endpoint provides detailed verification results including:

* **KYC Results**: Identity match confidence and specific field matches
* **Reputation Scores**: Email, phone, and address risk assessments
* **Watchlist Results**: Any sanctions, PEP, or adverse media hits
* **Network Alerts**: Consortium fraud signals and patterns
* **Messages**: Specific verification issues with reason codes

For complete reason code reference, see [Reason Codes Guide](/guides/identity/reasons).

## Testing in Sandbox

Use the `config.sandbox_outcome` field to test different verification scenarios:

```json theme={null}
{
  "name": "Test User",
  "type": "individual",
  "config": {
    "sandbox_outcome": "verified"  // or "review", "rejected"
  }
  // ... other fields
}
```

## Business Customers

Business customers require additional fields in the compliance profile:

* `ein`: Employer Identification Number
* `legal_business_name`: Official registered name
* `website`: Company website
* `representatives`: Array of authorized signers with ownership percentages

See [Business Identity Guide](/guides/identity/business_identity) for complete requirements.

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/customers/create">
    Complete endpoint documentation for customers
  </Card>

  <Card title="Business Identity" icon="building" href="/guides/identity/business_identity">
    Special requirements for business verification
  </Card>

  <Card title="Reason Codes" icon="list" href="/guides/identity/reasons">
    Understanding verification messages and codes
  </Card>

  <Card title="Webhook Events" icon="webhook" href="/webhooks/overview">
    Set up real-time customer status notifications
  </Card>
</CardGroup>