Skip to content

Record a journal entry activity
Alpha

Request

Record an activity item against a journal entry. Integrations can use this to relay how an entry was processed in an external accounting system - for example that a sync started, succeeded, or failed. The recorded activity surfaces on the entry's activity feed and drives its sync status.

Supply a stable activity_id to make retries idempotent: recording the same activity_id again has no further effect.

Security
OAuth2(Required scopes: accounting.write)
Path
journalEntryIdstringrequired

The unique identifier of the journal entry.

Bodyapplication/jsonrequired
sourcestringrequired

The system recording the activity - typically the integration relaying the result (e.g. "e-conomic", "tripletex").

typestringrequired

What the activity represents. The set of accepted types grows over time as more kinds of activity are supported.

Enum:"SYNC_STARTED""SYNC_SUCCEEDED""SYNC_FAILED"
activity_idstring

A client-supplied idempotency key for the activity. Recording the same activity_id again has no further effect. Generated by the server when omitted.

detailstring

Human-readable detail eg. error message of a failed sync.

detail_codestring(ActivityDetailCode)

How a failed sync classifies, so it can be rendered in the reader's language and acted on without parsing detail. detail still carries what the accounting provider itself said about the posting; this says what kind of failure it was. Omitted when the integration has nothing to classify - a successful sync, or an activity recorded before the field existed - so fall back to detail when it is absent.

ValueWhat the customer does
CONFIGURATION_INCOMPLETEfinish setting the integration up
CONFIGURATION_INVALIDcorrect a specific mapping, named in detail
CONNECTION_REJECTEDreconnect the integration
ACCESS_DENIEDreauthorize the integration to widen its grant
SALES_DOCUMENT_MISSINGmake the correction in the provider by hand
FINANCIAL_YEAR_MISSINGopen a period covering the posting date
PROVIDER_REJECTEDact on the provider's own message in detail
UNKNOWNretry, and contact support if it persists

The set grows over time; treat an unrecognised value as UNKNOWN.

Enum:"CONFIGURATION_INCOMPLETE""CONFIGURATION_INVALID""CONNECTION_REJECTED""ACCESS_DENIED""SALES_DOCUMENT_MISSING""FINANCIAL_YEAR_MISSING""PROVIDER_REJECTED""UNKNOWN"
external_referenceobject(ExternalReference)

A labelled link to the record this activity refers to in the external system - for example the voucher created by a successful sync.

occurred_atstring, (date-time)

Timestamp of when the activity happened in the source system. Defaults to the time the request is received when omitted.

POST
/v1/accounting-journal-entries/{journalEntryId}/activities
curl -i -X POST \
  'https://api.understory.io/v1/accounting-journal-entries/{journalEntryId}/activities' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "activity_id": "string",
    "source": "string",
    "type": "SYNC_STARTED",
    "detail": "string",
    "detail_code": "CONFIGURATION_INCOMPLETE",
    "external_reference": {
      "label": "string",
      "url": "http://example.com"
    },
    "occurred_at": "2019-08-24T14:15:22Z"
  }'

Responses

The activity was recorded.

Bodyapplication/json
idstringrequired

The unique identifier of the activity item.

sourcestringrequired

The system that recorded the activity - typically the accounting integration relaying the result (e.g. "e-conomic", "tripletex").

typestringrequired

What the activity represents. The set of types grows over time, so treat unrecognised values as UNKNOWN. UNKNOWN is returned when the upstream value does not match a known type; treat as a signal to re-fetch or surface for manual review.

Enum:"SYNC_STARTED""SYNC_SUCCEEDED""SYNC_FAILED""UNKNOWN"
occurred_atstring, (date-time)required

When the activity happened in the source system.

recorded_atstring, (date-time)required

When the activity was recorded by Understory.

detailstring

Human-readable detail about the activity - for example the error message of a failed sync. Omitted when there is nothing to add.

detail_codestring(ActivityDetailCode)

How a failed sync classifies, so it can be rendered in the reader's language and acted on without parsing detail. detail still carries what the accounting provider itself said about the posting; this says what kind of failure it was. Omitted when the integration has nothing to classify - a successful sync, or an activity recorded before the field existed - so fall back to detail when it is absent.

ValueWhat the customer does
CONFIGURATION_INCOMPLETEfinish setting the integration up
CONFIGURATION_INVALIDcorrect a specific mapping, named in detail
CONNECTION_REJECTEDreconnect the integration
ACCESS_DENIEDreauthorize the integration to widen its grant
SALES_DOCUMENT_MISSINGmake the correction in the provider by hand
FINANCIAL_YEAR_MISSINGopen a period covering the posting date
PROVIDER_REJECTEDact on the provider's own message in detail
UNKNOWNretry, and contact support if it persists

The set grows over time; treat an unrecognised value as UNKNOWN.

Enum:"CONFIGURATION_INCOMPLETE""CONFIGURATION_INVALID""CONNECTION_REJECTED""ACCESS_DENIED""SALES_DOCUMENT_MISSING""FINANCIAL_YEAR_MISSING""PROVIDER_REJECTED""UNKNOWN"
external_referenceobject(ExternalReference)

A labelled link to the record this activity refers to in the external system - for example the voucher created by a successful sync.

Response
{
  "id": "string",
  "source": "string",
  "type": "SYNC_STARTED",
  "detail": "string",
  "detail_code": "CONFIGURATION_INCOMPLETE",
  "external_reference": {
    "label": "string",
    "url": "http://example.com"
  },
  "occurred_at": "2019-08-24T14:15:22Z",
  "recorded_at": "2019-08-24T14:15:22Z"
}