API docs by Redocly

SantInvoice API (0.3.1)

Download OpenAPI specification:

General

General service information

Check the service health

Responses

Response samples

Content type
text/xml
<healthCheckResponse>
  <status>Ok</status>
</healthCheckResponse>

Submission

Making submissions to the SantInvoice server

Submit an invoice for processing

Submission Rules

  • If defaultCurrency is not specified, every item MUST specify a currency on it's debit or credit field.
  • processedDetails MUST NOT be included in any submission.
  • issuedAt MUST NOT be specified.
  • paymentDueBy MUST NOT be in the past.
Authorizations:
oauth
header Parameters
X-Idempotency-Key
required
string

A unique token for this particular submission. It is recommended to prefix your application name, then suffix something unique to your application.

Request Body schema: text/xml

Responses

Request samples

Content type
text/xml
<invoice
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://hpkns.uk/accounting"
  xsi:schemaLocation="https://hpkns.uk/accounting ../accounting.xsd"
  defaultCurrency="GBP"
>
  <paymentDueBy>2026-12-20</paymentDueBy>

  <parties>
    <us>
      <name>Eden Turner</name>
      <address>1 Transport Lane</address>
      <email>driver@example.com</email>
    </us>
    <them>
      <name>Lily Hopkins</name>
      <address>17 Dumb Road</address>
      <email>passenger@example.com</email>
    </them>
  </parties>

  <items>
    <item>
      <date>2025-12-01</date>
      <summary>DriveShare Journey</summary>
      <details>2.3 miles, 12:30 - 12:42</details>
      <link>https://driveshare.hpkns.uk/view-journey/asbdoiausbdiu</link>
      <tag>driveshare</tag>
      <tag>driveshare-user=passenger@example.com</tag>
      <debit>32.15</debit>
    </item>
    <item>
      <date>2025-12-01</date>
      <summary>Proton Duo</summary>
      <debit currency="EUR">3.20</debit>
    </item>
    <item>
      <date>2025-12-01</date>
      <summary>Payment</summary>
      <credit>12.52</credit>
    </item>
  </items>

  <notes>Please make payment to the usual bank account with the reference as your account number. Thanks.</notes>
</invoice>

Response samples

Content type
text/xml
<invoice
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://hpkns.uk/accounting"
  xsi:schemaLocation="https://hpkns.uk/accounting ../accounting.xsd"
  defaultCurrency="GBP"
>
  <paymentDueBy>2026-12-20</paymentDueBy>

  <parties>
    <us>
      <name>Eden Turner</name>
      <address>1 Transport Lane</address>
      <email>driver@example.com</email>
    </us>
    <them>
      <name>Lily Hopkins</name>
      <address>17 Dumb Road</address>
      <email>passenger@example.com</email>
    </them>
  </parties>

  <items>
    <item>
      <date>2025-12-01</date>
      <summary>DriveShare Journey</summary>
      <details>2.3 miles, 12:30 - 12:42</details>
      <link>https://driveshare.hpkns.uk/view-journey/asbdoiausbdiu</link>
      <tag>driveshare</tag>
      <tag>driveshare-user=passenger@example.com</tag>
      <debit>32.15</debit>
    </item>
    <item>
      <date>2025-12-01</date>
      <summary>Proton Duo</summary>
      <debit>2.82</debit>
    </item>
    <item>
      <date>2025-12-01</date>
      <summary>Payment</summary>
      <credit>12.52</credit>
    </item>
  </items>

  <notes>Please make payment to the usual bank account with the reference as your account number. Thanks.</notes>

  <processedDetails>
    <number>I12391</number>
    <account>A142873</account>
    <exchangeRates>
      <rate from="EUR">0.88</rate>
    </exchangeRates>
    <total>22.45</total>
  </processedDetails>
</invoice>

Submit a payment lot

Submission Rules

  • If defaultCurrency is not specified, every item MUST specify a currency on it's debit or credit field.
  • processedDetails MUST NOT be included in any submission.
  • paymentMadeAt MUST NOT be specified.
  • If toAccount is provided, it MUST be for an accounts receivable or accounts payable account.
Authorizations:
oauth
header Parameters
X-Idempotency-Key
required
string

A unique token for this particular submission. It is recommended to prefix your application name, then suffix something unique to your application.

Request Body schema: text/xml

Responses

Request samples

Content type
text/xml
Example
<paymentLot
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://hpkns.uk/accounting"
  xsi:schemaLocation="https://hpkns.uk/accounting ../accounting.xsd"
  defaultCurrency="GBP"
