Skip to content
KivraAPI Reference
This is a new version of the Kivra Developer Docs. Report issues or share feedback at avsandare.support@kivra.se. The previous version can be found here.

Schemas

The operation pages expand referenced schemas inline. Use this page to browse the reusable component schemas and inspect their complete YAML definitions.

36 schemas.

TokenResponseobject
title: TokenResponse
type: object
required:
  - access_token
  - token_type
  - expires_in
properties:
  access_token:
    type: string
    description: OAuth 2.0 access token.
  token_type:
    type: string
    description: Token type to use in the Authorization header.
  expires_in:
    type: integer
    description: Lifetime of the access token in seconds.
Paymentobject

NOTE: payment is deprecated and will be removed on 31st May 2024. Use `payment_multiple_options` instead. 

title: Payment
type: object
description: >
  NOTE: payment is deprecated and will be removed on 31st May 2024. Use
  `payment_multiple_options` instead.
required:
  - payable
  - currency
  - due_date
  - total_owed
  - type
  - method
  - account
  - reference
properties:
  payable:
    type: boolean
    description: Toggles whether this content should be payable through Kivra’s
      payment platform
  status:
    type: string
    description: "Toggles whether this content is paid or unpaid: if already paid
      the user can’t pay it again through Kivra"
    default: unpaid
    readOnly: true
    enum:
      - paid
      - unpaid
  currency:
    type: string
    enum:
      - SEK
    example: SEK
    description: |
      Currency used in specifying `total_owed`. In Sweden, only SEK is accepted.
  due_date:
    type: string
    format: ISO8601
    example: 2017-01-01
    description: Date when this Invoice is due
  total_owed:
    type: string
    format: float
    example: "123.50"
    description: The total amount owed according to the invoice. **If `payable`
      equals `true` this must be a non negative number that’s greater than or
      equal to "1"**
  type:
    type: string
    description: Type of format for the reference
    example: SE_OCR
    enum:
      - SE_OCR
      - TENANT_REF
  method:
    type: string
    description: 1 = BG and 2 = PG
    example: "1"
    enum:
      - "1"
      - "2"
  account:
    type: string
    example: "12345"
    description: Tenant’s account number
  reference:
    type: string
    example: "426523791"
    description: The reference number used for paying. This can be maximum 25
      characters long
  variable_amount:
    type: boolean
    default: false
    description: Toggles whether the user may choose to pay only a portion of the
      total_owed amount or whether the user must always pay the complete
      total_owed amount
  min_amount:
    type: string
    format: float
    example: "50.00"
    description: The minimum amount that can be paid when `variable_amount` equals
      `true`. Note that this is a soft limit, so whenever `variable_amount` is
      `true` the user will be able to choose freely the amount to be paid, but
      it may be warned if the amount paid is inferior to `min_amount`.
      `min_amount` must be greater than "0" and less than "total_owed".
CompanyInboxobject
title: CompanyInbox
type: object
properties:
  key:
    description: Content's unique key
    type: string
    example: 15294092505b9cfab3f79d233f8eca6fbc5385fa61
  sender:
    description: Unique key for the tenant that posted the content
    type: string
    example: 1341573157b3a133f220f4217b2e32989d2efa015
  sender_name:
    description: Name of the tenant that posted the content
    type: string
    example: Kivra
  created_at:
    description: Date and time when the content was delivered to the recipient
    type: string
    example: 2018-06-19T11:54:10Z
  subject:
    description: Subject of the content, as set by the sender
    type: string
    example: Invoice 4512 from Local Bank
  status:
    description: Whether the content has been read (opened) or not
    type: string
    enum:
      - read
      - unread
    example: read
CompanyContentobject
title: CompanyContent
type: object
properties:
  sender:
    description: Unique key for the tenant that posted the content
    type: string
    example: 1341573157b3a133f220f4217b2e32989d2efa015
  sender_name:
    description: Name of the tenant that posted the content
    type: string
    example: Kivra
  created_at:
    description: Date and time when the content was delivered to the recipient
    type: string
    example: 2018-06-19T11:54:10Z
  subject:
    description: Subject of the content, as set by the sender
    type: string
    example: Invoice 4512 from Local Bank
  receiver_name:
    description: Name of the company that received the content
    type: string
    example: Digital Hero AB
  payment:
    $ref: "#/components/schemas/Payment"
  parts:
    description: files composing the content
    type: array
    items:
      $ref: "#/components/schemas/Parts"
