Skip to main content
POST
https://api.fifteenth.com
/
v1beta
/
accounts
Create Account
curl --request POST \
  --url https://api.fifteenth.com/v1beta/accounts \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "email": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "spouse": {
    "spouse.email": "<string>",
    "spouse.first_name": "<string>",
    "spouse.last_name": "<string>",
    "spouse.send_invitation": true
  }
}
'
{
  "id": 123,
  "status": "<string>",
  "login_link": "<string>",
  "login_link_expires_at": "<string>",
  "spouse": {
    "spouse.id": 123,
    "spouse.email": "<string>",
    "spouse.first_name": "<string>",
    "spouse.last_name": "<string>",
    "spouse.login_link": "<string>",
    "spouse.login_link_expires_at": "<string>",
    "spouse.status": "<string>"
  },
  "created_at": "<string>",
  "400 Bad Request": {},
  "409 Conflict": {},
  "429 Too Many Requests": {}
}

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

​
Request

​
Headers

​
Authorization
string
required
Bearer token with your Partner API key
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
email
string
required
Client’s primary email address for communication and account access.Validation: Must be valid email format
Example: [email protected]
​
first_name
string
required
Client’s first name as it appears on tax documents.Format: Max 50 characters
Example: John
​
last_name
string
required
Client’s last name as it appears on tax documents.Format: Max 50 characters
Example: Doe
​
spouse
object
Optional spouse information. If provided, the spouse will have full account access equivalent to the primary account holder.

​
Response

​
Success Response

​
id
number
Unique Fifteenth account identifier.
​
status
string
Current account status. Always active for newly created accounts.
​
login_link
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
​
login_link_expires_at
string
ISO 8601 timestamp when the login link expires.
​
spouse
object
Spouse information and access details (if spouse was provided in request).
​
created_at
string
ISO 8601 timestamp when the account was created.

​
Examples

​
Basic Account Creation

import requests

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

data = {
    "email": "[email protected]",
    "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']}")

​
Account with Spouse

data = {
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "spouse": {
        "email": "[email protected]",
        "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']}")

​
Response Examples

​
Successful Account Creation

Response
{
  "id": 12345,
  "email": "[email protected]",
  "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

Response (With Spouse)
{
  "id": 67890,
  "email": "[email protected]",
  "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": "[email protected]",
    "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

​
400 Bad Request
object
Invalid request data or missing required fields.
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "email": ["Invalid email format"],
      "tax_year": ["Must be between 2020 and 2025"]
    }
  }
}
​
409 Conflict
object
Account with the same email already exists.
{
  "error": {
    "code": "DUPLICATE_EMAIL",
    "message": "An account with this email already exists",
    "details": {
      "email": "[email protected]",
      "existing_account_id": 12345
    }
  }
}
​
429 Too Many Requests
object
Rate limit exceeded.
{
  "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"
    }
  }
}

​
Usage Notes

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

​
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 TypeTax FormsTypical Use Case
individual1040, schedulesPersonal tax returns
business1120, 1120S, 1065, 1041Corporate, partnership, S-Corp returns
trust_estate1041, 706Trust 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
  3. Upload initial documents using Document Upload
  4. Track project progress using Project 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

Ensure both primary and spouse email addresses are correct, as they will receive sensitive tax information.
  • Use individual for personal tax returns (1040)
  • Use business for business entities
  • Include spouse information primarily for individual accounts
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.

Retrieve Account

Get account details and current status

Upload Documents

Upload tax documents for the account

Account Details

Retrieve complete account information

Generate Login Link

Generate new login links if needed