retrieveIQ
Sign in Request beta access

Reference

Mutations

Every change the API makes, with the scopes each needs and an example to send. A change to a parcel, a bill or an appeal is recorded in that parcel's activity trail. An error anywhere in a request undoes the whole request.

This page as Markdown

Generated from the API’s schema with every release, so it always matches the API it describes. Each entry shows the scope a key needs for it.

mutationacceptBillNeeds BILL_REVIEW and BILL_READ#

Returns BillReviewPayload!

Accept a bill: NEEDS_REVIEW or DISPUTED becomes VALIDATED, on every installment named or on none. Refused with UNRESOLVED_VALIDATIONS while an ERROR check stands unresolved against any installment of the bill, and with CONFLICT when the bill changed after the version you read (expectedVersion). Name every installment of the bill: its checks are recorded on the first.

Arguments

expectedVersionInt!required

The bill's version as the caller read it (TaxBill.version). If anything about the bill changed since, the call is refused as a CONFLICT (reason STALE_VERSION) and nothing is written.

installmentIds[ID!]!required

The installments of one bill, from TaxBill.installments. One bill per call.

noteString

A note for the activity trail.

Example
graphql
mutation ($expectedVersion: Int!, $installmentIds: [ID!]!) {
  acceptBill(expectedVersion: $expectedVersion, installmentIds: $installmentIds) {
    notVisible
    bill {
      key
      status
      annualTotal
      assessmentYear
      billNumber
    }
  }
}

mutationacknowledgeDeadlineNeeds BILL_REVIEW and PARCEL_READ#

Returns Deadline!

A person marks a saved date as seen and handled. Once per date: a date that later moves is a new date, unacknowledged. BILL_REVIEW, as a decision about a bill; the trail records it with the note.

Arguments

idID!required

The date, by its Deadline id from deadlines.

noteString

What was done about it, for the trail.

Example
graphql
mutation ($id: ID!) {
  acknowledgeDeadline(id: $id) {
    id
    acknowledgedAt
    assessmentYear
    generatedAt
    kind
    on
    qualifier
    source
    parcel {
      id
      parcelNumber
      status
      useCode
    }
    jurisdiction {
      id
      name
      assesses
      billDelivery
      bills
    }
  }
}

mutationclearLegalEntityTaxIdNeeds ADMIN and PARCEL_READ#

Returns LegalEntityPayload!

Remove a legal entity's tax identification number: the encrypted value, its key version and its last four together. The trail records the removal.

Arguments

legalEntityIdID!required

The legal entity, by its id.

Example
graphql
mutation ($legalEntityId: ID!) {
  clearLegalEntityTaxId(legalEntityId: $legalEntityId) {
    legalEntity {
      id
      name
      taxIdLast4
    }
  }
}

mutationcorrectBillNeeds BILL_REVIEW and BILL_READ#

Returns BillReviewPayload!

