Employers resource — Beeswax STP help

Overview

An Employer represents the entity lodging pay events with the ATO — typically one per ABN. You need at least one Employer before you can add employees or create pay events.

The Employer object

Fields

Field	Type	Notes
`id`	integer	Beeswax's internal ID, used everywhere else in the API
`legal_name`	string	Required. Registered business name
`trading_name`	string	Optional. If set, used for `display_name`
`display_name`	string	Computed. `trading_name
`abn`	string	Required. 11 digits, no spaces
`formatted_abn`	string	Computed. ABN with spaces ("51 824 753 556")
`branch_number`	integer	Required. Defaults to 1. Must be a positive integer
`bms_id`	string	Business Management System ID — your software's unique identifier for this employer
`environment`	string	Required. `evte` for test, `production` for live
`active`	boolean	Whether this employer is active (inactive employers are hidden by default)
`stp_configured`	boolean	Computed. True if the employer has valid M2M credentials uploaded
`employee_count`	integer	Computed. Current number of active employees
`contact_name`	string	Optional
`contact_phone`	string	Optional
`contact_email`	string	Optional — must be a valid email if set
`address_line_1`	string	Optional
`address_line_2`	string	Optional
`suburb`	string	Optional
`state`	string	Optional. Must be one of `ACT`, `NSW`, `NT`, `QLD`, `SA`, `TAS`, `VIC`, `WA`
`postcode`	string	Optional. 4 digits
`address`	string	Computed. Full address as a single line
`credential_id`	string	ATO M2M credential ID (set via Settings → STP Config for live)
`keystore_path`	string	Path to keystore file on our infrastructure
`software_id`	string	ATO-assigned software ID
`software_subscription_id`	string	Computed on create. 11-character Software Subscription ID required by the ATO DSP framework from 30 June 2026. Notify this to the ATO via Access Manager.
`auto_lodge`	boolean	Whether to automatically submit new pay events
`self_verify`	boolean	Whether to run self-verification before submission
`created_at`	string (ISO 8601)
`updated_at`	string (ISO 8601)

Environment isolation

Test tokens (stp_test_...) only see employers with environment: "evte". Live tokens only see environment: "production". Creating an employer with the wrong environment for your token results in a successfully-created record that's invisible to the API until you switch tokens. See Environments.

Endpoints

List employers

GET /api/v1/employers

Scopes: employers:read

Query parameters:

Param	Default	Notes
`page`	1	See Pagination
`per_page`	25	Max 100

Response: 200 OK, array of Employer objects (compact fields only — no address or contact details).

curl https://stp.beeswaxapp.com/api/v1/employers \
  -H "Authorization: Bearer stp_test_..."

[
  {
    "id": 12,
    "legal_name": "Acme Pty Ltd",
    "trading_name": "Acme",
    "display_name": "Acme",
    "abn": "51824753556",
    "formatted_abn": "51 824 753 556",
    "branch_number": 1,
    "environment": "evte",
    "active": true,
    "stp_configured": false,
    "employee_count": 3,
    "created_at": "2026-04-09T11:32:05Z",
    "updated_at": "2026-04-09T11:32:05Z"
  }
]

Get an employer

GET /api/v1/employers/:id

Scopes: employers:read

Response: 200 OK, a single Employer object with full detail fields (contact, address, STP config).

curl https://stp.beeswaxapp.com/api/v1/employers/12 \
  -H "Authorization: Bearer stp_test_..."

Create an employer

POST /api/v1/employers

Scopes: employers:write

Idempotent: yes — set Idempotency-Key header to safely retry

Body:

{
  "employer": {
    "legal_name": "Acme Pty Ltd",
    "trading_name": "Acme",
    "abn": "51824753556",
    "branch_number": 1,
    "bms_id": "acme-001",
    "contact_name": "Finance",
    "contact_email": "finance@acme.example",
    "address_line_1": "Level 3, 100 Market Street",
    "suburb": "Sydney",
    "state": "NSW",
    "postcode": "2000",
    "environment": "evte"
  }
}

Response: 201 Created with the full Employer object.

Validation errors: 422 Unprocessable Entity

{
  "error": "Validation Failed",
  "message": [
    "Abn must be 11 digits",
    "Branch number must be greater than 0"
  ]
}

Already-exists collision: if the (abn, branch_number) pair is already taken by one of your own employers, the 422 body includes a code and the existing record's ID so you can recover without a second GET:

{
  "error": "Validation Failed",
  "code": "employer_already_exists",
  "message": ["Abn and branch number combination already exists"],
  "existing_employer_id": 4821
}

The ID is only surfaced when the existing employer is visible to the calling token (i.e. owned by the same user, in the same environment, and — for platform tokens — the one named by X-On-Behalf-Of-Employer). Collisions against records the caller can't see return the plain validation shape with no ID.

Update an employer

PATCH /api/v1/employers/:id

Scopes: employers:write

Idempotent: yes

Body: any subset of the Employer fields.

{
  "employer": {
    "trading_name": "Acme Group",
    "contact_email": "new-finance@acme.example"
  }
}

Response: 200 OK with the full updated Employer object.

Employer-scoped sub-resources

/employers/:id/employees — employee records under this employer
/employers/:id/employer_delegates — delegated access (web UI only, not yet available via API)

Validation rules

abn — must be exactly 11 digits. We don't yet run the ABN checksum validation; that's on the roadmap. For now, garbage-in ABNs will fail at ATO submission time.
branch_number — must be a positive integer. Most employers use 1. Multi-branch arrangements use higher numbers per the ATO's instructions.
state — must be a valid Australian state or territory code, or blank.
postcode — must be 4 digits, or blank.
contact_email — must be a valid email format, or blank.
(abn, branch_number) — this combination must be unique within your account. You can't have two employers with the same ABN + branch.

Deleting / deactivating an employer

DELETE /api/v1/employers/:id

Scopes: employers:write

Deactivates the employer (active: false) and scrubs personally identifying employee data — TFN, email, and address fields are set to NULL on every employee. Employment end dates are stamped if not already set.

ATO record retention is preserved. Pay events, submissions, and YTD rows are kept for 5 financial years from lodgement per ATO record-keeping rules (see retention_expires_on in the response). They remain visible in the audit log and the admin UI but drop out of the default API listing.

curl https://stp.beeswaxapp.com/api/v1/employers/12 \
  -X DELETE \
  -H "Authorization: Bearer stp_live_..."

Response: 200 OK

{
  "status": "deactivated",
  "employer_id": 12,
  "message": "Employer deactivated and employee PII scrubbed. ATO-required records (pay events, submissions, YTD) retained for 5 financial years per ATO record-keeping rules.",
  "retention_expires_on": "2031-10-16"
}

Soft deactivation without PII scrub

If you want to stop using the employer but keep their employee data (e.g. temporary suspension), PATCH active: false instead — no PII is touched:

{ "employer": { "active": false } }

Full physical erasure

After the 5-year retention window expires, physical erasure is triggered via the admin-only ErasureJob. This is intentionally not exposed on the public API — ATO/OSF auditors need to see that 5-year retention is hard-enforced at the API layer, not customer-controllable.

Transferring ownership

To move an employer to another user's Beeswax STP account, use the Employer Transfer flow in the web UI. This triggers an email invitation to the recipient and moves all associated employees, pay events, and YTD data. Not currently available via API.

Common tasks

Find an employer by ABN

There's no dedicated endpoint for this yet. List employers and filter client-side:

curl "https://stp.beeswaxapp.com/api/v1/employers?per_page=100" \
  -H "Authorization: Bearer stp_test_..." \
  | jq '.[] | select(.abn == "51824753556")'

Bulk-create employers

There's no bulk endpoint. Send POST requests one at a time. At 120 req/min on the live tier, you can create 7,000+ employers per hour.

Use an idempotency key per employer so retries don't create duplicates:

for abn in 51824753556 98765432109; do
  curl https://stp.beeswaxapp.com/api/v1/employers \
    -X POST \
    -H "Authorization: Bearer stp_live_..." \
    -H "Idempotency-Key: employer-$abn" \
    -H "Content-Type: application/json" \
    -d "{ \"employer\": { \"legal_name\": \"...\", \"abn\": \"$abn\", \"environment\": \"production\" } }"
done