Data Retrieval API
After a session is completed, you can retrieve the submitted form data and download the generated PDF document.
Get Session Data
Retrieves the completed form data for a session.
Endpoint: GET /v1/sessions/:id/data
Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| id | string | The session ID |
Example Request
curl https://api.ezy-forms.com.au/v1/sessions/sess_abc123xyz/data \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"session_id": "sess_abc123xyz",
"form_type": "financial_statement",
"status": "completed",
"submitted_at": "2024-01-16T14:22:00Z",
"data": {
"personal_details": {
"full_name": "John Smith",
"date_of_birth": "1985-03-15",
"occupation": "Software Engineer",
"employer": "Tech Corp Pty Ltd",
"address": {
"street": "123 Main Street",
"suburb": "Sydney",
"state": "NSW",
"postcode": "2000"
},
"phone": "0412345678",
"email": "[email protected]"
},
"income": {
"employment_income": {
"gross_salary": 120000,
"bonuses": 10000,
"allowances": 5000
},
"other_income": {
"rental_income": 15000,
"dividends": 2000,
"interest": 500
},
"total_gross_income": 152500
},
"assets": {
"real_property": [
{
"description": "Family home",
"address": "123 Main Street, Sydney NSW 2000",
"ownership": "joint",
"ownership_percentage": 50,
"current_value": 1500000,
"mortgage_owing": 450000,
"net_value": 525000
}
],
"vehicles": [
{
"description": "2022 Toyota Camry",
"value": 35000,
"amount_owing": 15000
}
],
"bank_accounts": [
{
"institution": "Commonwealth Bank",
"account_type": "savings",
"balance": 25000
},
{
"institution": "Westpac",
"account_type": "everyday",
"balance": 5000
}
],
"superannuation": [
{
"fund_name": "Australian Super",
"balance": 180000
}
],
"investments": [
{
"description": "Share portfolio",
"value": 50000
}
],
"total_assets": 1015000
},
"liabilities": {
"mortgages": [
{
"lender": "Commonwealth Bank",
"property": "123 Main Street, Sydney NSW 2000",
"balance": 450000,
"monthly_repayment": 2500
}
],
"personal_loans": [
{
"lender": "ANZ",
"purpose": "Car loan",
"balance": 15000,
"monthly_repayment": 450
}
],
"credit_cards": [
{
"issuer": "Commonwealth Bank",
"limit": 10000,
"balance": 3000
}
],
"other_liabilities": [],
"total_liabilities": 468000
},
"expenses": {
"housing": {
"mortgage_rent": 2500,
"utilities": 350,
"insurance": 200,
"rates": 250
},
"transport": {
"car_loan": 450,
"fuel": 200,
"registration_insurance": 150
},
"living": {
"groceries": 800,
"clothing": 150,
"medical": 100,
"entertainment": 300
},
"total_monthly_expenses": 5450
},
"summary": {
"total_assets": 1015000,
"total_liabilities": 468000,
"net_worth": 547000,
"total_monthly_income": 12708,
"total_monthly_expenses": 5450,
"monthly_surplus": 7258
}
}
}
Errors
| Code | Status | Description |
|------|--------|-------------|
| session_not_found | 404 | The session does not exist |
| session_not_completed | 400 | The session has not been completed yet |
Download PDF
Downloads the generated PDF document for a completed session.
Endpoint: GET /v1/sessions/:id/pdf
Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| id | string | The session ID |
Query Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| download | boolean | If true, returns as attachment. Default: false (inline) |
Example Request
# Download as file
curl https://api.ezy-forms.com.au/v1/sessions/sess_abc123xyz/pdf?download=true \
-H "Authorization: Bearer YOUR_API_KEY" \
--output financial_statement.pdf
# View inline (for browser display)
curl https://api.ezy-forms.com.au/v1/sessions/sess_abc123xyz/pdf \
-H "Authorization: Bearer YOUR_API_KEY"
Response
Returns the PDF file with appropriate headers:
Content-Type: application/pdf
Content-Disposition: attachment; filename="financial_statement_sess_abc123xyz.pdf"
Content-Length: 125432
Errors
| Code | Status | Description |
|------|--------|-------------|
| session_not_found | 404 | The session does not exist |
| session_not_completed | 400 | The session has not been completed yet |
| pdf_not_ready | 202 | PDF is still being generated (retry in a few seconds) |
Data Format
Dates
All dates are returned in ISO 8601 format:
2024-01-15T10:30:00Z
Date-only fields (like date of birth) use the format:
1985-03-15
Currency Values
All monetary values are returned as integers representing cents (or the smallest currency unit):
{
"gross_salary": 12000000 // $120,000.00
}
Or as decimal numbers when appropriate:
{
"gross_salary": 120000.00
}
Ownership Percentages
Ownership percentages are returned as integers (0-100):
{
"ownership_percentage": 50 // 50%
}
Webhooks for Data
When form data is ready, you'll receive a webhook:
{
"event": "session.completed",
"session_id": "sess_abc123xyz",
"timestamp": "2024-01-16T14:22:00Z",
"data": {
"status": "completed",
"completed_at": "2024-01-16T14:22:00Z"
}
}
When the PDF is generated:
{
"event": "session.pdf_ready",
"session_id": "sess_abc123xyz",
"timestamp": "2024-01-16T14:22:30Z"
}
See Webhooks for more details.
Best Practices
Handling Large Data
Form data can be substantial. Consider:
- Storing data in your database rather than fetching on demand
- Processing data asynchronously after webhook receipt
- Using pagination if you're processing multiple sessions
PDF Storage
PDFs are retained for 90 days after session completion. After that:
- PDFs are automatically deleted
- Download requests will return
404 - Store PDFs in your own storage if long-term retention is needed
Data Privacy
Remember that form data contains sensitive financial information:
- Encrypt data at rest
- Use HTTPS for all API calls
- Limit access to authorized personnel
- Follow applicable privacy regulations