Partsobject
title: Parts
type: object
properties:
  content_type:
    type: string
    description: The IANA media type corresponding to the file, e.g. "application/pdf"
    example: application/pdf
  checksum:
    type: string
    description: The cheksum of the document calculated with md5
    example: 9209c7eebdd283a4c4bd7555e73e6064
  sha256:
    type: string
    description: hash of the document calculated with SHA-256
    example: 287f2fe67a8a76a10169aa6a885d21e1f83416c4831294ea5c4b0a38bda5c78d
  size:
    type: integer
    description: size of the document in bytes
    example: 163414
  body:
    type: string
    description: body of the content (present only if content_type is "text/html" or
      "text/plain")
    example: |-
      <!doctype html>
      <html class="....
  key:
    type: string
    description: >
      The unique key for the content file (present for all content that is not
      "text/html" or "text/plain")
    example: 15118724482475bf32615b4a2aaa604fd66377010e
EmptyStringstring

The empty string

title: EmptyString
description: The empty string
enum:
  - ""
type: string
SenderContactInfoobject

Contact information for the sender. Null if not provided or all fields are null.

title: SenderContactInfo
type: object
description: Contact information for the sender. Null if not provided or all
  fields are null.
nullable: true
properties:
  email_address:
    type: string
    nullable: true
    description: Email address for support.
    example: support@example.com
  logo_url:
    type: string
    format: url
    nullable: true
    description: URL to a logo.
    example: https://example.com/logo.png
  phone_number:
    type: string
    nullable: true
    description: Phone number for support.
    example: "+46700000000"
  text:
    type: string
    nullable: true
    description: Free-form text, e.g., contact person or department.
    example: Customer Support
  url:
    type: string
    format: url
    nullable: true
    description: URL to a support page.
    example: https://example.com/support
example:
  email_address: support@example.com
  logo_url: https://example.com/logo.png
  phone_number: "+46700000000"
  text: Customer Support
  url: https://example.com/support
CompanyKeystring

The key for a company

title: CompanyKey
description: The key for a company
pattern: ^[0-9]{10}[a-f0-9]{32}$
example: 156077433683911cdca5fd4563bded979572454cb9
type: string
ContentKeystring

The key for a content

title: ContentKey
description: The key for a content
pattern: ^[0-9]{10}[a-f0-9]{32}$
example: 156077433683911cdca5fd4563bded979572454cb9
type: string
CompanyTypestring

The company's/organisation's type This is currently based on the registry holding the signatory information. Thus `company` really means that Bolagsverket is the registry and includes Ekonomiska föreningar as well. For `riksidrottsförening` it is Riksindrottsförbundet. 

title: CompanyType
description: |
  The company's/organisation's type

  This is currently based on the registry holding the signatory
  information. Thus `company` really means that Bolagsverket is the
  registry and includes Ekonomiska föreningar as well. For
  `riksidrottsförening` it is Riksindrottsförbundet.
example: company
enum:
  - company
  - riksidrottsförening
type: string
CompanyNamestring

The name of a company

title: CompanyName
description: The name of a company
example: Cornelias Café AB
type: string
VatNumberstring

A Swedish VAT number ("momsregistreringsnummer").

title: VatNumber
pattern: ^SE[0-9]{10}01$
description: A Swedish VAT number ("momsregistreringsnummer").
example: SE556000475501
type: string
IncomingEmailstring

Email address for receiving emails as content

title: IncomingEmail
pattern: ^[a-tv-zA-TV-Z0-9]{9}@(sandbox\.)?kivramail.com$
description: Email address for receiving emails as content
type: string
example: xxcsn2psy@kivramail.com
ScanningAddressobject

