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

# Manage account representatives

> Add and verify business representatives, beneficial owners, and authorized signers for KYB compliance on your embedded Straddle accounts.

Representatives are individuals who have legal authority or significant responsibility within a business entity associated with a Straddle account. Understanding how to manage representatives is crucial for maintaining compliance and ensuring smooth account operations.

## Understanding Representatives

Representatives in Straddle serve several key purposes:

1. **Legal Compliance**: They fulfill regulatory requirements for identifying individuals with control over business accounts
2. **Account Management**: They can be authorized to make changes to the account or view sensitive information
3. **Risk Assessment**: They help Straddle evaluate the risk profile of an account
4. **Communication Channel**: They serve as points of contact for important account-related communications

<CardGroup cols={2}>
  <Card title="Multiple Representatives" icon="users">
    Add multiple representatives to a single account
  </Card>

  <Card title="Flexible Roles" icon="user-gear">
    Specify different roles and responsibilities for each representative
  </Card>

  <Card title="Easy Updates" icon="pen-to-square">
    Update representative information as needed programatically
  </Card>

  <Card title="Required for Compliance" icon="shield-check">
    Verified representative information is required to meet FinCEN compliance
  </Card>
</CardGroup>

<Tip>
  A representative profile must be created for at least one individual with "control"-- think a CFO, CTO, or Director -- and every individual with >25% ownership. An account can have from 1-5 representatives associated with it.
</Tip>

## Key Considerations

<Steps>
  <Step title="Collect Accurate Information" icon="clipboard-check">
    Ensure you have a robust process for collecting accurate representative information from your clients.
  </Step>

  <Step title="Explain the Importance" icon="bullhorn">
    Communicate to your clients why representative information is crucial for account setup and compliance.
  </Step>

  <Step title="Handle Status Changes" icon="arrow-progress">
    Implement logic to handle representative status changes, especially if a representative is rejected during verification.
  </Step>

  <Step title="Provide Update Mechanisms" icon="pen-to-square">
    Offer easy ways for clients to update their representative information when needed.
  </Step>
</Steps>

## Creating a Representative

To add a representative to an account, use the Create Representative endpoint.

<Warning>
  You must add at least one representative where `relationship.control` = `true` to an account before it can be onboarded.
</Warning>

### Attributes

When creating a representative, you can specify the following attributes:

| Field                           | Type    | Description                                                                  |
| ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| account\_id                     | string  | The unique identifier of the account this representative is associated with. |
| first\_name                     | string  | The first name of the representative.                                        |
| last\_name                      | string  | The last name of the representative.                                         |
| dob                             | string  | Date of birth for the representative in ISO 8601 format (YYYY-MM-DD).        |
| ssn\_last4                      | string  | The last 4 digits of the representative's Social Security Number.            |
| email                           | string  | The company email address of the representative.                             |
| mobile\_number                  | string  | The mobile phone number of the representative.                               |
| relationship                    | object  | Describes the representative's relationship to the account.                  |
| relationship.primary            | boolean | Whether this is the primary representative for the account.                  |
| relationship.control            | boolean | Whether the representative has significant control over the business.        |
| relationship.owner              | boolean | Whether the representative is an owner of the business.                      |
| relationship.percent\_ownership | number  | The percentage of ownership, if the representative is an owner.              |
| relationship.title              | string  | The job title of the representative.                                         |
| external\_id                    | string  | Your own unique identifier for the representative.                           |

### Example Request

Here's how you might create a new representative:

<CodeGroup>
  ```bash theme={null}
  curl https://api.straddle.com/v1/representatives \
    -X POST \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "account_id": "acct_1234567890abcdef",
      "first_name": "Jane",
      "last_name": "Doe",
      "dob": "1980-01-15",
      "ssn_last4": "1234",
      "email": "jane.doe@techinnovators.com",
      "mobile_number": "+1 (555) 123-4567",
      "relationship": {
        "primary": true,
        "control": true,
        "owner": true,
        "percent_ownership": 51,
        "title": "CEO"
      },
      "external_id": "rep_jd001"
    }'
  ```

  ```javascript theme={null}
  async function createRepresentative() {
    const res = await fetch('https://api.straddle.com/v1/representatives', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        account_id: 'acct_1234567890abcdef',
        first_name: 'Jane',
        last_name: 'Doe',
        dob: '1980-01-15',
        ssn_last4: '1234',
        email: 'jane.doe@techinnovators.com',
        mobile_number: '+1 (555) 123-4567',
        relationship: {
          primary: true,
          control: true,
          owner: true,
          percent_ownership: 51,
          title: 'CEO'
        },
        external_id: 'rep_jd001'
      })
    })
    const json = await res.json()
    console.log(json)
  }
  ```
</CodeGroup>

### Representative Statuses

Representatives, like accounts, have different statuses that reflect their current state in the system. Understanding these statuses is crucial for managing representatives effectively.

<ResponseField name="status" type="enum">
  Possible values:

  * `created`: Initial status when a representative is first added
  * `onboarding`: The representative is going through the verification process
  * `active`: The representative has been verified and is active
  * `rejected`: The representative has failed verification
  * `inactive`: The representative has been deactivated
</ResponseField>

### Status Details

The `status_detail` object provides more granular information about the representative's current status:

<ResponseField name="status_detail" type="object">
  <ResponseField name="reason" type="enum">
    Possible values:

    * `unverified`: Initial state, pending verification
    * `in_review`: Representative is being reviewed
    * `pending`: Waiting for additional information
    * `stuck`: Issues in the verification process
    * `verified`: Successfully verified
    * `failed_verification`: Verification process failed
    * `disabled`: Representative has been disabled
  </ResponseField>

  <ResponseField name="source" type="string">
    Always "watchtower", Straddle's compliance monitoring system.
  </ResponseField>

  <ResponseField name="code" type="string">
    A specific code related to the status reason.
  </ResponseField>

  <ResponseField name="message" type="string">
    A human-readable message providing more context about the current status.
  </ResponseField>
</ResponseField>

## Update a Representative

During the onboarding process, you may need to update representative information for various reasons. However, the ability to update a representative depends on their current status. Understanding when and why you might need to update a representative is crucial for smooth account onboarding.

### When Can You Update a Representative?

<AccordionGroup>
  <Accordion title="Updateable Statuses" icon="check">
    You can update a representative when their status is:

    * Created: Full updates allowed
    * Onboarding: Most updates allowed
    * Active: Limited updates allowed
  </Accordion>

  <Accordion title="Non-Updateable Statuses" icon="xmark">
    You cannot update a representative when their status is:

    * Rejected: Updates not allowed
    * Inactive: Updates not allowed

    <Note>
      For representatives in these statuses, contact Straddle support for assistance.
    </Note>
  </Accordion>
</AccordionGroup>

### Why Update a Representative?

There are several reasons why you might need to update a representative during the onboarding process:

1. **Correction of Errors**: Initial submission might contain mistakes that need to be rectified.
2. **Additional Information Required**: Straddle's verification process might request more details.
3. **Change in Circumstances**: The representative's role or contact information might change during onboarding.
4. **Compliance Requirements**: Additional information might be needed to meet specific regulatory requirements.

### What Can Be Updated?

Depending on the representative's status, different fields can be updated:

<AccordionGroup>
  <Accordion title="Created Status" icon="baby">
    All fields can be updated when the status is 'created'.
  </Accordion>

  <Accordion title="Onboarding Status" icon="clipboard-list">
    Most fields can be updated, but changes might restart parts of the verification process.
  </Accordion>

  <Accordion title="Active Status" icon="shield-check">
    Only non-critical information (like contact details) can typically be updated without triggering re-verification.
  </Accordion>
</AccordionGroup>

### Example: Updating a Representative

Here's an example of updating a representative's information during the onboarding process:

<CodeGroup>
  ```bash theme={null}
  curl https://api.straddle.com/v1/representatives/rep_1234567890abcdef \
    -X PUT \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "mobile_number": "+1 (555) 987-6543",
      "relationship": {
        "title": "CFO",
        "percent_ownership": 25
      }
    }'
  ```

  ```javascript theme={null}
  async function updateRepresentative() {
    const res = await fetch('https://api.straddle.com/v1/representatives/rep_1234567890abcdef', {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        mobile_number: '+1 (555) 987-6543',
        relationship: {
          title: 'CFO',
          percent_ownership: 25
        }
      })
    })
    const json = await res.json()
    console.log(json)
  }
  ```
</CodeGroup>

### Best Practices for Updating Representatives

<Check>
  Follow these best practices when updating representative information during onboarding:
</Check>

1. **Check Current Status**: Always verify the representative's current status before attempting an update.
2. **Minimize Changes**: Only update information that is absolutely necessary to avoid delays in the verification process.
3. **Provide Explanations**: When making significant changes, consider adding a note in the metadata to explain the reason for the update.
4. **Monitor Status Changes**: After an update, closely monitor the representative's status for any changes or additional requirements.
5. **Prepare for Re-verification**: Be aware that certain updates might trigger a re-verification process, potentially extending the onboarding timeline.

<Warning>
  Updating critical information (like name or date of birth) for a representative in 'active' status may trigger a re-verification process. Only do this if absolutely necessary and be prepared for potential delays.
</Warning>

### Handling Update Restrictions

If you attempt to update a representative in a non-updateable status (rejected or inactive), you'll receive an error response. In these cases:

1. For **rejected** status: Review the rejection reason in the status\_detail. You may need to create a new representative instead of updating the existing one.
2. For **inactive** status: Contact Straddle support for guidance on how to proceed, as reactivation might be possible in some cases.

<Info>
  Remember, the ability to update representatives is designed to ensure accuracy of information during the onboarding process while maintaining the integrity of Straddle's verification procedures. Always prioritize providing accurate information from the start to minimize the need for updates and potential delays.
</Info>

## Lookup a Representative

To view the details of a specific representative, use the Get Representative endpoint.

#### Example Request

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

  ```javascript theme={null}
  async function getRepresentative() {
    const res = await fetch('https://api.straddle.com/v1/representatives/rep_1234567890abcdef', {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    })
    const json = await res.json()
    console.log(json)
  }
  ```
</CodeGroup>

## Best Practices

When working with representatives in Straddle, consider the following best practices:

<AccordionGroup>
  <Accordion title="Verify Information" icon="user-check">
    Always verify the accuracy of representative information before submission. Incorrect details can lead to verification issues.
  </Accordion>

  <Accordion title="Multiple Representatives" icon="users">
    Consider adding multiple representatives to ensure continuity of account access and management.
  </Accordion>

  <Accordion title="Timely Updates" icon="clock">
    Update representative information promptly when changes occur to maintain compliance and accurate records.
  </Accordion>

  <Accordion title="Privacy Considerations" icon="shield">
    Handle representative personal information with care, adhering to relevant data protection regulations.
  </Accordion>
</AccordionGroup>

## For Platforms: Managing Client Representatives

If you're a platform creating accounts on behalf of your clients, here are some key considerations for managing representatives:

<Steps>
  <Step title="Collect Accurate Information" icon="clipboard-check">
    Ensure you have a robust process for collecting accurate representative information from your clients.
  </Step>

  <Step title="Explain the Importance" icon="bullhorn">
    Communicate to your clients why representative information is crucial for account setup and compliance.
  </Step>

  <Step title="Handle Status Changes" icon="exchange-alt">
    Implement logic to handle representative status changes, especially if a representative is rejected during verification.
  </Step>

  <Step title="Provide Update Mechanisms" icon="pen-to-square">
    Offer easy ways for clients to update their representative information when needed.
  </Step>
</Steps>

<Warning>
  Remember, at least one representative must be added to an account before it can be onboarded. Ensure you add representatives promptly after account creation to avoid delays in the onboarding process.
</Warning>