Sessions API

Sessions represent individual financial statement collection requests. Each session generates a unique link that your customer uses to complete their form.

The Session Object

{
  "id": "sess_abc123xyz",
  "status": "pending",
  "form_type": "financial_statement",
  "customer_email": "[email protected]",
  "customer_name": "John Smith",
  "reference_id": "case-12345",
  "session_url": "https://ezy-forms.com.au/s/abc123xyz",
  "webhook_url": "https://yourapp.com/webhooks",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-02-14T10:30:00Z",
  "accessed_at": null,
  "completed_at": null
}

Attributes

| Attribute | Type | Description | |-----------|------|-------------| | id | string | Unique identifier for the session | | status | string | Current status: pending, in_progress, completed, expired, cancelled | | form_type | string | Type of form: financial_statement | | customer_email | string | Customer's email address | | customer_name | string | Customer's full name | | reference_id | string | Your internal reference ID | | session_url | string | URL for customer to access the form | | webhook_url | string | URL to receive webhook events | | created_at | datetime | When the session was created | | expires_at | datetime | When the session expires | | accessed_at | datetime | When the customer first accessed the form | | completed_at | datetime | When the form was completed |

Status Lifecycle

pending → in_progress → completed
    ↓          ↓
 expired   cancelled

Create a Session

Creates a new session for collecting a financial statement.

Endpoint: POST /v1/sessions

Request Body

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | form_type | string | Yes | Type of form to collect. Currently only financial_statement | | customer_email | string | Yes | Email address of the customer | | customer_name | string | No | Customer's full name | | reference_id | string | No | Your internal reference ID for this session | | webhook_url | string | No | URL to receive webhook events | | expires_in_days | integer | No | Days until expiration (default: 30, max: 90) | | metadata | object | No | Custom key-value data (max 10 keys, 500 chars per value) |

Example Request

curl -X POST https://api.ezy-forms.com.au/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "form_type": "financial_statement",
    "customer_email": "[email protected]",
    "customer_name": "John Smith",
    "reference_id": "case-12345",
    "webhook_url": "https://yourapp.com/webhooks/ezyfamily",
    "expires_in_days": 14,
    "metadata": {
      "case_type": "family_law",
      "assigned_to": "lawyer-456"
    }
  }'

Response

{
  "id": "sess_abc123xyz",
  "status": "pending",
  "form_type": "financial_statement",
  "customer_email": "[email protected]",
  "customer_name": "John Smith",
  "reference_id": "case-12345",
  "session_url": "https://ezy-forms.com.au/s/abc123xyz",
  "webhook_url": "https://yourapp.com/webhooks/ezyfamily",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-29T10:30:00Z",
  "metadata": {
    "case_type": "family_law",
    "assigned_to": "lawyer-456"
  }
}

Status Code: 201 Created

List Sessions

Retrieves a list of all sessions for your account.

Endpoint: GET /v1/sessions

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | page | integer | Page number (default: 1) | | per_page | integer | Items per page (default: 20, max: 100) | | status | string | Filter by status: pending, in_progress, completed, expired, cancelled | | reference_id | string | Filter by your reference ID | | customer_email | string | Filter by customer email | | created_after | datetime | Filter sessions created after this date | | created_before | datetime | Filter sessions created before this date |

Example Request

curl "https://api.ezy-forms.com.au/v1/sessions?status=completed&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "sess_abc123xyz",
      "status": "completed",
      "form_type": "financial_statement",
      "customer_email": "[email protected]",
      "customer_name": "John Smith",
      "reference_id": "case-12345",
      "created_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-16T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 45,
    "total_pages": 5
  }
}

Get a Session

Retrieves details of a specific session.

Endpoint: GET /v1/sessions/:id

Path Parameters

| Parameter | Type | Description | |-----------|------|-------------| | id | string | The session ID |

Example Request

curl https://api.ezy-forms.com.au/v1/sessions/sess_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "sess_abc123xyz",
  "status": "in_progress",
  "form_type": "financial_statement",
  "customer_email": "[email protected]",
  "customer_name": "John Smith",
  "reference_id": "case-12345",
  "session_url": "https://ezy-forms.com.au/s/abc123xyz",
  "webhook_url": "https://yourapp.com/webhooks/ezyfamily",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-02-14T10:30:00Z",
  "accessed_at": "2024-01-15T11:00:00Z",
  "completed_at": null,
  "progress": {
    "sections_completed": 3,
    "sections_total": 7,
    "percentage": 43
  }
}

Cancel a Session

Cancels a pending or in-progress session. Completed sessions cannot be cancelled.

Endpoint: DELETE /v1/sessions/:id

Path Parameters

| Parameter | Type | Description | |-----------|------|-------------| | id | string | The session ID |

Example Request

curl -X DELETE https://api.ezy-forms.com.au/v1/sessions/sess_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "sess_abc123xyz",
  "status": "cancelled",
  "cancelled_at": "2024-01-15T12:00:00Z"
}

Status Code: 200 OK

Errors

| Code | Description | |------|-------------| | 404 | Session not found | | 409 | Session already completed or cancelled |

Session Errors

| Error Code | Description | |------------|-------------| | invalid_form_type | The specified form type is not supported | | invalid_email | The customer email address is invalid | | session_not_found | The session does not exist | | session_expired | The session has expired | | session_completed | Operation not allowed on completed sessions | | session_cancelled | Operation not allowed on cancelled sessions |