Postal address for receiving physical mail as scanned content in Kivra.

title: ScanningAddress
description: Postal address for receiving physical mail as scanned content in Kivra.
nullable: true
additionalProperties: false
properties:
  name:
    $ref: "#/components/schemas/CompanyName"
  street:
    description: >
      A special "street" that allows the scanning facility to send to the
      correct company.


      It's on the format "Kivra: <organisation number>"
    type: string
    example: "Kivra: 556000-4755"
  postal_code:
    description: |
      The special postal code that goes to Kivra's scanning facility
    example: 106 31
    enum:
      - 106 31
    type: string
  city:
    description: The "city" for Kivra's scanning facility
    example: Stockholm
    enum:
      - Stockholm
    type: string
  country:
    description: The country for Kivra's scanning facility
    example: SE
    enum:
      - SE
    type: string
required:
  - name
  - street
  - postal_code
  - city
  - country
type: object
ScanningFallbackAddressobject

If a mailpiece cannot be scanned, it will be forwarded to this address instead.

title: ScanningFallbackAddress
description: If a mailpiece cannot be scanned, it will be forwarded to this address instead.
nullable: true
additionalProperties: false
properties:
  name:
    description: Name of the recipient (a company or person).
    type: string
    example: Cornelias Café AB
  street:
    description: Name of the street, including street number.
    type: string
    example: Klara Norra kyrkogata 33
  postal_code:
    description: Postal code.
    example: "11122"
    type: string
  city:
    description: Name of the city.
    example: Stockholm
    type: string
  country:
    description: Name of the country.
    example: Sverige
    type: string
  care_of:
    description: Address care of (c/o).
    example: ""
    type: string
required:
  - name
  - street
  - postal_code
  - city
  - country
  - care_of
type: object
AllServicesobject

The status of each Kivra Business and Kivra Business Plus service for the company. 

title: AllServices
description: |
  The status of each Kivra Business and Kivra Business Plus service
  for the company.
additionalProperties: false
properties:
  email:
    description: Indicates if the Kivra email service is active
    example: false
    type: boolean
  scanning:
    description: Indicates if the scanned mail service is active
    example: false
    type: boolean
  interpreter:
    deprecated: true
    description: |
      Used to indicate if the interpreter service is active. Now it is
      always false.
    example: false
    type: boolean
  kivra:
    description: Indicates that the Kivra digital mail service is active (always true)
    example: true
    enum:
      - true
    type: boolean
  minameddelanden:
    description: |
      Indicates if the Kivra public authority mail service is active.
    example: true
    type: boolean
type: object
FieldQueryParameterstring

The field(s) to respond with

title: FieldQueryParameter
description: The field(s) to respond with
example: key
type: string
BaseCompanyobject

A company object with basic fields only

title: BaseCompany
description: A company object with basic fields only
additionalProperties: false
properties:
  key:
    $ref: "#/components/schemas/CompanyKey"
  name:
    $ref: "#/components/schemas/CompanyName"
  type:
    $ref: "#/components/schemas/CompanyType"
  vat_number:
    $ref: "#/components/schemas/VatNumber"
type: object
FullCompanyobject

A company object.

title: FullCompany
description: A company object.
additionalProperties: false
properties:
  key:
    $ref: "#/components/schemas/CompanyKey"
  scanning_address:
    $ref: "#/components/schemas/ScanningAddress"
  scanning_fallback_address:
    $ref: "#/components/schemas/ScanningFallbackAddress"
  created_at:
    description: When the company started to onboard.
    example: 2019-02-26T14:47:26Z
    type: string
    format: date-time
  email:
    description: |
      Email address for receiving emails as content.
      Empty if the Kivra email service is not active.
    oneOf:
      - $ref: "#/components/schemas/IncomingEmail"
      - $ref: "#/components/schemas/EmptyString"
  name:
    $ref: "#/components/schemas/CompanyName"
  type:
    $ref: "#/components/schemas/CompanyType"
  services:
    $ref: "#/components/schemas/AllServices"
  vat_number:
    $ref: "#/components/schemas/VatNumber"
