get_statement - Qobra public API documentation

Get one statement in full: a row per line (each compensation, plus the manual payments and the draw), the activity log, the validation workflow, the draw balance, the calculation errors and the linked requests. Identify the statement by statement_id, the id of a row list_statements returns, not a user id. payment_status answers “am I paid, and if not, why?” in one read; when an approval holds it up, validation_workflow names the blocking stage and who still has to approve. For a line’s variables and scopes, pass the line’s compensation_id to get_statement_compensation. By default the response carries only the 20 most recent activities, most recent first, and activity_count says how many the statement holds. When activity_count is above the length of activities, call again with include_all_activities set to true to read the whole log.

Example arguments

{
  "statement_id": "665f1c2e8a4b3d0012a7e9f1",
  "include_all_activities": true
}

Every amount here, lines included, is converted into the currency named by currency_mode (payment by default) and labelled with currency, so amount and currency always agree. The conversion block gives the currency the statement stores its amounts in and the rate applied; list_exchange_rates holds the company’s rates per period. A statement with no rate for the requested currency is refused rather than served in another one. Only get_statement_compensation stays in the plan’s calculation currency. A statement with no line reads as not found. A statement you can’t access reads exactly like one that doesn’t exist, so the error never reveals a statement outside your scope.

Parameters

Body

string

required

The id of a row of list_statements, not a user id.

string

Currency every amount (total_amount, each line’s value, balance, minimum_compensation) is converted into and labelled with: ‘payment’ (default) the currency the user is paid in, ‘calculation’ the currency the plan computes in, ‘company’ the company’s currency. One of: company, payment, calculation.

boolean

default:"false"

True to serve the statement’s whole activity log. By default only the 20 most recent activities are served, most recent first; activity_count says how many there are.

Response

Body

string

The statement_id get_statement, get_statement_compensation, list_statement_records and the statement writes take. Not the user’s id.

string

Deep link to open this statement in the Qobra web app.

object

Show object properties

string

error (a calculation failed, whatever the lock or the payment), ongoing (open, editable), locked (amounts locked, not paid), paid (sent to payroll). Not the reporting stage of list_statement_periods. One of: error, ongoing, locked, paid.

string

ready (amounts current), calculating (a computation is running), need_refresh (data changed since the last computation, amounts stale). Not the lifecycle status. One of: ready, calculating, need_refresh.

number

Net amount to be paid out, in currency: it already reflects the draw and the manual payments, so it is not just the sum of the compensation lines.

string

The ISO currency code that total_amount is expressed in. One of: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RMB, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYI, UYU, UZS, VEF, VND, VUV, WON, WST, XAF, XAG, XAU, XCD, XOF, XPD, XPF, XPT, XSU, YER, ZAR, ZMK, ZWL.

object

How every amount of this statement reached currency: the currency it is stored in and the rate applied.

Show object properties

string

The currency the statement stores its amounts in — its calculation currency, the one its plan computes in. One of: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RMB, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYI, UYU, UZS, VEF, VND, VUV, WON, WST, XAF, XAG, XAU, XCD, XOF, XPD, XPF, XPT, XSU, YER, ZAR, ZMK, ZWL.

number

The exchange rate applied to every amount here: an amount in source_currency times this rate gives the amount in currency. 1 when both are the same currency, i.e. nothing was converted. Read list_exchange_rates for the company’s rates and the periods they apply to.

string

When the statement last finished computing and was up to date; null if it never reached that state.

boolean

True when a value of one of the statement’s lines was corrected by hand, or a line was entered by hand (a manual payment, or the draw set by hand), a manual payment alone being enough. The overwritten and manual flags of each line in get_statement’s compensations tell which.

object

The draw carried on this statement, its amounts in currency. Null when it has none, or when draws are off for the company (get_company_settings).

Show object properties

number

Opening balance carried over from the previous period.

number

Opening balance set by hand, detached from the previous period; null if not overridden. When set, the draw is taken from it.

number

The draw applied this period: the part of the balance recovered against this statement’s commissions.

boolean

True when the balance was entered or edited by hand.

number

The opening balance (or its override) minus drawn_value.

string

What the payment waits on:

blocked_by_error: a calculation error, to fix first.
awaiting_lock: still open, to lock first.
awaiting_approval: locked, a mandatory validation-workflow stage is not approved yet (awaited_approvers).
awaiting_payroll: locked, nothing blocks it, not yet sent to payroll.
paid: sent to payroll. One of: blocked_by_error, awaiting_lock, awaiting_approval, awaiting_payroll, paid.

object[]

The approvers of the workflow stages open now who have not approved yet, optional stages included. Empty when nothing awaits an approval.

Show object properties

object

Show object properties

string

When they were last reminded to approve; null if never.

object[]

Show object properties

string

object

Show object properties

string

object

Show object properties

string

object[]

The statement’s lines, as get_statement lists them without their amounts. Pass this statement’s id and a line’s compensation_id to get_statement_compensation for its breakdown.

Show object properties

string

What get_statement_compensation takes, with this statement’s id, for the line’s breakdown; valid on this statement only. Null on a manual payment or the draw.

string

object

Show object properties

string

Deep link that opens this line in the Qobra web app — its statement, with this compensation selected.

number

The line’s amount, converted into currency.

string

The statement’s currency, that of value. One of: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RMB, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYI, UYU, UZS, VEF, VND, VUV, WON, WST, XAF, XAG, XAU, XCD, XOF, XPD, XPF, XPT, XSU, YER, ZAR, ZMK, ZWL.

boolean