>
  <parties>
    <payer>
      <name>Eden Turner</name>
      <address>17 Dumb Road</address>
      <email>passenger@example.com</email>
    </payer>
    <payee>
      <name>Lily Hopkins</name>
      <address>19 Dumb Road</address>
      <email>driver@example.com</email>
    </payee>
  </parties>

  <payments>
    <payment>
      <source>BACS</source>
      <amount>320.00</amount>
      <externalReference>tx_00008zjky19HyFLAzlUk7t</externalReference>
      <details>Reference: AB123958</details>
    </payment>
  </payments>
</paymentLot>

Response samples

Content type
text/xml
<paymentLot
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://hpkns.uk/accounting"
  xsi:schemaLocation="https://hpkns.uk/accounting ../accounting.xsd"
  defaultCurrency="GBP"
>
  <paymentMadeAt>2025-12-12T00:00:00</paymentMadeAt>

  <parties>
    <payer>
      <name>Eden Turner</name>
      <address>17 Dumb Road</address>
      <email>passenger@example.com</email>
    </payer>
    <payee>
      <name>Lily Hopkins</name>
      <address>19 Dumb Road</address>
      <email>driver@example.com</email>
    </payee>
  </parties>

  <payments>
    <payment>
      <source>BACS</source>
      <amount>320.00</amount>
      <externalReference>monzo:tx_00008zjky19HyFLAzlUk7t</externalReference>
      <details>Reference: AB123958</details>
    </payment>
  </payments>

  <processedDetails>
    <number>P12391</number>
    <account>A142873</account>
    <exchangeRates>
      <rate from="EUR">0.88</rate>
    </exchangeRates>
    <total>320.00</total>
  </processedDetails>
</paymentLot>

View

View accounting information

Get the general ledger

Authorizations:
oauth
query Parameters
linkedTo
stringI[0-9]+

Filter by invoice number(s) associated with an item

lineIdentifier
string <uuid>

Filter by line identifier(s) assicated with an item

tag
string

Filter by tag(s) associated with an item

fromDate
string <date>

Filter by items since this date, inclusive

toDate
string <date>

Filter by items until this date, inclusive

Responses

Response samples

Content type
text/xml
<account
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://hpkns.uk/accounting"
  xsi:schemaLocation="https://hpkns.uk/accounting ../accounting.xsd"
  defaultCurrency="GBP"
>
  <generalLedger />

  <openingBalance>0.00</openingBalance>
  <items>
    <item>
      <date>2025-12-01</date>
      <summary>DriveShare Journey</summary>
      <details>2.3 miles, 12:30 - 12:42</details>
      <link>https://driveshare.hpkns.uk/view-journey/asbdoiausbdiu</link>
      <tag>driveshare</tag>
      <tag>driveshare-user=passenger@example.com</tag>
      <credit>32.15</credit>
      <lineIdentifier>019b4108-0969-72c7-9957-05e6126cd4f3</lineIdentifier>
      <complementaryIdentifier>019b4104-68b4-753b-bf0c-d4182dfb9a11</complementaryIdentifier>
      <account>A12345678</account>
      <complementaryAccount>A98765432</complementaryAccount>
      <linkedTo>I12391</linkedTo>
    </item>
    <item>
      <date>2025-12-01</date>
      <summary>Proton Duo</summary>
      <credit>2.82</credit>
      <lineIdentifier>019b4108-3402-7cb8-8804-66dfcfc6a963</lineIdentifier>
      <complementaryIdentifier>019b4104-9479-75bb-bdcd-891d8f7e025c</complementaryIdentifier>
      <account>A12345678</account>
      <complementaryAccount>A98765432</complementaryAccount>
      <linkedTo>I12391</linkedTo>
    </item>
  </items>
  <closingBalance>22.45</closingBalance>
</account>

Get an account statement by account number

Authorizations:
oauth
path Parameters
accountId
required
string

The account ID, or associated email address

query Parameters
linkedTo
stringI[0-9]+

Filter by invoice number(s) associated with an item

lineIdentifier
string <uuid>

Filter by line identifier(s) assicated with an item

tag
string

Filter by tag(s) associated with an item

fromDate
string <date>

Filter by items since this date, inclusive

toDate
string <date>

Filter by items until this date, inclusive

Responses

Response samples

Content type
text/xml
<account
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://hpkns.uk/accounting"
  xsi:schemaLocation="https://hpkns.uk/accounting ../accounting.xsd"
  defaultCurrency="GBP"
