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

# Create Account

> Create a new tax preparation account for a client with custom branding and authentication

## Overview

The Create Account endpoint allows you to onboard new clients to Fifteenth services. Each account is associated with your partner organization and includes unique login credentials, custom branding, and access to professional tax preparation services.

<Note>
  Account creation returns a unique login link that expires in 7 days. This allows your clients to access their Fifteenth account without creating separate credentials.
</Note>

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token with your Partner API key
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Body Parameters

<ParamField body="email" type="string" required>
  Client's primary email address for communication and account access.

  **Validation**: Must be valid email format\
  **Example**: `john.doe@example.com`
</ParamField>

<ParamField body="first_name" type="string" required>
  Client's first name as it appears on tax documents.

  **Format**: Max 50 characters\
  **Example**: `John`
</ParamField>

<ParamField body="last_name" type="string" required>
  Client's last name as it appears on tax documents.

  **Format**: Max 50 characters\
  **Example**: `Doe`
</ParamField>

<ParamField body="spouse" type="object">
  Optional spouse information. If provided, the spouse will have full account access equivalent to the primary account holder.

  <Expandable title="spouse object">
    <ParamField body="spouse.email" type="string" required>
      Spouse's email address for login and communications.
      **Validation**: Must be valid email format, unique across Fifteenth
    </ParamField>

    <ParamField body="spouse.first_name" type="string" required>
      Spouse's first name as it appears on tax documents.
      **Format**: Max 50 characters
    </ParamField>

    <ParamField body="spouse.last_name" type="string" required>
      Spouse's last name as it appears on tax documents.
      **Format**: Max 50 characters
    </ParamField>

    <ParamField body="spouse.send_invitation" type="boolean">
      Whether to send an invitation email to the spouse.
      **Default**: `true`
    </ParamField>
  </Expandable>
</ParamField>

## Response

### Success Response

<ResponseField name="id" type="number">
  Unique Fifteenth account identifier.
</ResponseField>

<ResponseField name="status" type="string">
  Current account status. Always `active` for newly created accounts.
</ResponseField>

<ResponseField name="login_link" type="string">
  **IMPORTANT**: Unique, time-limited URL for client access to their Fifteenth account.

  This link:

  * Expires in 7 days from creation
  * Can only be used once for initial login
  * Grants full access to the client's account
  * Should be securely transmitted to the client
</ResponseField>

<ResponseField name="login_link_expires_at" type="string">
  ISO 8601 timestamp when the login link expires.
</ResponseField>

<ResponseField name="spouse" type="object">
  Spouse information and access details (if spouse was provided in request).

  <Expandable title="spouse object">
    <ResponseField name="spouse.id" type="number">
      Unique spouse user identifier.
    </ResponseField>

    <ResponseField name="spouse.email" type="string">
      Spouse's email address.
    </ResponseField>

    <ResponseField name="spouse.first_name" type="string">
      Spouse's first name.
    </ResponseField>

    <ResponseField name="spouse.last_name" type="string">
      Spouse's last name.
    </ResponseField>

    <ResponseField name="spouse.login_link" type="string">
      Unique login link for spouse's first-time access (if invitation sent).
    </ResponseField>

    <ResponseField name="spouse.login_link_expires_at" type="string">
      Expiration timestamp for the spouse's login link.
    </ResponseField>

    <ResponseField name="spouse.status" type="string">
      Spouse's current status: `invited` or `pending`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the account was created.
</ResponseField>

## Examples