required:
  - key
type: object
GovernmentalLabelboolean

Indicates if the content comes from a governmental body. 

title: GovernmentalLabel
description: |
  Indicates if the content comes from a governmental body.
type: boolean
HandledLabelboolean

The content has been marked as `handled`, previously known as `paid`. 

title: HandledLabel
description: |
  The content has been marked as `handled`, previously known as `paid`.
type: boolean
InterpretedLabelboolean

Used to indicate if the content has been interpreted. Now it is always set to `false`. 

title: InterpretedLabel
deprecated: true
description: |
  Used to indicate if the content has been interpreted. Now it is always
  set to `false`.
type: boolean
example: false
ReminderLabelboolean

Indicates if the content, which must be an invoice, is a reminder. 

title: ReminderLabel
description: |
  Indicates if the content, which must be an invoice, is a reminder.
type: boolean
TrashedLabelboolean

Indicates if the content has been moved to the trash. 

title: TrashedLabel
description: |
  Indicates if the content has been moved to the trash.
type: boolean
ViewedLabelboolean

The content has been viewed. This can be toggled by the user, i.e. "Mark as unread". 

title: ViewedLabel
description: |
  The content has been viewed. This can be toggled by the user, i.e. "Mark
  as unread".
type: boolean
InterpretedFieldsarray

Used to indicate which fields, in dot notation, have been interpreted. Now it is always set to the empty array. 

title: InterpretedFields
deprecated: true
description: |
  Used to indicate which fields, in dot notation, have been interpreted.
  Now it is always set to the empty array.
type: array
items:
  type: string
example: []
PartnerPaymentOptionobject

One way to pay this invoice

title: PartnerPaymentOption
description: One way to pay this invoice
additionalProperties: false
properties:
  account:
    description: The account to pay to
    example: "12345678"
    type: string
    nullable: true
  amount:
    minimum: 0
    description: The amount to pay in öre, or equivalent
    example: 150000
    type: integer
    nullable: true
  currency:
    description: The currency used for this payment option
    example: SEK
    type: string
    nullable: true
  description:
    description: The description of this payment option
    example: 12 month subscription
    type: string
    nullable: true
  due_at:
    description: Due date of this payment option
    example: 2022-03-30T00:00:00Z
    type: string
    format: date-time
    nullable: true
  interpreted:
    deprecated: true
    description: |
      Used to indicate if this payment option was interpreted. Now it is
      always set to `false`.
    example: false
    type: boolean
  reference:
    description: |
      The payments reference, could be an OCR number or invoice reference
    example: 987654321
    type: string
    nullable: true
  reference_type:
    description: The type of reference
    example: OCR
    type: string
    nullable: true
  type:
    description: The type of the the payment, aka the type of the account
    example: bankgiro
    type: string
    nullable: true
  vat_amount:
    description: The VAT in öre for this invoice, if available
    example: 1500
    type: integer
    nullable: true
required:
  - account
  - amount
  - currency
  - description
  - due_at
  - interpreted
  - reference
  - reference_type
  - type
  - vat_amount
type: object
InvoiceReferencesobject

References for this invoice

title: InvoiceReferences
description: References for this invoice
additionalProperties: false
nullable: true
properties:
  our:
    description: Our reference, "vår referens" in Swedish
    type: string
    nullable: true
    example: Gustav Larsson
  your:
    description: Your reference, "er referens" in Swedish
    type: string
    nullable: true
    example: null
required:
  - our
  - your
type: object
PartQueryParameterinteger

The content part to retrive, 1-indexed