>
  <meta>
    <number>A12345678</number>
    <type>accountsReceivable</type>
    <owner>
      <name>Lily Hopkins</name>
      <address>17 Dumb Road</address>
      <email>driver@example.com</email>
    </owner>
    <otherParty>
      <name>Eden Turner</name>
      <address>15 Dumb Road</address>
      <email>passenger@example.com</email>
    </otherParty>
  </meta>

  <openingBalance date="2025-12-01">32.00</openingBalance>

  <items>
    <item>
      <date>2025-12-01</date>
      <summary>DriveShare Journey</summary>
      <details>2.3 miles, 12:30 - 12:42</details>
      <link>https://driveshare.hpkns.uk/view-journey/asbdoiausbdiu</link>
      <tag>driveshare</tag>
      <tag>driveshare-user=passenger@example.com</tag>
      <debit>32.15</debit>
      <lineIdentifier>019b4104-68b4-753b-bf0c-d4182dfb9a11</lineIdentifier>
      <complementaryIdentifier>019b4108-0969-72c7-9957-05e6126cd4f3</complementaryIdentifier>
      <account>A12345678</account>
      <complementaryAccount>A98765432</complementaryAccount>
      <linkedTo>I12391</linkedTo>
    </item>
    <item>
      <date>2025-12-01</date>
      <summary>Proton Duo</summary>
      <debit>2.82</debit>
      <lineIdentifier>019b4104-9479-75bb-bdcd-891d8f7e025c</lineIdentifier>
      <complementaryIdentifier>019b4108-3402-7cb8-8804-66dfcfc6a963</complementaryIdentifier>
      <account>A12345678</account>
      <complementaryAccount>A98765432</complementaryAccount>
      <linkedTo>I12391</linkedTo>
    </item>
    <item>
      <date>2025-12-01</date>
      <summary>Payment</summary>
      <credit>12.52</credit>
      <lineIdentifier>019b4104-af6b-78b7-bde3-d8f7eabec218</lineIdentifier>
      <account>A12345678</account>
      <complementaryAccount>A98765432</complementaryAccount>
      <linkedTo>I12391</linkedTo>
    </item>
  </items>
  <closingBalance>9.55</closingBalance>
</account>

Get an account statement by associated email address

Authorizations:
oauth
path Parameters
accountEmail
required
string <email>

The associated email address

accountType
required
string
Enum: "asset" "revenue-and-liabilities" "accounts-payable" "accounts-receivable"

The account type

query Parameters
otherParty
string <email>

The email address of the other party. This is required if using account type "accounts-payable" or "accounts-receivable", otherwise it should not be provided.

linkedTo
stringI[0-9]+

Filter by invoice number(s) associated with an item

lineIdentifier
string <uuid>

Filter by line identifier(s) assicated with an item

tag
string

Filter by tag(s) associated with an item

fromDate
string <date>

Filter by items since this date, inclusive

toDate
string <date>

Filter by items until this date, inclusive

Responses

Response samples

Content type
text/xml
<account
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://hpkns.uk/accounting"
  xsi:schemaLocation="https://hpkns.uk/accounting ../accounting.xsd"
  defaultCurrency="GBP"
>
  <meta>
    <number>A12345678</number>
    <type>accountsReceivable</type>
    <owner>
      <name>Lily Hopkins</name>
      <address>17 Dumb Road</address>
      <email>driver@example.com</email>
    </owner>
    <otherParty>
      <name>Eden Turner</name>
      <address>15 Dumb Road</address>
      <email>passenger@example.com</email>
    </otherParty>
  </meta>

  <openingBalance date="2025-12-01">32.00</openingBalance>

  <items>
    <item>
      <date>2025-12-01</date>
      <summary>DriveShare Journey</summary>
      <details>2.3 miles, 12:30 - 12:42</details>
      <link>https://driveshare.hpkns.uk/view-journey/asbdoiausbdiu</link>
      <tag>driveshare</tag>
      <tag>driveshare-user=passenger@example.com</tag>
      <debit>32.15</debit>
      <lineIdentifier>019b4104-68b4-753b-bf0c-d4182dfb9a11</lineIdentifier>
      <complementaryIdentifier>019b4108-0969-72c7-9957-05e6126cd4f3</complementaryIdentifier>
      <account>A12345678</account>
      <complementaryAccount>A98765432</complementaryAccount>
      <linkedTo>I12391</linkedTo>
    </item>
    <item>
      <date>2025-12-01</date>
      <summary>Proton Duo</summary>
      <debit>2.82</debit>
      <lineIdentifier>019b4104-9479-75bb-bdcd-891d8f7e025c</lineIdentifier>
      <complementaryIdentifier>019b4108-3402-7cb8-8804-66dfcfc6a963</complementaryIdentifier>
      <account>A12345678</account>
      <complementaryAccount>A98765432</complementaryAccount>
      <linkedTo>I12391</linkedTo>
    </item>
    <item>
      <date>2025-12-01</date>
      <summary>Payment</summary>
      <credit>12.52</credit>
      <lineIdentifier>019b4104-af6b-78b7-bde3-d8f7eabec218</lineIdentifier>
      <account>A12345678</account>
      <complementaryAccount>A98765432</complementaryAccount>
      <linkedTo>I12391</linkedTo>
    </item>
  </items>
  <closingBalance>9.55</closingBalance>
