Create Account - Fifteenth Partner API

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": {}
}

POST

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

string

required

Client’s primary email address for communication and account access.Validation: Must be valid email format
Example: john.doe@example.com

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.

Show spouse object

spouse.email

string

required

Spouse’s email address for login and communications. Validation: Must be valid email format, unique across Fifteenth

spouse.first_name

string

required

Spouse’s first name as it appears on tax documents. Format: Max 50 characters

spouse.last_name

string

required

Spouse’s last name as it appears on tax documents. Format: Max 50 characters

spouse.send_invitation

boolean

Whether to send an invitation email to the spouse. Default: true

Response

Success Response

number

Unique Fifteenth account identifier.

status

string

Current account status. Always active for newly created accounts.

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

ISO 8601 timestamp when the login link expires.

spouse

object

Spouse information and access details (if spouse was provided in request).

Show spouse object

spouse.id

number

Unique spouse user identifier.

spouse.email

string

Spouse’s email address.

spouse.first_name

string

Spouse’s first name.

spouse.last_name

string

Spouse’s last name.

Unique login link for spouse’s first-time access (if invitation sent).

Expiration timestamp for the spouse’s login link.

spouse.status

string

Spouse’s current status: invited or pending.

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": "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']}")

Account with Spouse

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']}")

Response Examples

Successful Account Creation

Response

{
  "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

Response (With Spouse)

{
  "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

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": "john.doe@example.com",
      "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 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:

Send login link to client via secure communication
Monitor account status using Retrieve Account
Upload initial documents using Document Upload
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

Email Verification

Ensure both primary and spouse email addresses are correct, as they will receive sensitive tax information.

Account Types

Use individual for personal tax returns (1040)
Use business for business entities
Include spouse information primarily for individual accounts

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

Health Check Retrieve Account

​Overview

​Request

​Headers

​Body Parameters

​Response

​Success Response

​Examples

​Basic Account Creation

​Account with Spouse

​Response Examples

​Successful Account Creation

​Account with Spouse Response

​Error Responses

​Usage Notes

​Login Link Security

​Email Management Best Practices

​Account Type Implications

​Next Steps

​Usage Notes

​Spouse Functionality

​Best Practices

Retrieve Account

Upload Documents

Account Details

Generate Login Link

Overview

Request

Headers

Body Parameters

Response

Success Response

Examples

Basic Account Creation

Account with Spouse

Response Examples

Successful Account Creation

Account with Spouse Response

Error Responses

Usage Notes

Login Link Security

Email Management Best Practices

Account Type Implications

Next Steps

Usage Notes

Spouse Functionality

Best Practices