OpenAPI Specification
openapi: 3.0.3
info:
version: '1.0'
title: Company authorization suppliers API
description: The Bokio Company API containing all resources for company tenant.
termsOfService: https://docs.bokio.se/page/terms/
contact:
name: Bokio
url: https://docs.bokio.se
email: support@bokio.se
servers:
- url: https://api.bokio.se/v1
description: Bokio API
x-bokio-api: true
security:
- tokenAuth: []
tags:
- name: suppliers
description: Operations for managing suppliers
paths:
/companies/{companyId}/suppliers:
parameters:
- name: companyId
in: path
required: true
description: Unique identifier of the company
schema:
type: string
format: uuid
example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
post:
tags:
- suppliers
summary: '[Preview] Create a supplier'
description: 'Creates a new supplier for the company.
**Scope:** `suppliers:write`
'
operationId: post-supplier
requestBody:
description: Post the necessary fields for the API to create a supplier.
content:
application/json:
schema:
$ref: '#/components/schemas/supplier'
examples:
New supplier:
value:
name: Supplier ABC
orgNumber: 556677-8899
vatNumber: SE123456789001
address:
line1: Älvsborgsvägen 10
line2: c/o Test
city: Gothenburg
postalCode: 123 45
country: SE
paymentDetails:
type: bankgiro
bankgiroNumber: 1234-5678
responses:
'200':
description: Supplier created
content:
application/json:
schema:
$ref: '#/components/schemas/supplier'
examples:
Supplier created:
value:
id: 12345678-abcd-1234-abcd-1234567890ab
name: Supplier ABC
orgNumber: 556677-8899
vatNumber: SE123456789001
currency: SEK
address:
line1: Älvsborgsvägen 10
line2: c/o Test
city: Gothenburg
postalCode: 123 45
country: SE
paymentDetails:
type: bankgiro
bankgiroNumber: 1234-5678
'400':
description: Missing required information
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: validation-error
message: Validation failed with 1 error
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
errors:
- field: '#/name'
message: The name field is required
security:
- tokenAuth: []
get:
tags:
- suppliers
summary: '[Preview] Get suppliers'
description: 'Get all suppliers for the company. Use the query parameters to filter and navigate through the results.
**Scope:** `suppliers:read`
'
operationId: get-suppliers
parameters:
- name: page
in: query
required: false
description: Page number
schema:
type: integer
format: int32
default: 1
- name: pageSize
in: query
required: false
description: Number of items per page
schema:
type: integer
format: int32
default: 25
maximum: 100
- name: query
in: query
required: false
description: 'Optional query to filter the data set with supported fields listed below and [available operations](filtering).
| Field | Type |
| -------------------- | ----------- |
| name | string |
| vatNumber | string |
| orgNumber | string |
'
schema:
type: string
example: name==Supplier ABC
responses:
'200':
description: Suppliers found
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/pagedResponse'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/supplier'
security:
- tokenAuth: []
/companies/{companyId}/suppliers/{supplierId}:
parameters:
- name: companyId
in: path
required: true
description: Unique identifier of the company
schema:
type: string
format: uuid
example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
- name: supplierId
in: path
required: true
description: Unique identifier of the supplier
schema:
type: string
format: uuid
example: 12345678-abcd-1234-abcd-1234567890ab
get:
tags:
- suppliers
summary: '[Preview] Get a supplier'
description: 'Retrieve the information of the supplier with the matching supplierId.
**Scope:** `suppliers:read`
'
operationId: get-supplier-by-id
responses:
'200':
description: Supplier found
content:
application/json:
schema:
$ref: '#/components/schemas/supplier'
examples:
Supplier found:
value:
id: 12345678-abcd-1234-abcd-1234567890ab
name: Example Supplier
orgNumber: 556677-8899
vatNumber: SE123456789001
currency: SEK
address:
line1: Älvsborgsvägen 10
line2: c/o Test
city: Gothenburg
postalCode: 123 45
country: SE
paymentDetails:
type: bankgiro
bankgiroNumber: 5174-8895
'404':
description: Supplier not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: not-found
message: Supplier not found
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
security:
- tokenAuth: []
put:
tags:
- suppliers
summary: '[Preview] Update a supplier'
description: 'Update an existing supplier for the company.
**Scope:** `suppliers:write`
'
operationId: put-supplier
requestBody:
description: Post the necessary fields for the API to update a supplier.
content:
application/json:
schema:
$ref: '#/components/schemas/supplier'
examples:
Update supplier:
value:
name: Updated Supplier ABC
orgNumber: 556677-8899
vatNumber: SE123456789001
currency: SEK
address:
line1: Älvsborgsvägen 10
line2: c/o Test
city: Gothenburg
postalCode: 123 45
country: SE
paymentDetails:
type: internationalPayment
iban: SE1234567890123456789012
bic: SWEDSESS
responses:
'200':
description: Supplier updated
content:
application/json:
schema:
$ref: '#/components/schemas/supplier'
examples:
Supplier updated:
value:
id: 12345678-abcd-1234-abcd-1234567890ab
name: Updated Supplier ABC
orgNumber: 556677-8899
vatNumber: SE123456789001
currency: SEK
address:
line1: Älvsborgsvägen 10
line2: c/o Test
city: Gothenburg
postalCode: 123 45
country: SE
paymentDetails:
type: internationalPayment
iban: SE1234567890123456789012
bic: SWEDSESS
'400':
description: Missing required information
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: validation-error
message: Validation failed with 1 error
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
errors:
- field: '#/name'
message: The name field is required
'404':
description: Supplier not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: not-found
message: Supplier not found
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
security:
- tokenAuth: []
delete:
tags:
- suppliers
summary: '[Preview] Delete a supplier'
description: 'Delete an existing supplier for the company.
NOTE: Currently only supports deleting suppliers that have been added through the API.
**Scope:** `suppliers:write`
'
operationId: delete-supplier
responses:
'204':
description: Supplier deleted
'400':
description: Operation not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Not created by integration:
value:
code: operation-not-allowed
message: Bokio API only supports deleting suppliers that have been added through the API by the same integration.
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
Supplier has active invoices:
value:
code: operation-not-allowed
message: Cannot delete supplier with active invoices.
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
security:
- tokenAuth: []
components:
schemas:
apiError:
type: object
title: apiError
properties:
code:
type: string
message:
type: string
bokioErrorId:
type: string
format: uuid
errors:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
bankgiroPaymentDetails:
type: object
title: bankgiroPaymentDetails
required:
- type
- bankgiroNumber
properties:
type:
type: string
enum:
- bankgiro
bankgiroNumber:
type: string
description: The bankgiro number for the supplier
example:
type: bankgiro
bankgiroNumber: 1234-5678
pagedResponse:
type: object
title: pagedResponse
properties:
totalItems:
type: integer
format: int32
example: 1
totalPages:
type: integer
format: int32
example: 1
currentPage:
type: integer
format: int32
example: 1
transferPaymentDetails:
type: object
title: transferPaymentDetails
required:
- type
- clearingNumber
- accountNumber
properties:
type:
type: string
enum:
- transfer
clearingNumber:
type: string
description: Bank clearing number
accountNumber:
type: string
description: Bank account number
example:
type: transfer
clearingNumber: '1234'
accountNumber: '1234567890'
internationalPaymentDetails:
type: object
title: internationalPaymentDetails
required:
- type
- iban
- bic
properties:
type:
type: string
enum:
- internationalPayment
iban:
type: string
description: International Bank Account Number
bic:
type: string
description: Bank Identifier Code (SWIFT code)
example:
type: internationalPayment
iban: SE1234567890123456789012
bic: SWEDSESS
plusgiroPaymentDetails:
type: object
title: plusgiroPaymentDetails
required:
- type
- plusgiroNumber
properties:
type:
type: string
enum:
- plusgiro
plusgiroNumber:
type: string
description: The plusgiro number for the supplier
example:
type: plusgiro
plusgiroNumber: 12345-6
supplier:
type: object
title: supplier
required:
- name
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
orgNumber:
type: string
vatNumber:
type: string
currency:
type: string
description: 'ISO 4217 currency code. Defaults to SEK if not provided.
Sets the currency for the supplier, which determines the currency used when creating supplier invoices. When a non-SEK currency is set, exchange rates are automatically calculated to determine the correct SEK amount — no manual exchange rate lookup is needed.
Allowed values depend on whether the company has a Bokio Business Account (BBA):
**With Bokio Business Account:** `SEK`, `EUR`, `NOK`, `USD`, `DKK`, `GBP`, `PLN`, `RON`, `CZK`, `HUF`, `ISK`, `CHF`
Note: For companies with a Bokio Business Account, only currencies supported by BBA are available. For supplier invoices that cannot be paid via BBA, the currency must be set to `SEK` and exchange rates must be handled manually.
**Without Bokio Business Account:** `SEK`, `GBP`, `EUR`, `USD`, `NOK`, `DKK`, `AUD`, `BRL`, `CAD`, `CHF`, `CNY`, `CZK`, `HKD`, `HUF`, `IDR`, `INR`, `ISK`, `JPY`, `KRW`, `MAD`, `MXN`, `NZD`, `PLN`, `RUB`, `SAR`, `SGD`, `THB`, `TRY`, `ZAR`
'
default: SEK
address:
$ref: '#/components/schemas/supplierAddress'
paymentDetails:
$ref: '#/components/schemas/paymentDetails'
example:
id: 12345678-abcd-1234-abcd-1234567890ab
name: Example Supplier
orgNumber: 556677-8899
vatNumber: SE123456789001
currency: SEK
address:
line1: Älvsborgsvägen 10
line2: c/o Test
city: Gothenburg
postalCode: 123 45
country: SE
paymentDetails:
type: bankgiro
bankgiroNumber: 1234-5678
paymentDetails:
type: object
title: paymentDetails
required:
- type
discriminator:
propertyName: type
mapping:
bankgiro: '#/components/schemas/bankgiroPaymentDetails'
plusgiro: '#/components/schemas/plusgiroPaymentDetails'
transfer: '#/components/schemas/transferPaymentDetails'
internationalPayment: '#/components/schemas/internationalPaymentDetails'
oneOf:
- $ref: '#/components/schemas/bankgiroPaymentDetails'
- $ref: '#/components/schemas/plusgiroPaymentDetails'
- $ref: '#/components/schemas/transferPaymentDetails'
- $ref: '#/components/schemas/internationalPaymentDetails'
supplierAddress:
type: object
title: supplierAddress
properties:
line1:
type: string
line2:
type: string
nullable: true
city:
type: string
postalCode:
type: string
country:
description: ISO 3166-1 alpha-2 country code. Defaults to SE if not provided.
type: string
format: country
default: SE
example:
line1: Älvsborgsvägen 10
line2: c/o Test
city: Gothenburg
postalCode: 123 45
country: SE
securitySchemes:
tokenAuth:
type: http
scheme: bearer
access_token:
type: oauth2
flows:
clientCredentials:
tokenUrl: /token
scopes: {}
authorizationCode:
authorizationUrl: /authorize
tokenUrl: /token
scopes:
bank-payments:read-limited: Read access to bank payments created by the integration
bank-payments:write: Write access to bank payments
chart-of-accounts:read: Read access to chart of accounts
company-information:read: Read access to company information
credit-notes:read: Read access to credit notes
credit-notes:write: Write access to credit notes
customers:read: Read access to customers
customers:write: Write access to customers
fiscal-years:read: Read access to fiscal years
invoices:read: Read access to invoices
invoices:write: Write access to invoices
items:read: Read access to items
items:write: Write access to items
journal-entries:read: Read access to journal entries
journal-entries:write: Write access to journal entries
sie:read: Read access to SIE files
supplier-invoices:read: Read access to supplier invoices
supplier-invoices:write: Write access to supplier invoices
suppliers:read: Read access to suppliers
suppliers:write: Write access to suppliers
tags:read: Read access to tag groups and tags
tags:write: Write access to tag groups and tags
uploads:read: Read access to uploads
uploads:write: Write access to uploads
client_auth:
type: http
scheme: basic
externalDocs:
url: https://docs.bokio.se
description: Read the API Documentation
x-readme:
explorer-enabled: true
proxy-enabled: false
samples-languages:
- shell
- http
- node
- csharp
- java