Accounts

Manage FiscalAPI accounts. Each account receives an API key for authenticating subsequent requests.

Create an account

POST /v1/accounts

Creates a new account and generates the first API key (test environment). This is a public endpoint -- no authentication required.

Request body

Field	Type	Required	Description
name	string	Yes	Account display name (1-100 chars)
billing_email	string	Yes	Billing contact email (must be unique)

Example

curl -X POST https://api.fiscalapi.com/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "billing_email": "admin@acme.com"
  }'

Response 201 Created

{
  "account": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Acme Corp",
    "billing_email": "admin@acme.com",
    "status": "active",
    "created_at": "2026-03-08T12:00:00Z"
  },
  "api_key": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "key_prefix": "fsk_test_",
    "key": "fsk_test_abc123def456...",
    "environment": "test",
    "created_at": "2026-03-08T12:00:00Z"
  }
}

caution

The api_key.key field is returned only on creation. Store it securely -- it cannot be retrieved again.

Errors

Status	Error	Cause
400	Key: 'CreateRequest.Name' Error:Field validation for 'Name' failed on the 'required' tag	Missing name field
400	Key: 'CreateRequest.BillingEmail' Error:Field validation for 'BillingEmail' failed on the 'email' tag	Invalid email format
409	an account with this billing email already exists	Duplicate email

Account object

Field	Type	Description
id	uuid	Unique account identifier
name	string	Account display name
billing_email	string	Billing contact email
status	string	active, suspended, or cancelled
created_at	datetime	Account creation timestamp

API key object

Field	Type	Description
id	uuid	Key identifier
key_prefix	string	Key prefix for identification (e.g., fsk_test_)
key	string	Full plaintext API key (shown once)
environment	string	test or live
created_at	datetime	Key creation timestamp