Correct a reading by hand. The corrected figures become the next revision of the bill, at needs_review like any new reading; the revision they replace is rejected and kept as evidence; the correction is an extraction of its own (engine manual, by the person) and one activity row. Refused before anything is written when the installments do not add up to the charges, so a corrected revision never carries the sum error it was meant to fix. Then checked like any reading (the unit's calendar, the stated total, the prior year): a check that finds an error does not refuse the correction, it withholds the new revision (TaxBill.withheld) until a person resolves the check or corrects the bill again. The checks read the parcel, so an engagement without PARCEL_READ is FORBIDDEN a correction, as it is the inbox. Never an update of a figure in place.

Arguments

correctionBillCorrectionInput!required

The figures as the county shows them: each installment by its id, and the charges when they change.

expectedVersionInt!required

The bill's version as the caller read it (TaxBill.version). If anything about the bill changed since, the call is refused as a CONFLICT (reason STALE_VERSION) and nothing is written.

noteString!required

What the county shows, for the trail and the next reader.

Example
graphql
mutation ($correction: BillCorrectionInput!, $expectedVersion: Int!, $note: String!) {
  correctBill(
    correction: $correction
    expectedVersion: $expectedVersion
    note: $note
  ) {
    notVisible
    bill {
      key
      status
      annualTotal
      assessmentYear
      billNumber
    }
  }
}

mutationcreateApiKeySigned-in people only#

Returns ApiKeyCreated!

Create a key for your own firm. The secret is returned once and never stored. For people signed in to the app: refused while acting for a client, and refused to a request made with a key.

Arguments

expiresOnDate

The last day it works, UTC. Omitted, it works until revoked.

nameString!required

What it is for, for the list: "Nightly loader". 1 to 80 characters.

scopes[Scope!]!required

One or more of the six data scopes; never ADMIN.

Example
graphql
mutation ($name: String!, $scopes: [Scope!]!) {
  createApiKey(name: $name, scopes: $scopes) {
    secret
    apiKey {
      id
      name
      status
      createdAt
      expiresAt
    }
  }
}

mutationcreateCalendarFeedNeeds PARCEL_READ#

Returns CalendarFeedCreated!

Create a subscribable calendar (iCal) URL over the whole portfolio's dates, with the balance at stake on each payment when the request holds BILL_READ. The secret is returned once, inside the URL, and never shown again. The feed answers until it is revoked, or until the key that created it is revoked or expires, or until the engagement it was created under lapses.

Arguments

labelString

Where it will be used, for the list: "Outlook", "Team calendar". Up to 80 characters; longer is cut.

Example
graphql
mutation {
  createCalendarFeed {
    url
    feed {
      id
      createdAt
      label
      lastFetchedAt
      revokedAt
    }
  }
}

mutationcreateDocumentLinkNeeds BILL_READ#

Returns DocumentLink!

A five-minute link to one document's bytes that opens without a header: for a new tab or an embedded viewer.

Arguments

documentIdID!required

The document to open, by its id.

Example
graphql
mutation ($documentId: ID!) {
  createDocumentLink(documentId: $documentId) {
    expiresAt
    path
  }
}

mutationenterBillNeeds BILL_REVIEW and BILL_READ#

Returns BillEntryPayload!

Enter a bill by hand from a tax-bill document no reading turned into a bill. The entry is a reading of its own (engine manual, by the person), checked like any reading, and a bill at needs_review: entering never accepts it. Refused before anything is written when the page is not on this server (it is the entry's evidence), when the parcel already holds a bill of that year and type (correct it from its review), and when the installments do not add up to the charges.

Arguments

documentIdID!required

The tax-bill document the figures are typed from, by its id.

entryBillEntryInput!required

The figures as the page prints them: the year, the bill type, its installments and its charges.

noteString!required

What the figures were entered from, for the trail and the reviewer.

Example
graphql
mutation ($documentId: ID!, $entry: BillEntryInput!, $note: String!) {
  enterBill(documentId: $documentId, entry: $entry, note: $note) {
    message
    outcome
    installments {
      id
      status
      amountDue
      amountOutstanding
      amountPaid
    }
  }
}

mutationflagBillForClientNeeds BILL_REVIEW and BILL_READ#

Returns BillReviewPayload!

Flag a bill for the client: NEEDS_REVIEW or VALIDATED becomes DISPUTED, on every installment named or on none. The note is what the client reads. Refused with CONFLICT when the bill changed after the version you read (expectedVersion).

Arguments

expectedVersionInt!required

The bill's version as the caller read it (TaxBill.version). If anything about the bill changed since, the call is refused as a CONFLICT (reason STALE_VERSION) and nothing is written.

installmentIds[ID!]!required

The installments of one bill, from TaxBill.installments. One bill per call.

noteString!required

What the client should know. Required.

Example
graphql
mutation ($expectedVersion: Int!, $installmentIds: [ID!]!, $note: String!) {
  flagBillForClient(
    expectedVersion: $expectedVersion
    installmentIds: $installmentIds
    note: $note
  ) {
    notVisible
    bill {
      key
      status
      annualTotal
      assessmentYear
      billNumber
    }
  }
}

mutationimportParcelsNeeds PARCEL_WRITE and PARCEL_READ#

Returns ParcelImportPayload!

Add a whole spreadsheet of parcels at once. Every row is checked before any is written (a blank number, an unknown county, the same parcel twice, more than 500 rows), the accepted rows land together, and rejected rows are reported by index. dryRun checks and writes nothing. California counties only, for now.

Arguments

inputParcelImportInput!required

The rows and the owner of record.

Example
graphql
mutation ($input: ParcelImportInput!) {
  importParcels(input: $input) {
    created
    dryRun
    existing
    legalEntity {
      id
      name
      taxIdLast4
    }
    rejected {
      index
      reason
    }
  }
}

mutationimportPaymentsNeeds BILL_REVIEW and PARCEL_READ#

Returns PaymentImportPayload!

A whole list of the customer's payments at once, each row naming its parcel, year and installment. Every row is checked; the good ones land as one transaction, a row already on record is counted rather than recorded twice, and rejected rows are reported by index with the reason, a row the database refuses among them. dryRun checks and writes nothing.

Arguments

inputPaymentImportInput!required

The rows, and whether only to check them (dryRun).

Example
graphql
mutation ($input: PaymentImportInput!) {
  importPayments(input: $input) {
    alreadyRecorded
    dryRun
    recorded
    rejected {
      index
      reason
    }
  }
}

mutationopenAppealNeeds APPEAL_WRITE and PARCEL_READ#

Returns Appeal!

Record an appeal of one assessment year. The filing deadline comes from the unit's window unless deadlineOn is given; where the window depends on an event whose date is not on record, it stays null with a reason. CONFLICT when the year already has an appeal.

Arguments

assessmentYearInt!required

The year of the assessed value under appeal, 1990 to 2100.

deadlineOnDate

The last day to file, when you know it better than the unit's rule.

noteString

A note for whoever reads the appeal next.

parcelIdID!required

The parcel.

requestedValueMoney

The value the appeal asks for.

Example
graphql
mutation ($assessmentYear: Int!, $parcelId: ID!) {
  openAppeal(assessmentYear: $assessmentYear, parcelId: $parcelId) {
    id
    status
    assessedValue
    assessmentYear
    createdAt
    deadlineOn
    deadlineReason
    deadlineSource
    parcel {
      id
      parcelNumber
      status
      useCode
    }
    openedBy {
      id
      name
      email
    }
  }
}

mutationrecordAppealOutcomeNeeds APPEAL_WRITE and PARCEL_READ#

Returns Appeal!

Record the decision on an appeal: the date, the value the board set (a value above the assessed value is allowed and recorded), and the tax saved, if known. Final: only the note of a decided appeal can change afterwards (updateAppeal), so record the savings with the decision. Refused with CONFLICT when the appeal changed after the version you read (expectedVersion).

Arguments

appealIdID!required

The appeal.

decidedOnDate!required

When it was decided.

decidedValueMoney!required

The value the board set.

expectedVersionInt!required

The appeal's version as the caller read it (Appeal.version). If the appeal changed since, the call is refused as a CONFLICT (reason STALE_VERSION) and nothing is written.

noteString

Replaces the note on the appeal.

savingsMoney

The tax saved, from the corrected bill, if known now; it cannot be added later.

Example
graphql
mutation ($appealId: ID!, $decidedOn: Date!, $decidedValue: Money!, $expectedVersion: Int!) {
  recordAppealOutcome(
    appealId: $appealId
    decidedOn: $decidedOn
    decidedValue: $decidedValue
    expectedVersion: $expectedVersion
  ) {
    id
    status
    assessedValue
    assessmentYear
    createdAt
    deadlineOn
    deadlineReason
    deadlineSource
    parcel {
      id
      parcelNumber
      status
      useCode
    }
    openedBy {
      id
      name
      email
    }
  }
}

mutationrecordPaymentNeeds BILL_REVIEW and BILL_READ#

Returns RecordPaymentPayload!

Record one entry in the customer's own payment records for an installment: a payment, a refund, or a signed adjustment, with the day the money moved and a reference. Kept beside the county's published figure, never merged into it. The same entry twice is one entry.

Arguments

amountMoney!required

The amount in dollars. A payment or a refund is positive; an adjustment may be negative. Never zero.

effectiveDateDate!required

The day the money moved.

installmentIdID!required

The installment the money was for, by its id.

kindPaymentKind!required

A payment, a refund, or an adjustment.

noteString

Anything the next reader should know about the entry.

referenceString

A check number, a confirmation, a ledger line.

Example
graphql
mutation ($amount: Money!, $effectiveDate: Date!, $installmentId: ID!, $kind: PaymentKind!) {
  recordPayment(
    amount: $amount
    effectiveDate: $effectiveDate
    installmentId: $installmentId
    kind: $kind
  ) {
    recorded
    installment {
      id
      status
      amountDue
      amountOutstanding
      amountPaid
    }
  }
}

mutationrejectBillNeeds BILL_REVIEW and BILL_READ#

Returns BillReviewPayload!

Reject a bill as a wrong reading: NEEDS_REVIEW or DISPUTED becomes REJECTED, on every installment named or on none. Final, and left out of every total and deadline; undoBillReview takes it back within 10 minutes. A later fetch does not reopen it: one that reads other charges is the bill's next revision, waiting for review. Refused with CONFLICT when the bill changed after the version you read (expectedVersion).

Arguments

expectedVersionInt!required

The bill's version as the caller read it (TaxBill.version). If anything about the bill changed since, the call is refused as a CONFLICT (reason STALE_VERSION) and nothing is written.

installmentIds[ID!]!required

The installments of one bill, from TaxBill.installments. One bill per call.

reasonString!required

Why, for the activity trail. Required.

Example
graphql
mutation ($expectedVersion: Int!, $installmentIds: [ID!]!, $reason: String!) {
  rejectBill(
    expectedVersion: $expectedVersion
    installmentIds: $installmentIds
    reason: $reason
  ) {
    notVisible
    bill {
      key
      status
      annualTotal
      assessmentYear
      billNumber
    }
  }
}

mutationreportBillProblemNeeds BILL_REVIEW and BILL_READ#

Returns BillReviewPayload!

Report a bill that was accepted automatically (TaxBill.acceptedAutomatically) as wrong. It goes back to NEEDS_REVIEW and to retrieve-IQ, who check it against the county and correct it or hand it to you; until then it shows as being checked (TaxBill.retrieveIqCheck) and accepting, flagging and rejecting it are refused. Refused for a bill a person accepted or one not accepted, and with CONFLICT when the bill changed after the version you read (expectedVersion).

Arguments

expectedVersionInt!required

The bill's version as the caller read it (TaxBill.version). If anything about the bill changed since, the call is refused as a CONFLICT (reason STALE_VERSION) and nothing is written.

installmentIds[ID!]!required

The installments of one bill, from TaxBill.installments. One bill per call.

noteString!required

What looks wrong. retrieve-IQ reads it, and it stays in the bill's history. Required.

Example
graphql
mutation ($expectedVersion: Int!, $installmentIds: [ID!]!, $note: String!) {
  reportBillProblem(
    expectedVersion: $expectedVersion
    installmentIds: $installmentIds
    note: $note
  ) {
    notVisible
    bill {
      key
      status
      annualTotal
      assessmentYear
      billNumber
    }
  }
}

mutationreportRuleNeeds PARCEL_READ#

Returns RuleReport!

Tell the people who maintain the rules that a rule or a filing requirement is wrong. The report keeps what the product showed for that rule and year at filing, and its status shows in ruleReports when they answer. A rule itself changes only through the reviewed dataset.

Arguments

inputReportRuleInput!required

The rule, the year, and what is wrong with it.

Example
graphql
mutation ($input: ReportRuleInput!) {
  reportRule(input: $input) {
    id
    status
    assessmentYear
    createdAt
    evidenceUrl
    problem
    resolution
    resolvedAt
    jurisdiction {
      id
      name
      assesses
      billDelivery
      bills
    }
    reportedBy {
      id
      name
      email
    }
  }
}

mutationrequestReportNeeds REPORT_READ#

Returns ReportJob!

Request a report. It is produced in the background with the access this request has: the engagement's scopes, capped by the key's, checked again when it runs. The key needs REPORT_READ and the scopes the report reads with (reportCatalog names them); one without them is refused here. The job carries downloadUrl once DONE. Poll reportJob or reportJobs.

Arguments

filterReportFilter

Which parcels. The whole portfolio when omitted.

formatReportFormat!required

The file format.

kindReportKind!required

Which report, from reportCatalog.

Example
graphql
mutation ($format: ReportFormat!, $kind: ReportKind!) {
  requestReport(format: $format, kind: $kind) {
    id
    name
    status
    byteSize
    downloadUrl
    error
    filterDescription
    finishedAt
    requestedBy {
      id
      name
      email
    }
  }
}

mutationrerunReportNeeds REPORT_READ#

Returns ReportJob!

Queue a report again as it was asked for: the kind, the format and the filter of the job named, which may have failed or expired. The new job is yours and renders under your context, as requestReport's do; an appeal its filter names that you can no longer read refuses it as NOT_ENTITLED, with nothing queued.

Arguments

idID!required

The ReportJob to ask for again.

Example
graphql
mutation ($id: ID!) {
  rerunReport(id: $id) {
    id
    name
    status
    byteSize
    downloadUrl
    error
    filterDescription
    finishedAt
    requestedBy {
      id
      name
      email
    }
  }
}

mutationresolveValidationNeeds BILL_REVIEW and BILL_READ#

Returns ResolveValidationPayload!

Accept a discrepancy a check found: the check records who, when and the note (Validation.resolutionNote), its history keeps them for good (Validation.history), and the bill is no longer withheld once no check stands. There is no un-resolve; a wrong resolution is followed by a rejection or a re-fetch, both of which leave a record. The note is required because the next reader asks why. The bill's version moves (TaxBill.version), so a decision made from a read before the resolution is refused with CONFLICT.

Arguments

idID!required

The check (a Validation) to resolve.

noteString!required

Why the discrepancy is acceptable. Required.

Example
graphql
mutation ($id: ID!, $note: String!) {
  resolveValidation(id: $id, note: $note) {
    bill {
      key
      status
      annualTotal
      assessmentYear
      billNumber
    }
    validation {
      id
      clearedAt
      code
      createdAt
      expected
    }
  }
}

mutationrevokeApiKeySigned-in people only#

Returns ApiKey!

End one of your firm's keys. It stops working at once for the API and the MCP server, a calendar feed it created stops answering, and a report it requested that has not run yet fails. The record stays, with the time. For people signed in to the app: refused while acting for a client.

Arguments

idID!required

The key.

Example
graphql
mutation ($id: ID!) {
  revokeApiKey(id: $id) {
    id
    name
    status
    createdAt
    expiresAt
    lastUsedAt
    prefix
    revokedAt
  }
}

mutationrevokeCalendarFeedNeeds PARCEL_READ#

Returns CalendarFeed!

End a calendar feed. Its record stays; the URL answers 404 from now on.

Arguments

idID!required

The feed.

Example
graphql
mutation ($id: ID!) {
  revokeCalendarFeed(id: $id) {
    id
    createdAt
    label
    lastFetchedAt
    revokedAt
    createdBy {
      id
      name
      email
    }
  }
}

mutationsetLegalEntityTaxIdNeeds ADMIN and PARCEL_READ#

Returns LegalEntityPayload!

Store a legal entity's tax identification number (an EIN, nine digits however typed), kept encrypted. Only the last four digits are ever returned; the trail records that a number was set, never the number. An administrator's act: ADMIN on the engagement, with PARCEL_WRITE.

Arguments

legalEntityIdID!required

The legal entity, by its id.

taxIdString!required

The number as written, with or without its dash: nine digits.

Example
graphql
mutation ($legalEntityId: ID!, $taxId: String!) {
  setLegalEntityTaxId(legalEntityId: $legalEntityId, taxId: $taxId) {
    legalEntity {
      id
      name
      taxIdLast4
    }
  }
}

mutationstartDocumentUploadNeeds BILL_REVIEW#

Returns DocumentUploadLink!

Start an upload for a parcel: a county's bill PDF, read when the product reads that county's bills exactly, or a client's own export, kept as evidence. Returns a link for the bytes, good once, for fifteen minutes.

Arguments

inputStartDocumentUploadInput!required

The parcel, what the document is, its name and its exact size.

Example
graphql
mutation ($input: StartDocumentUploadInput!) {
  startDocumentUpload(input: $input) {
    expiresAt
    maxBytes
    method
    uploadPath
  }
}

mutationundoBillReviewNeeds BILL_REVIEW and BILL_READ#

Returns BillReviewPayload!

Take back your own acceptance, flag or rejection of a bill within 10 minutes: each installment returns to the status it had before, and both the decision and its undoing stay in the activity trail. expectedVersion is the version the decision's answer carried; CONFLICT when the bill changed since. Refused with UNDO_REFUSED and a reason (NO_DECISION, ALREADY_UNDONE, NOT_YOURS, EXPIRED, CHANGED) otherwise.

Arguments

expectedVersionInt!required

The bill's version as the decision being taken back left it (BillReviewPayload.bill.version).

installmentIds[ID!]!required

The installments of the bill whose decision to take back.

Example
graphql
mutation ($expectedVersion: Int!, $installmentIds: [ID!]!) {
  undoBillReview(
    expectedVersion: $expectedVersion
    installmentIds: $installmentIds
  ) {
    notVisible
    bill {
      key
      status
      annualTotal
      assessmentYear
      billNumber
    }
  }
}

mutationupdateAppealNeeds APPEAL_WRITE and PARCEL_READ#

Returns Appeal!

Change what an appeal asks for, when its window closes, or its note. While the appeal is open or filed: requestedValue (null clears it), deadlineOn (the person's own date) or deadlineFromRule (the jurisdiction's window again, which is no date where the rule gives none exact). At any status: note (null or empty clears it), which is how a decided or withdrawn appeal is corrected. Only the arguments given change, and a change to what the appeal already holds is refused as nothing to change. The trail records each change, from and to. CONFLICT when the appeal changed after expectedVersion was read.

Arguments

appealIdID!required

The appeal, by its id.

deadlineFromRuleBoolean

True takes the window's close from the jurisdiction's rule again, which is no date where the rule gives none exact. Not with deadlineOn.

deadlineOnDate

The day the appeal's window closes, as you know it. Only while the appeal is open or filed; it cannot be cleared, deadlineFromRule puts the rule's date back.

expectedVersionInt!required

The appeal's version as the caller read it (Appeal.version). If the appeal changed since, the call is refused as a CONFLICT (reason STALE_VERSION) and nothing is written.

noteString

The appeal's note; null or empty clears it. At any status.

requestedValueMoney

The value the appeal asks for, in dollars; null clears it. Only while the appeal is open or filed.

Example
graphql
mutation ($appealId: ID!, $expectedVersion: Int!) {
  updateAppeal(appealId: $appealId, expectedVersion: $expectedVersion) {
    id
    status
    assessedValue
    assessmentYear
    createdAt
    deadlineOn
    deadlineReason
    deadlineSource
    parcel {
      id
      parcelNumber
      status
      useCode
    }
    openedBy {
      id
      name
      email
    }
  }
}

mutationupdateAppealStatusNeeds APPEAL_WRITE and PARCEL_READ#

Returns Appeal!

FILE an appeal (with filedOn), WITHDRAW it, or REOPEN a withdrawn one; WITHDRAW and REOPEN clear filedOn. A decided appeal is final: only its note can change, through updateAppeal. Refused with CONFLICT when the appeal changed after the version you read (expectedVersion).

Arguments

actionAppealAction!required

The move to make.

appealIdID!required

The appeal.

expectedVersionInt!required

The appeal's version as the caller read it (Appeal.version). If the appeal changed since, the call is refused as a CONFLICT (reason STALE_VERSION) and nothing is written.

filedOnDate

When it was filed. With FILE.

noteString

Replaces the note on the appeal.

Example
graphql
mutation ($action: AppealAction!, $appealId: ID!, $expectedVersion: Int!) {
  updateAppealStatus(
    action: $action
    appealId: $appealId
    expectedVersion: $expectedVersion
  ) {
    id
    status
    assessedValue
    assessmentYear
    createdAt
    deadlineOn
    deadlineReason
    deadlineSource
    parcel {
      id
      parcelNumber
      status
      useCode
    }
    openedBy {
      id
      name
      email
    }
  }
}

mutationupsertParcelNeeds PARCEL_WRITE and PARCEL_READ#

Returns UpsertParcelPayload!

Add a parcel to the portfolio. Safe to repeat: a parcel already held comes back with created false and nothing changed.

Arguments

inputParcelInput!required

The parcel.

Example
graphql
mutation ($input: ParcelInput!) {
  upsertParcel(input: $input) {
    created
    parcel {
      id
      parcelNumber
      status
      useCode
    }
  }
}