True when a value behind this line (a variable of the line, of one of its records, or the line itself) was corrected by hand, through update_statement_adjustments or in the web app. A line entered by hand is manual instead.

boolean

True on a line entered by hand: a manual payment, or the draw when draw is true too.

boolean

True on the draw line (the recoverable advance); manual tells whether its amount was set by hand.

string

The payment_id update_statement_payments takes to change or remove a manual payment line. Null on every other line.

string

How often the compensation is calculated, on the company’s fiscal calendar. EACH_MONTH every month; EACH_MONTH_EXCEPT_END_OF_QUARTER every month but the one each quarter closes on; EACH_QUARTER, EACH_SEMESTER and EACH_YEAR at each period’s close; Q1-Q4 once a year, at that quarter’s close only. A compensation bounded to a window is calculated at most once: on the statement closing the period of its cadence that holds the window’s last day, and never when its cadence does not calculate on that period. Null on a manual payment or draw row, which no compensation backs.

string

First month this line covers (YYYY-MM): a quarterly compensation on a June statement starts in April, the statement’s period being only where it is paid out.

string

Last month this line actually covers (YYYY-MM).

object[]

The line’s scopes (its calculation perimeters), by letter. Empty on a manual payment or draw row.

Show object properties

string

The scope_id list_statement_records takes, valid on this statement only.

string

Deep link that opens this scope in the Qobra web app — its statement, on its compensation line, scrolled to this tab.

string

The scope’s short label within the compensation (A, B, …).

string

boolean

True once the statement is locked and its amounts can no longer change. status cannot tell it for an errored statement, which reports error even when locked and paid.

boolean

True once the statement was sent to payroll.

boolean

True when at least one line failed to compute. See errors for the detail.

string

object

The months this statement covers: a quarterly compensation paid out in June covers April to June, which period alone does not say.

Show object properties

string

The span in words, as the web app titles it.

string

First month any line on this statement covers (YYYY-MM).

string

Last month any line on this statement covers (YYYY-MM).

number

Guaranteed floor of this statement, in currency; null when the plan sets none.

object[]

The groups the user belongs to on the statement.

Show object properties

string

object[]

Show object properties

object

Show object properties

string

Workflow step this event records: freeze (statement locked), validation (an intermediate, informational sign-off), payment (sent to payroll). One of: freeze, validation, payment.

string

object[]

The calculation errors, resolved to variable, quota and scope names. Empty when the statement computed cleanly, and for a caller whose role can edit neither compensations nor quotas, even when error is true.

Show object properties

object

The compensation the error sits on: its id is the compensation_id get_statement_compensation takes, on this statement.

Show object properties

string

object

Show object properties

string

The variable whose computation errored.

string

The scope the errored variable belongs to, when the error is on a scope record rather than a compensation variable.

string

The kind of calculation error:

FormulaError / DivisionZeroError: the formula could not be computed.
TypeError: a value had an unexpected type.
ConversionError: no exchange rate for a currency in the period.
NullQuotaError / NullQuotaProjectionError: a quota has no value for the period.
ScopeTooLargeError: a scope returned too many records to compute.
FieldDependencyError / FieldReferenceError / DependencyError: the variable depends on a field or variable that is missing or in error. One of: FormulaError, DivisionZeroError, TypeError, ConversionError, NullQuotaError, NullQuotaProjectionError, ScopeTooLargeError, FieldDependencyError, FieldReferenceError, DependencyError.

string

The specifics of the error: the missing currency, quota, scope or dependency by name.

object

The approval stages the statement goes through once locked, who approves each and who already did. Null when no workflow is assigned or the company’s validation workflow is off.

Show object properties

string

When the last approval landed, once every stage, optional ones included, is validated; null until then.

integer

Position of the first mandatory stage not yet validated, the one holding payment up; null when nothing blocks, and once the statement is paid.

object[]

Stages in the order the statement goes through them.

Show object properties

boolean

Whether the stage gates what follows: until it is approved, the statement cannot be paid and the later stages wait. An optional stage blocks neither payment nor the later stages, but it still waits behind an earlier mandatory stage that is not approved yet.

boolean

True: every approver must approve. False: the first approval completes the stage.

integer

1-based position of the stage in the workflow.

string

validated: the stage got the approvals it needs. in_progress: open to its approvers now. pending: waiting on an earlier mandatory stage, its approvers cannot act yet. One of: validated, in_progress, pending.

object[]

Show object properties

object

Show object properties

string

When this approver approved the stage; null if not yet.

object[]

The statement’s activity log, most recent first: only the 20 most recent unless include_all_activities is true. activity_count says how many the statement holds.

Show object properties

object

Show object properties

string

The comment the actor wrote, with every @-mention rendered as @<name> instead of the raw user id the web app stores; null when the activity carries no comment. See comment_mentions for the ids and emails behind those names.

object[]

The users @-mentioned in comment, in order of first appearance; empty when it mentions nobody. A mention whose id matches no user is left as a raw handle in comment and is absent here.

Show object properties

string

object[]

Show object properties

string

any

string

One of: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RMB, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYI, UYU, UZS, VEF, VND, VUV, WON, WST, XAF, XAG, XAU, XCD, XOF, XPD, XPF, XPT, XSU, YER, ZAR, ZMK, ZWL.

string

integer

How many activities the statement holds, whatever activities lists. Above the length of activities, call again with include_all_activities=true for the rest.

string[]

The reasons the company requires an adjustment of a statement to cite. Pass one of them as reason to update_statement_adjustments. Null when the company requires none.

​Parameters

​Response

Parameters

Response