gRPC API Reference
Complete API documentation for Symmetry Tax Filing Platform gRPC services. Includes both REST-accessible unary methods and gRPC-only streaming methods.
Service Health
Standard gRPC health checking protocol (grpc.health.v1). Health check endpoints are unauthenticated to allow ALB and Kubernetes probes. The aggregated endpoint reports healthy only when all backend services are up.
Synchronous health check. Returns the current health status of a service or the overall server. Used by AWS ALB health checks, Kubernetes liveness/readiness probes, and Envoy health checking.
Leave service empty to check overall server health, or specify a service name like com.symmetry.datagrpc.IngestionService
Streaming health status. The server immediately sends the current status, then sends updates whenever the health status changes. Used by service mesh sidecars for long-lived health monitoring.
grpcurl or a native gRPC client to test it.
grpcurl -plaintext \
-d '{"service": ""}' \
api.symmetryfiling.com:443 \
grpc.health.v1.Health/Watch
Service AgencyCatalogService
---- Identity reads --------------------------------------------------------
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListAgencies
---- Assembled overlay read ------------------------------------------------ Returns the agency plus its filings (with form children), deposits, and enrollments in one call.
---- Overlay component reads ----------------------------------------------
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListAgencyFilings
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListAgencyDeposits
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListAgencyEnrollments
---- Agency receiving-bank coordinates ------------------------------------- The account a deposit is paid TO. Shared, non-tenant reference data: every tenant filing in a jurisdiction credits the same agency account (the paying side -- BankAccount + ACHConfiguration -- is tenant-scoped and encrypted). Keyed by deposit_key (migration 030), matching AgencyDeposit above. The old (jurisdiction, form_type) pair could not express an agency running more than one receiving account -- a state's withholding and unemployment accounts matched it equally -- and DepositNachaAssembler broke the tie by taking whichever row it walked first, which routes a payment to an arbitrary agency account in a file that is well-formed and whose control totals foot. Get/Delete accept EITHER key: deposit_key when set, else the legacy pair, so a caller holding only the old pair can still reach a row that predates the key.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListTaxAgencyBankInfos
Service EntitySearchService
Unified search - returns scored entity IDs Clients should fetch full entities via Get* RPCs (e.g., GetEmployee)
Streaming variant for large result sets
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/SearchStream
Get list of searchable entity types and their fields Useful for UI autocomplete and discovering available search options
Service EntityTableService
--------------------------------------------------------------------------- Address Operations ---------------------------------------------------------------------------
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListAddresses
--------------------------------------------------------------------------- Company Operations ---------------------------------------------------------------------------
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListCompanies
Company Address Operations - creates address AND links to company atomically
--------------------------------------------------------------------------- Employee Operations ---------------------------------------------------------------------------
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListEmployees
Employee Address Operations - creates address AND links to employee atomically
--------------------------------------------------------------------------- Employment Operations ---------------------------------------------------------------------------
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListEmployments
--------------------------------------------------------------------------- WorksiteLocation Operations ---------------------------------------------------------------------------
Restore soft-deleted WorksiteLocation
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListWorksiteLocations
--------------------------------------------------------------------------- PEO (Professional Employer Organization) Operations ---------------------------------------------------------------------------
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListPeos
PEO Address Operations - creates address AND links to PEO atomically
--------------------------------------------------------------------------- ServiceProvider Operations ---------------------------------------------------------------------------
Restore soft-deleted ServiceProvider
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListServiceProviders
ServiceProvider Address Operations - creates address AND links to ServiceProvider atomically
--------------------------------------------------------------------------- Preparer Operations ---------------------------------------------------------------------------
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListPreparers
--------------------------------------------------------------------------- BankAccount Operations ---------------------------------------------------------------------------
Restore soft-deleted BankAccount
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListBankAccounts
--------------------------------------------------------------------------- ACHConfiguration Operations ---------------------------------------------------------------------------
Restore soft-deleted ACHConfiguration
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListACHConfigurations
--------------------------------------------------------------------------- StateTaxAccount Operations (PAF-1420) --------------------------------------------------------------------------- StateTaxAccount uses block-level encryption: account_number is hashed (HMAC-SHA256) for lookup, plaintext lives in encrypted_data_block. ste_tax_code is the canonical FK to libs/reference-data-models TaxDef.uniqueTaxId; tax_type / status are open CMS-vocabulary strings.
Restore soft-deleted StateTaxAccount
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListStateTaxAccounts
--------------------------------------------------------------------------- AgencyData operations (tenant-scoped agency-assigned field values) --------------------------------------------------------------------------- EAV store: one row per (owner, agency, field) value. ListAgencyData with owner_type + owner_id returns the per-owner collection. No PII / encryption.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListAgencyData
---- Reporting agent authorizations (Form 8655) ---------------------------- READ ONLY on this service. The table is append-only: a new grant, a revocation and a restatement are all APPENDS, and they go through data-grpc's IngestReportingAgentAuthorization like any other ingested record. Offering Update/Delete here would imply an in-place edit that must never happen -- authority has to stay evaluable as of the signing date of a return filed while it was in force. ---- Company contacts ------------------------------------------------------ READ ONLY. Writes go through data-grpc's IngestCompanyContact and the ingestion pipeline's dual-write. List/Get return the MASKED contact: the name, email and phone columns hold HMAC-SHA256 hashes, so they are omitted rather than returned -- a hash rendered where a name is expected reads as corrupt data. GetCompanyContactDecrypted is the only path carrying plaintext and requires an audit context.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListCompanyContacts
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListReportingAgentAuthorizations
--------------------------------------------------------------------------- Batch Operations (Client Streaming) ---------------------------------------------------------------------------
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/BatchCreateEntities
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/BatchUpdateEntities
Service PiiAccessAuditService
List PII access audit records for a tenant
Service SyncTrackingService
Get the latest sync tracking record for an entity If entity_type is UNSPECIFIED, looks up by entity_id only
List sync tracking history for an entity (ordered by tracking_id DESC)
List sync tracking for all entities under a company (for SP/PEO multi-company views)
List all pending sync records for a tenant (for monitoring)
List all failed sync records for a tenant (for error analysis)
Service FilingJobService
---- Reads -----------------------------------------------------------------
Runs grouped by period_label with rollup counts + status breakdown, aggregated across tenants.
Per-company rows for a single run (amounts, counts, status, approval stamps).
Flat job query across runs; period_label is the primary scope, the rest are optional filters.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListFilingJobs
Move every PENDING_REVIEW job in the run to APPROVED, skipping ON_HOLD / EXCLUDED. Stamps approved_at/approved_by and writes history per job.
Run-level No-Go: move every PENDING_REVIEW job in the run to ON_HOLD (reversible; filing obligation stays OPEN), skipping APPROVED / ON_HOLD / EXCLUDED. Writes history per job. Like HoldCompany, a review-queue hold has no generation effect, so this does NOT emit Iceberg transitions.
Per-company Go: PENDING_REVIEW -> APPROVED.
PENDING_REVIEW -> ON_HOLD (reversible; filing obligation stays OPEN).
PENDING_REVIEW / ON_HOLD -> EXCLUDED. reason_code is REQUIRED; obligation becomes CLOSED for the run.
EXCLUDED -> PENDING_REVIEW (explicit, audited reversal).
APPROVED -> PENDING_REVIEW, allowed only while the job is not yet claimed (not PROCESSING).
Insert run-scoped record exclusions (does NOT change job status; the company still generates, minus the excluded records).
Read active record exclusions for a run (optionally one company).
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/ListRecordExclusions
Soft un-exclude (active = false).
Service IngestionService
High-level API for typed data ingestion. Accepts raw payroll data (employees, companies, tax liabilities, etc.) and streams them to Kinesis for processing. Unary methods are accessible via REST/JSON, streaming methods are gRPC-only.
Stream employee records for bulk ingestion. Accepts a client stream of employee records and returns an aggregate response with success/failure counts.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestEmployees
Stream company records for bulk ingestion. Accepts a client stream of company records and returns an aggregate response.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestCompanies
Stream tax liability records for bulk ingestion. Accepts a client stream of liability records and returns an aggregate response.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestTaxLiabilities
Stream applied-benefit records for bulk ingestion (PAF-1820). One record per (employee, pay_date, jurisdiction, wage_type, benefit_category) — the producer sums its own individual benefits into a category before sending, because the natural key excludes the reference code and two rows sharing a category would otherwise collapse under latest-wins.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestAppliedBenefits
Stream employment relationship records for bulk ingestion.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestEmployments
Stream bank account records for bulk ingestion.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestBankAccounts
Stream tax preparer records for bulk ingestion.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestPreparers
Stream state tax account records for bulk ingestion.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestStateTaxAccounts
Stream company tax profile records for bulk ingestion (PAF-1616, append-only).
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestCompanyTaxProfiles
Stream tenant schedule config records for bulk ingestion (PAF-1921, append-only).
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestTenantScheduleConfigs
Stream tax exemption records for bulk ingestion (PAF-1616, append-only).
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestTaxExemptions
Stream correction declarations — a producer stating that liabilities restate a FILED period. Append-only; correlated to tax_liability by a composite natural key on scope, never a foreign key, so a declaration may arrive before, after, or without its rows.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestTaxCorrections
Stream Form 8655 authority grants. Append-only: a revocation is a new version carrying revoked_at, never a delete, because authority must stay evaluable as of the signing date of a return filed while it was in force.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestReportingAgentAuthorizations
Stream deposits made against a tax obligation, by us or by the client (PAF-1765). Append-only and origination-agnostic; a settlement confirmation arrives as a NEW ROW reusing deposit_id with an advanced status, never as an update.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestTaxDeposits
Stream the AGENCY's own statements about a filer's credits (PAF-1913). The third corner of the reconciliation: tax_liability is our computation, tax_deposit is the client's assertion, and this is what the agency says it holds. Append-only; a restatement reuses credit_id with a later stated_at. Replaces DepositAdjustment, which never had a producer.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestAgencyCredits
Stream the agency's allocations of deposits (PAF-1913). The other half of the third corner: AgencyCredit is money the agency HOLDS, this is money it APPLIED. One deposit fans out to many of these, which is why it cannot be a field on TaxDeposit. Append-only; a re-allocation reuses application_id with a later stated_at.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestPaymentApplications
Stream company contact records for bulk ingestion (PAF-1606, Iceberg-only).
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestCompanyContacts
Stream employee tax profile records for bulk ingestion (PAF-1606, Iceberg-only).
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestEmployeeTaxProfiles
Stream employee tax exemption records for bulk ingestion (PAF-1606, Iceberg-only).
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestEmployeeTaxExemptions
Stream PEO (Professional Employer Organization) records for bulk ingestion.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestPEOs
Stream service provider records for bulk ingestion.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestServiceProviders
Stream address records for bulk ingestion.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestAddresses
Stream worksite location records for bulk ingestion.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestWorksiteLocations
Stream ACH configuration records for bulk ingestion.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestAchConfigurations
Stream agency-data records (agency-assigned EAV field values) for bulk ingestion. No PII. owner_id is expected to be the server-issued UUID7 (the batch client resolves owner_external_id -> owner_id before staging, same as bank_accounts/preparers); a non-UUID7 owner_id is logged but not rejected.
grpcurl or a native gRPC client to test it.
grpcurl -H "Authorization: Bearer $TOKEN" \
-d '{ }' \
api.symmetryfiling.com:443 \
com.symmetry.datagrpc.IngestionService/IngestAgencyDatas
Ingest a batch of mixed record types in a single request. Supports multiple entity types: employees, companies, tax liabilities, etc.
Ingest a single employee record with PII data (SSN, name, DOB, addresses).
Ingest a single company record with EIN and legal entity details.
Ingest a single PayCalc submission: one tax-calculation API call covering N employees. This is the protection boundary for exported calculations. The submission arrives with plaintext payloads and leaves as a protected envelope on the PayCalc stream, plus derived tax liabilities on the entity ingestion path. It is the only place payload plaintext meets key material — the producer holds plaintext without keys, and everything downstream holds protection's output without plaintext. Unlike the entity RPCs this one performs derivation as well as protection, because deriving tax liabilities requires reading the payload. Doing it anywhere downstream would mean shipping plaintext past this point, which is the thing the design exists to prevent. Unary only, deliberately: a submission is already a batch of N employees, so client-streaming would batch batches for no benefit while making partial failure harder to report.
Ingest a single tax preparer record.
Ingest a single bank account record with routing and account numbers.
Ingest a single employment relationship record.
Ingest a single PEO (Professional Employer Organization) record.
Ingest a single service provider record.
Ingest a single state tax account record.
Ingest a single correction declaration (append-only).
Ingest a single Form 8655 authority grant (append-only). One call per GRANTED FORM -- line 15 grants per-form start periods, so one signed instrument yields several of these.
Ingest a single agency credit statement (append-only). The REST/portal door — a person reading an agency notice keys it here; batch uses IngestAgencyCredits.
Ingest a single payment application (append-only). How the agency allocated one deposit to one (period, tax); batch uses IngestPaymentApplications.
Ingest a single deposit (append-only). The REST/dev-UI door; batch uses IngestTaxDeposits.
Ingest a single company tax profile record (PAF-1616, append-only).
Ingest a single tenant schedule config record (PAF-1921, append-only).
Ingest a single tax exemption record (PAF-1616, append-only).
Ingest a single company contact record (PAF-1606, Iceberg-only).
Ingest a single employee tax profile record (PAF-1606, Iceberg-only).
Ingest a single employee tax exemption record (PAF-1606, Iceberg-only).
Ingest a single address record.
Ingest a single worksite location record.
Ingest a single ACH configuration record.
Ingest a single agency-data record (agency-assigned field value). No PII.
Ingest a single filing-job lifecycle transition (scheduler merge). No PII. Append-only event; entity-grpc owns the local-first PG overlay write, this forwards the event to the data lake (Kinesis -> ingestion-stream -> Iceberg).
Insert a single tax liability record. Tax liabilities are insert-only (immutable) - use this for payroll-generated tax obligations.
Insert a single applied-benefit record. Append-only, like tax liabilities.
Delete a record by entity type and ID. Creates a tombstone record in Iceberg for soft delete semantics.
Service ReportingQueryService
======================================================================================= ReportingQueryService — interactive, row-capped, synchronous. ======================================================================================= Bounded by MAX_INTERACTIVE_ROWS and by the workgroup's bytes-scanned cutoff. Anything larger needs narrowing by the caller. A result that hits the cap sets QueryResult.truncated silently returning a prefix, because a truncated reconciliation is not a smaller answer — it is a different one.
Surface 1: named, parameterised templates. The server owns the SQL.