title: PartQueryParameter
minimum: 1
description: The content part to retrive, 1-indexed
type: integer
PartMetadataobject
title: PartMetadata
additionalProperties: false
properties:
  content_type:
    description: The MIME type of this content part
    enum:
      - application/pdf
      - text/html
      - text/plain
      - image/jpeg
      - image/gif
      - image/png
      - text/calendar
      - application/msword
      - application/vnd.openxmlformats-officedocument.wordprocessingml.document
      - application/vnd.openxmlformats-officedocument.wordprocessingml.template
    type: string
  name:
    description: The name of this content part. Usually a filename.
    type: string
    example: faktura.pdf
  sha256:
    description: The SHA256 digest of this content part. For older content, received
      before early 2018, this may be `null`.
    type: string
    example: 060bed374498fe2f36a5f2e1abf217a90beb46e8fe4ec1d9d5ce7746
    nullable: true
  size:
    minimum: 0
    description: The size in bytes of this content part
    type: integer
    example: 4711
  url:
    description: The URL to fetch this content part
    type: string
    example: https://sender.sandbox-api.kivra.com/v3/partner/company/1691677086a57b73569d594df5abad7fd2575c1070/content/1691677075a9813e08f783496382b0bff743ec34ae?part=1
  responsive_body:
    description: The responsive content HTML of the part, if and only if this part
      has a corresponding responsive part
    type: string
    example: |-
      <h1>Faktura</h1>
      <p>Totalt: 1 500,00 kr/p>
required:
  - content_type
  - name
  - sha256
  - size
  - url
type: object
ContentPartschema

The file data of the content part, `content_type` in the part metadata describes its file type. 

title: ContentPart
description: |
  The file data of the content part, `content_type` in the part metadata
  describes its file type.
ContentOriginstring

The origin of the content. Indicates how the content was delivered to Kivra. - `kivra`: Sent directly through Kivra. - `minameddelanden`: Sent via Mina Meddelanden. Used by governmental organisations. - `user`: Uploaded by an user. Companies with Kivra företag+ can also receive: - `physical`: Physical post scanned by Kivra. - `email`: Sent via the company's kivramail.com email address. 

title: ContentOrigin
description: >
  The origin of the content. Indicates how the content was delivered to Kivra.

  - `kivra`: Sent directly through Kivra.

  - `minameddelanden`: Sent via Mina Meddelanden. Used by governmental
  organisations.

  - `user`: Uploaded by an user.

  Companies with Kivra företag+ can also receive:

  - `physical`: Physical post scanned by Kivra.

  - `email`: Sent via the company's kivramail.com email address.
type: string
enum:
  - kivra
  - minameddelanden
  - user
  - physical
  - email
BaseContentMetadataobject

Listing summary of content metadata

title: BaseContentMetadata
description: Listing summary of content metadata
additionalProperties: false
properties:
  created_at:
    description: |
      This is the same date and time as `transaction_at`, except for
      reminder invoices, where it is the reminder date and not the
      original invoice date.
    type: string
    format: date-time
    nullable: false
  key:
    $ref: "#/components/schemas/ContentKey"
  labels:
    description: The labels that apply to this content
    additionalProperties: false
    properties:
      governmental:
        $ref: "#/components/schemas/GovernmentalLabel"
      handled:
        $ref: "#/components/schemas/HandledLabel"
      interpreted:
        $ref: "#/components/schemas/InterpretedLabel"
      reminder:
        $ref: "#/components/schemas/ReminderLabel"
      trashed:
        $ref: "#/components/schemas/TrashedLabel"
      viewed:
        $ref: "#/components/schemas/ViewedLabel"
    required:
      - governmental
      - handled
      - interpreted
      - reminder
      - trashed
      - viewed
    type: object
  parts:
    type: array
    items:
      $ref: "#/components/schemas/PartMetadata"
  received_at:
    description: When the content was received by Kivra
    type: string
    format: date-time
  receiver_name:
    description: The name of the recipient company
    type: string
    example: Developers Developers Developers AB
  receiver_vat_number:
    $ref: "#/components/schemas/VatNumber"
  sender_icon_url:
    type: string
    example: https://sandbox-static.kivra.com/img/tenant/1341573157b3a1c55f220f4007b2e44789d2d04015/icon.png
    format: url
    description: A url to the icon used by the sender within Kivra, or `null` if no
      corresponding icon exists.
    nullable: true
  sender_name:
    description: The name of the sender
    example: Lenas Konditori AB
    type: string
    nullable: true
  sender_vat_numbers:
    description: VAT numbers representing the sender
    type: array
    items:
      $ref: "#/components/schemas/VatNumber"
    nullable: true
  origin:
    $ref: "#/components/schemas/ContentOrigin"
  subject:
    description: Subject of the content
    example: "Invoice: a thousand Swiss rolls"
    type: string
  transaction_at:
    description: |
      The date and time this content conceptually took place.

      + For a normal `invoice` it is the invoice date.
      + For a reminder `invoice` it the original invoice date and not
        the reminders invoice date.
      + For all `other` types of content it is `null`.
      + If no date could be found, it is `null`.
    type: string
    format: date-time
    nullable: true
  type:
    description: The type of the content
    enum:
      - invoice
      - other
    type: string