</account>

View or Change Party

View and change information regarding parties

Get information about a party

Authorizations:
oauth
path Parameters
partyEmail
required
string <email>

The associated email address

Responses

Response samples

Content type
text/xml
<partyInfo
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://hpkns.uk/accounting"
  xsi:schemaLocation="https://hpkns.uk/accounting ../accounting.xsd"
>
  <party>
    <name>Lily Hopkins</name>
    <address>17 Dumb Road</address>
    <email>driver@example.com</email>
  </party>

  <allowedSubjects>
    <subject>389576f7-b184-4c29-b93a-5ffea6a0cb6a</subject>
    <subject>20c8a083-cdb6-4bdd-86f3-03fe73c21de4</subject>
    <subject>88fee1af-f4fc-4816-9abe-0fab4c7b6add</subject>
  </allowedSubjects>

  <webhooks>
    <webhook>https://example.com/webhook/event</webhook>
  </webhooks>
</partyInfo>

Query or update information about a party

Submission Rules

  • There cannot be a party element unless it is within an update element.
  • There cannot be a allowedSubjects element unless it is within an update element.
  • There cannot be a webhooks element unless it is within an update element.
  • If you submit an update to a party, it MUST specify a name.
Authorizations:
oauth
path Parameters
partyEmail
required
string <email>

The associated email address

Request Body schema: text/xml

Responses

Request samples

Content type
text/xml
<partyInfo
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://hpkns.uk/accounting"
  xsi:schemaLocation="https://hpkns.uk/accounting ../accounting.xsd"
>
  <update>
    <party>
      <name>Lily Hopkins</name>
      <address>17 Dumb Road</address>
      <email>driver@example.com</email>
    </party>

    <allowedSubjects>
      <subject>389576f7-b184-4c29-b93a-5ffea6a0cb6a</subject>
      <subject>20c8a083-cdb6-4bdd-86f3-03fe73c21de4</subject>
      <subject>88fee1af-f4fc-4816-9abe-0fab4c7b6add</subject>
    </allowedSubjects>

    <webhooks>
      <webhook>https://example.com/webhook/event</webhook>
    </webhooks>
  </update>
</partyInfo>

Response samples

Content type
text/xml
<partyInfo
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://hpkns.uk/accounting"
  xsi:schemaLocation="https://hpkns.uk/accounting ../accounting.xsd"
>
  <party>
    <name>Lily Hopkins</name>
    <address>17 Dumb Road</address>
    <email>driver@example.com</email>
  </party>

  <allowedSubjects>
    <subject>389576f7-b184-4c29-b93a-5ffea6a0cb6a</subject>
    <subject>20c8a083-cdb6-4bdd-86f3-03fe73c21de4</subject>
    <subject>88fee1af-f4fc-4816-9abe-0fab4c7b6add</subject>
  </allowedSubjects>

  <webhooks>
    <webhook>https://example.com/webhook/event</webhook>
  </webhooks>
</partyInfo>

Generate PDFs

Generate PDFs of invoices, payment lots, or account statements

Create a PDF invoice statement by invoice number

Authorizations:
oauth
path Parameters
invoiceNumber
required
string

The invoice number

Responses

Response samples

Content type
text/xml
<error>
  <kind>authorization_header_missing</kind>
  <message>Authorization header missing</message>
</error>

Create a PDF payment lot statement by payment lot number

Authorizations:
oauth
path Parameters
paymentLotNumber
required
string

The payment lot number

Responses

Response samples

Content type
text/xml
<error>
  <kind>authorization_header_missing</kind>
  <message>Authorization header missing</message>
</error>