OpenAPI Specification
openapi: 3.0.3
info:
version: '1.0'
title: Company authorization customers 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: customers
description: Operations for managing customer data
paths:
/companies/{companyId}/customers:
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:
- customers
summary: Create a customer
description: 'Creates a customer for the company.
**Scope:** `customers:write`
'
operationId: post-customer
requestBody:
description: Post the necessary fields for the API to create a customer.
content:
application/json:
schema:
$ref: '#/components/schemas/customer'
examples:
New customer:
value:
name: customer 1
type: company
vatNumber: SE1234567890
orgNumber: 123456-7890
paymentTerms: '30'
contactsDetails:
- name: John Doe
email: john@email.com
phone: 0927-5631505
isDefault: true
address:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
language: sv
responses:
'200':
description: Customer created
content:
application/json:
schema:
$ref: '#/components/schemas/customer'
examples:
customer created:
value:
name: customer 1
type: company
vatNumber: SE1234567890
orgNumber: 123456-7890
paymentTerms: '30'
contactsDetails:
- id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
name: John Doe
email: john@email.com
phone: 0927-5631505
isDefault: true
address:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
language: sv
modifiedDateTime: 2024-10-10 00:00:00+00:00
'400':
description: Missing required information
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: validation-error
message: Validation failed with 3 errors
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
errors:
- field: '#/name'
message: The name field is required
- field: '#/type'
message: The type field is required
- field: '#/address/country'
message: 'Invalid country code: XX'
security:
- tokenAuth: []
get:
tags:
- customers
summary: Get customers
description: 'Get all customers for the company. Use the query parameters to filter and navigate through the results.
**Scope:** `customers:read`'
operationId: get-customer
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 |
| type | string |
| vatNumber | string |
| orgNumber | string |
| modifiedDateTime | date-time |
'
schema:
type: string
example: name==customer 1
responses:
'200':
description: Customers found
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/pagedResponse'
- type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/customer'
security:
- tokenAuth: []
/companies/{companyId}/customers/{customerId}:
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: customerId
in: path
required: true
schema:
type: string
format: uuid
example: 55c899c5-82b2-47fa-9c51-e35fc9b26443
description: Unique identifier of the customer
get:
tags:
- customers
summary: Get a customer
description: 'Retrieve the information of the customer with the matching customerId.
**Scope:** `customers:read`
'
operationId: get-customers-customerId
responses:
'200':
description: Customer found
content:
application/json:
schema:
$ref: '#/components/schemas/customer'
examples:
customer found:
value:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
type: company
vatNumber: SE1234567890
orgNumber: 123456-7890
paymentTerms: '30'
contactsDetails:
- id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
name: John Doe
email: john@email.com
phone: 0927-5631505
isDefault: true
address:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
language: sv
modifiedDateTime: 2024-10-10 00:00:00+00:00
'404':
description: Customer not found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: not-found
message: Customer not found
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
security:
- tokenAuth: []
put:
tags:
- customers
summary: Update a customer
description: 'Update an existing customer for the company.
**Scope:** `customers:write`
'
operationId: put-customer
requestBody:
description: Post the necessary fields for the API to update a customer.
content:
application/json:
schema:
$ref: '#/components/schemas/customer'
examples:
Update customer:
value:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
type: company
vatNumber: SE1234567890
orgNumber: 123456-7890
paymentTerms: '30'
contactsDetails:
- Id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
name: John Doe
email: john@email.com
phone: 0927-5631505
isDefault: true
address:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
language: sv
responses:
'200':
description: Customer updated
content:
application/json:
schema:
$ref: '#/components/schemas/customer'
examples:
Update customer:
value:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
type: company
vatNumber: SE1234567890
orgNumber: 123456-7890
paymentTerms: '30'
contactsDetails:
- id: 240a4af0-edfd-47b1-b4ab-f30450eaac19
name: John Doe
email: john@email.com
phone: 0927-5631505
isDefault: true
address:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
language: sv
modifiedDateTime: 2024-10-10 00:00:00+00:00
'400':
description: Missing required information
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
examples:
Error:
value:
code: validation-error
message: Validation failed with 3 errors
bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
errors:
- field: '#/name'
message: The name field is required
- field: '#/type'
message: The type field is required
- field: '#/address/country'
message: 'Invalid country code: XX'
security:
- tokenAuth: []
delete:
tags:
- customers
summary: Delete a customer
description: 'Delete an existing customer for the company.
NOTE: Currently only supports deleting customers that have been added through the API.
**Scope:** `customers:write`
'
operationId: delete-customer
responses:
'204':
description: Customer deleted
security:
- tokenAuth: []
components:
schemas:
customer:
type: object
title: customer
required:
- name
- type
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
type:
type: string
enum:
- company
- private
vatNumber:
type: string
orgNumber:
type: string
paymentTerms:
type: string
description: 'Payment terms for the invoices. Payment terms can both take free text or days, in digits, until the payment is due.
On the invoice, if a digit is provided it will be suffixed with "days". For example, "30" will be displayed as "30 days" on the invoice. Note that the suffix will, similar to the rest of the invoice, use the language on the customer.
'
contactsDetails:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
nullable: true
description: Should not be set for new items
name:
type: string
email:
type: string
phone:
type: string
isDefault:
type: boolean
address:
$ref: '#/components/schemas/addressWithCountrySubdivision'
language:
type: string
description: Default 'sv'
enum:
- sv
- en
modifiedDateTime:
type: string
format: date-time
readOnly: true
nullable: true
description: The date and time the customer was last modified. Returns null for customers that were changed before this field was introduced.
example:
id: 55c899c5-82b2-47fa-9c51-e35fc9b26443
name: customer 1
type: company
vatNumber: SE1234567890
orgNumber: 123456-7890
paymentTerms: '30'
contactsDetails:
- name: John Doe
email: john@email.com
phone: 0927-5631505
isDefault: true
address:
line1: Älvsborgsvägen 10
line2: null
city: Göteborg
postalCode: 123 45
country: SE
language: sv
modifiedDateTime: 2024-10-10 00:00:00+00:00
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
addressWithCountrySubdivision:
type: object
title: addressWithCountrySubdivision
required:
- line1
- city
- postalCode
- country
properties:
line1:
type: string
line2:
type: string
nullable: true
city:
type: string
postalCode:
type: string
country:
description: ISO 3166-1 alpha-2 country code
type: string
format: country
countrySubdivision:
description: ISO 3166-2 subdivision code (e.g. ENG, SCT, WLS, NIR for GB). Currently required for GB (United kingdom) country.
type: string
nullable: true
example:
line1: 10 Downing Street
line2: null
city: London
postalCode: SW1A 2AA
country: GB
countrySubdivision: ENG
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
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