required:
  - created_at
  - key
  - labels
  - parts
  - received_at
  - receiver_name
  - receiver_vat_number
  - sender_icon_url
  - sender_name
  - sender_vat_numbers
  - subject
  - transaction_at
  - type
type: object
FullContentMetadataobject

Details of content metadata

title: FullContentMetadata
description: Details of content metadata
allOf:
  - type: object
    properties:
      interpreted_fields:
        $ref: "#/components/schemas/InterpretedFields"
      parts:
        description: The files in the content
        type: array
        items:
          $ref: "#/components/schemas/PartMetadata"
      payment_options:
        description: Different ways to pay an invoice
        type: array
        items:
          $ref: "#/components/schemas/PartnerPaymentOption"
      accounting:
        description: |
          Accounting data for structured invoices. For details about the
          properties see the description of the `invoice` property for
          [Send content](/docs/api/tenant/operations/sendcontent/)
        type: object
        properties:
          invoice_type:
            type: string
            description: |
              The type of invoice that the content was sent as. For details
              about expected values, see the `accounting.*` variants allowed
              for the content `type` property in
              [Send content](/docs/api/tenant/operations/sendcontent/)
          total_amount_due:
            type: string
          currency:
            type: string
          due_date:
            type: string
          bankgiro:
            type: string
          plusgiro:
            type: string
          invoice_number:
            type: string
          original_invoice_number:
            type: string
          invoice_date:
            type: string
          buyer_reference:
            type: string
          order_number:
            type: string
          supplier_name:
            type: string
          supplier_organisation_number:
            type: string
          supplier_vat_number:
            type: string
          supplier_address_street:
            type: string
          supplier_address_postal_code:
            type: string
          supplier_address_city:
            type: string
          payment_reference:
            type: object
          iban:
            type: string
          bic:
            type: string
          total_amount_tax_exclusive:
            type: string
          total_amount_tax_inclusive:
            type: string
          total_vat_amount:
            type: string
          rounding_amount:
            type: string
          total_amount_charge:
            type: string
          total_amount_discount:
            type: string
          supplier_address_country:
            type: string
          supplier_reference:
            type: string
          buyer_name:
            type: string
          buyer_organisation_number:
            type: string
          project_reference:
            type: string
          cost_center_reference:
            type: string
          rows:
            type: array
            items:
              type: object
      references:
        $ref: "#/components/schemas/InvoiceReferences"
      sender_contact_info:
        $ref: "#/components/schemas/SenderContactInfo"
    required:
      - interpreted_fields
      - key
      - labels
      - parts
      - payment_options
      - references
      - received_at
      - receiver_name
      - receiver_vat_number
      - sender_contact_info
      - sender_icon_url
      - sender_name
      - sender_vat_numbers
      - subject
      - transaction_at
      - type
  - $ref: "#/components/schemas/BaseContentMetadata"
WebhookEventIdstring

Event ID prefixed with "event_". Can be used for deduplication.

title: WebhookEventId
type: string
description: Event ID prefixed with "event_". Can be used for deduplication.
example: event_3f62fc97907a4212af028c30f1ea1927
WebhookEventCreatedAtinteger

Unix timestamp when the event happened, in seconds (UTC).

title: WebhookEventCreatedAt
type: integer
format: int64
description: Unix timestamp when the event happened, in seconds (UTC).
example: 1686089970