### Basic Account Creation

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://api.fifteenth.com/v1beta/accounts"
  headers = {
      "Authorization": "Bearer 15th_your_api_key_here",
      "Content-Type": "application/json"
  }

  data = {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe"
  }

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

  print(f"Account created: {account['id']}")
  print(f"Login link: {account['login_link']}")
  print(f"Expires at: {account['login_link_expires_at']}")
  ```

  ```javascript JavaScript theme={null}
  const url = 'https://api.fifteenth.com/v1beta/accounts';
  const headers = {
      'Authorization': 'Bearer 15th_your_api_key_here',
      'Content-Type': 'application/json'
  };

  const data = {
      email: 'john.doe@example.com',
      first_name: 'John',
      last_name: 'Doe'
  };

  const response = await fetch(url, {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(data)
  });

  const account = await response.json();

  console.log(`Account created: ${account.id}`);
  console.log(`Login link: ${account.login_link}`);
  console.log(`Expires at: ${account.login_link_expires_at}`);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.fifteenth.com/v1beta/accounts" \
    -H "Authorization: Bearer 15th_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe"
    }'
  ```
</CodeGroup>

### Account with Spouse

<CodeGroup>
  ```python Python theme={null}
  data = {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "spouse": {
          "email": "jane.doe@example.com",
          "first_name": "Jane",
          "last_name": "Doe",
          "send_invitation": True
      }
  }

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

  print(f"Account created: {account['id']}")
  print(f"Primary login: {account['login_link']}")
  if account.get('spouse'):
      print(f"Spouse login: {account['spouse']['login_link']}")
      print(f"Spouse status: {account['spouse']['status']}")
  ```

  ```javascript JavaScript theme={null}
  const data = {
      email: 'john.doe@example.com',
      first_name: 'John',
      last_name: 'Doe',
      spouse: {
          email: 'jane.doe@example.com',
          first_name: 'Jane',
          last_name: 'Doe',
          send_invitation: true
      }
  };

  const response = await fetch(url, {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(data)
  });

  const account = await response.json();

  console.log(`Account created: ${account.id}`);
  console.log(`Primary login: ${account.login_link}`);
  if (account.spouse) {
      console.log(`Spouse login: ${account.spouse.login_link}`);
      console.log(`Spouse status: ${account.spouse.status}`);
  }
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.fifteenth.com/v1beta/accounts" \
    -H "Authorization: Bearer 15th_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "spouse": {
        "email": "jane.doe@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "send_invitation": true
      }
    }'
  ```
</CodeGroup>

## Response Examples

### Successful Account Creation

```json Response theme={null}
{
  "id": 12345,
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "status": "active",
  "login_link": "https://app.fifteenth.com/auth/partner-login/tk_A7xM9pQ2vK8xLqR4S",
  "login_link_expires_at": "2024-01-22T10:30:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Account with Spouse Response

```json Response (With Spouse) theme={null}
{
  "id": 67890,
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "status": "active",
  "login_link": "https://app.fifteenth.com/auth/partner-login/tk_P7sT0zQ2wU4oM7yN",
  "login_link_expires_at": "2024-01-22T10:30:00Z",
  "spouse": {
    "id": 67891,
    "email": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "login_link": "https://app.fifteenth.com/auth/user-login/tk_R9uV2BS4yW6qO9AP",
    "login_link_expires_at": "2024-01-22T10:30:00Z",
    "status": "invited"
  },
  "created_at": "2024-01-15T10:30:00Z"
}
```

## Error Responses

<ResponseField name="400 Bad Request" type="object">
  Invalid request data or missing required fields.

  ```json theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid request data",
      "details": {
        "email": ["Invalid email format"],
        "tax_year": ["Must be between 2020 and 2025"]
      }
    }
  }
  ```
</ResponseField>

<ResponseField name="409 Conflict" type="object">
  Account with the same email already exists.

  ```json theme={null}
  {
    "error": {
      "code": "DUPLICATE_EMAIL",
      "message": "An account with this email already exists",
      "details": {
        "email": "john.doe@example.com",
        "existing_account_id": 12345
      }
    }
  }
  ```
</ResponseField>

<ResponseField name="429 Too Many Requests" type="object">
  Rate limit exceeded.

  ```json theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded. Please retry after 60 seconds.",
      "details": {
        "limit": 100,
        "window_seconds": 60,
        "reset_at": "2024-01-15T10:31:00Z"
      }
    }
  }
  ```
</ResponseField>

## Usage Notes

### Login Link Security

<Warning>
  The login link provides full access to the client's tax account. Handle it securely:

  * Transmit via secure channels only (encrypted email, secure portal)
  * Do not log or store login links in plain text
  * Advise clients not to share the link
  * Link expires automatically after 7 days
</Warning>

### Email Management Best Practices

* Ensure email addresses are accurate and monitored
* Use unique email addresses for each account
* Consider using client's primary business email
* Email will be used for account recovery and important notifications

### Account Type Implications

| Account Type   | Tax Forms               | Typical Use Case                       |
| -------------- | ----------------------- | -------------------------------------- |
| `individual`   | 1040, schedules         | Personal tax returns                   |
| `business`     | 1120, 1120S, 1065, 1041 | Corporate, partnership, S-Corp returns |
| `trust_estate` | 1041, 706               | Trust and estate tax planning          |

## Next Steps

After creating an account:

1. **Send login link to client** via secure communication
2. **Monitor account status** using [Retrieve Account](/endpoints/accounts/retrieve)
3. **Upload initial documents** using [Document Upload](/endpoints/documents/upload)
4. **Track project progress** using [Project Status](/endpoints/projects/status)

## Usage Notes

### Spouse Functionality

When including spouse information during account creation:

* **Full Access**: Spouses automatically receive full account access equivalent to the primary account holder
* **Separate Login**: Each spouse gets their own login link and credentials
* **Invitation Control**: Set `send_invitation: false` to add spouse without immediately sending access
* **One Spouse Only**: Only one spouse per account is supported
* **Joint Returns**: Ideal for married filing jointly tax situations

### Best Practices

<AccordionGroup>
  <Accordion title="Email Verification">
    Ensure both primary and spouse email addresses are correct, as they will receive sensitive tax information.
  </Accordion>

  <Accordion title="Account Types">
    * Use `individual` for personal tax returns (1040)
    * Use `business` for business entities
    * Include spouse information primarily for individual accounts
  </Accordion>

  <Accordion title="Login Management">
    Both the primary account holder and spouse will receive separate login links that expire in 7 days. Use the Generate Login Link endpoint to create new links as needed.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Retrieve Account" icon="user" href="/endpoints/accounts/retrieve">
    Get account details and current status
  </Card>

  <Card title="Upload Documents" icon="file-arrow-up" href="/endpoints/documents/upload">
    Upload tax documents for the account
  </Card>

  <Card title="Account Details" icon="user" href="/endpoints/accounts/retrieve">
    Retrieve complete account information
  </Card>

  <Card title="Generate Login Link" icon="link" href="/endpoints/accounts/login-link">
    Generate new login links if needed
  </Card>
</CardGroup>