API docs by Redocly

Ukko API (0.8.0)

Download OpenAPI specification:Download

Attachments

Attachments

Store new attachment

Request Body schema: application/json
required

Attachment request

file
required
string

Base64 encoded file, currently supported mime types:

  • image/jpeg,
  • image/png,
  • image/gif,
  • application/pdf,
  • application/vnd.ms-office,
  • application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
file_name
required
string

File name

target_model_type
string

Type of resource

target_model_id
integer

ID of resource where want link this attachment.

document_type
string
Enum: "POWER-OF-ATTORNEY" "GUARDIANS-CONSENT" "TAX-CARD" "IDENTIFICATION" "PASSPORT" "RESIDENCE-PERMIT" "OTHER"

Type of document. Currently used only when target_model_type is 'USER'

Responses

Request samples

Content type
application/json
{
  • "file": "iVBORw0KGgoAAAANSUhEUgAAAGQAAABkBAMAAACCzIhnAAAAG1BMVEUAAAD///+fn58/Pz8fHx+/v7/f399/f39fX1/PwBUlAAAACXBIWXMAAA7EAAAOxAGVKw4bAAABOUlEQVRYhe2SvU7DQBCEV/GPUvIIoSGtJYhpjaKkRiCilJHsEJcpSO8i5rnZvdmzskGGioodKc55Ps/d3t0SuVwul8vlcv2RloU80/tvQC1w1a28lPvNkSh5fztcAbXAVas7JklN6QuDglYzA9RSruseciZ5F34tG60BaimHyk7IJ4+mz9Md//UGqAWu5IOEzGXam4mU+0Sy37MCtcCHzQjZyqDJZOm8WleYUYBa4CZSy+A1FJ8V/D2nANQCN5EwwTaXD3neOVYNEVjgP0TWj7PfI6Ywvr5qiIwWZrZP6X4A49s3h0yTvotg/JBLkqtKdhSusk+bCNQCN5HQEEXoDu6mBi0wNEwd+WUkadGWnfQg158dYwSW8ssILdD8G+n0E9ddRwBLudUynGv6cO1HC9zlcrlcLtd/0hccA0mFpeebygAAAABJRU5ErkJggg==",
  • "file_name": "sample-file.png",
  • "target_model_type": "TAX_CARD | INVOICE | RECEIPT_EXPENSE | TRAVEL_EXPENSE (DEPRECATED) | TRIP | USER",
  • "target_model_id": 0,
  • "document_type": "POWER-OF-ATTORNEY | GUARDIANS-CONSENT | TAX-CARD | IDENTIFICATION | PASSPORT | RESIDENCE-PERMIT | OTHER"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get attachment object

path Parameters
attachment_id
required
integer

Attachment id

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Deletes Attachment

path Parameters
attachment_id
required
integer

Attachment's id

Responses

Download attachment

path Parameters
attachment_id
required
integer

Attachment id

Responses

Show attachment content base64 string

path Parameters
attachment_id
required
integer

Attachment id

Responses

Gets user's attachments by target_model_type, document_type being optional

path Parameters
target_model_type
required
string
Example: USER | INVOICE | RECEIPT_EXPENSE | TRAVEL_EXPENSE

Type of attachment list: user | invoice | receipt-expense | travel-expense

document_type
required
string
Example: POWER_OF_ATTORNEY |GUARDIANS_CONSENT | TAX_CARD | * IDENTIFICATION | PASSPORT | RESIDENCE PERMIT | OTHER

Optional parameter for document type list. Used currently for User related documents

query Parameters
page
integer

Pagination page id

limit
integer
Example: limit=50

Limit per page. Default 50, max 1000

sort
string
Example: sort=document_type | created_at | mime_type

Sort by ascending order, add '-' prefix to get * descending order, ie. -total. To sort by * client_name, use company_name, contact_person

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Perform Receipt Expense Document analysis for attachment

path Parameters
attachment_id
required
integer
Example: 123

Attachment Id

Responses

Response samples

Content type
application/json
{
  • "place_of_purchase": "string",
  • "purchase_date": "2020-09-20",
  • "rows": [
    ]
}

Client Management

Client Management

Gets all user's clients

query Parameters
page
integer

Pagination page id

limit
integer
Example: limit=50

Limit per page. Default 50, max 1000

sort
string
Example: sort=company_name | type | contact_person | email | * | street_address1 | street_address2 | zip_code * | city | country | company_name, contact_person

Sort by ascending order, add -company_name to * get descending order. To sort by client_name, use * company_name, contact_person.

filter[*field_name*]
string
Example: filter[*field_name*]=filter[common_search] = 'foobar', other keys: * type | company_name | contact_person | email | city * | street_address1 | street_address2 | zip_code * | city | country | client_name

Search from fields. Array field, so * filter[common_search] = 'string. * Note common_search searches from multiple fields

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Gets full data of user's one Client

path Parameters
client_id
required
integer

Client id

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Deletes User Client

path Parameters
client_id
required
integer

Client id

Responses

Creates new Company

Request Body schema: application/json
required

CompanyRequest

occupation_id
integer
business_id
string

Business Id (Y-tunnus in Finnish)

einvoice_address
string

EINvoice/Finvoice address

einvoice_operator
string

EInvoice/Finvoice operator

company_name
string

Company name

contact_person
string

Contact Person

email
string

email

street_address1
string

Street address of the client

zip_code
string

Zipcode of the client

city
string

City of the client

country
string

Client's country as ISO short code (FI, GB, RU etc)

phone
string

Phone number

delivery_method
string
Enum: "EINVOICE" "MAIL" "EMAIL"

Default Invoice Delivery Option

display_vat_rate_id
integer

Id of the display vat rate. Required if vat_rate is not set

vat_rate
string

Default VAT rate for the Client's invoices. Related endpoint: /system/vat-rates/invoice

notify_overdue_and_automatic_debt_collection
boolean

Default value for Client's overdue and automatic debt collection setting

language
string

Short country code, ie. FI, SV, EN, EE, RU

clients_reference
string

Clients own invoicing reference

Responses

Request samples

Content type
application/json
{
  • "occupation_id": 0,
  • "business_id": "1234567-8",
  • "einvoice_address": "string",
  • "einvoice_operator": "string",
  • "company_name": "string",
  • "contact_person": "string",
  • "email": "string",
  • "street_address1": "string",
  • "zip_code": "string",
  • "city": "string",
  • "country": "FI",
  • "phone": "+3581234567",
  • "delivery_method": "EMAIL",
  • "display_vat_rate_id": 0,
  • "vat_rate": "VAT_REGULAR",
  • "notify_overdue_and_automatic_debt_collection": true,
  • "language": "FI",
  • "clients_reference": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Updates a Client Company, if passed Person Client, this will convert it to Company. * NOTE: validation rules will change to Company client.

path Parameters
client_id
required
integer

Client id

Request Body schema: application/json
required

CompanyRequest

occupation_id
integer
business_id
string

Business Id (Y-tunnus in Finnish)

einvoice_address
string

EINvoice/Finvoice address

einvoice_operator
string

EInvoice/Finvoice operator

company_name
string

Company name

contact_person
string

Contact Person

email
string

email

street_address1
string

Street address of the client

zip_code
string

Zipcode of the client

city
string

City of the client

country
string

Client's country as ISO short code (FI, GB, RU etc)

phone
string

Phone number

delivery_method
string
Enum: "EINVOICE" "MAIL" "EMAIL"

Default Invoice Delivery Option

display_vat_rate_id
integer

Id of the display vat rate. Required if vat_rate is not set

vat_rate
string

Default VAT rate for the Client's invoices. Related endpoint: /system/vat-rates/invoice

notify_overdue_and_automatic_debt_collection
boolean

Default value for Client's overdue and automatic debt collection setting

language
string

Short country code, ie. FI, SV, EN, EE, RU

clients_reference
string

Clients own invoicing reference

Responses

Request samples

Content type
application/json
{
  • "occupation_id": 0,
  • "business_id": "1234567-8",
  • "einvoice_address": "string",
  • "einvoice_operator": "string",
  • "company_name": "string",
  • "contact_person": "string",
  • "email": "string",
  • "street_address1": "string",
  • "zip_code": "string",
  • "city": "string",
  • "country": "FI",
  • "phone": "+3581234567",
  • "delivery_method": "EMAIL",
  • "display_vat_rate_id": 0,
  • "vat_rate": "VAT_REGULAR",
  • "notify_overdue_and_automatic_debt_collection": true,
  • "language": "FI",
  • "clients_reference": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Creates new Person Client

Request Body schema: application/json
required

PersonRequest

occupation_id
integer
einvoice_address
string

EINvoice/Finvoice address

einvoice_operator
string

EInvoice/Finvoice operator

contact_person
string

Contact Person

email
string

email

street_address1
string

Street address of the client

zip_code
string

Zipcode of the client

city
string

City of the client

country
string

Client's country as ISO short code (FI, GB, RU etc)

phone
string

Phone number

delivery_method
string
Enum: "EINVOICE" "MAIL" "EMAIL"

Default Invoice Delivery Option

display_vat_rate_id
integer

Id of the display vat rate. Required if vat_rate is not set

vat_rate
string

Default VAT rate for the Client's invoices. Related endpoint: /system/vat-rates/invoice

notify_overdue_and_automatic_debt_collection
boolean

Default value for Client's overdue and automatic debt collection setting

language
string

Short country code, ie. FI, SV, EN, EE, RU

clients_reference
string

Clients own invoicing reference

Responses

Request samples

Content type
application/json
{
  • "occupation_id": 0,
  • "einvoice_address": "string",
  • "einvoice_operator": "string",
  • "contact_person": "string",
  • "email": "string",
  • "street_address1": "string",
  • "zip_code": "string",
  • "city": "string",
  • "country": "FI",
  • "phone": "+3581234567",
  • "delivery_method": "EMAIL",
  • "display_vat_rate_id": 0,
  • "vat_rate": "VAT_REGULAR",
  • "notify_overdue_and_automatic_debt_collection": true,
  • "language": "FI",
  • "clients_reference": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Updates Client Person, if passed Company Client, this will convert it to Person. * NOTE: validation rules will change to Person client.

path Parameters
client_id
required
integer

Client id

Request Body schema: application/json
required

PersonRequest

occupation_id
integer
einvoice_address
string

EINvoice/Finvoice address

einvoice_operator
string

EInvoice/Finvoice operator

contact_person
string

Contact Person

email
string

email

street_address1
string

Street address of the client

zip_code
string

Zipcode of the client

city
string

City of the client

country
string

Client's country as ISO short code (FI, GB, RU etc)

phone
string

Phone number

delivery_method
string
Enum: "EINVOICE" "MAIL" "EMAIL"

Default Invoice Delivery Option

display_vat_rate_id
integer

Id of the display vat rate. Required if vat_rate is not set

vat_rate
string

Default VAT rate for the Client's invoices. Related endpoint: /system/vat-rates/invoice

notify_overdue_and_automatic_debt_collection
boolean

Default value for Client's overdue and automatic debt collection setting

language
string

Short country code, ie. FI, SV, EN, EE, RU

clients_reference
string

Clients own invoicing reference

Responses

Request samples

Content type
application/json
{
  • "occupation_id": 0,
  • "einvoice_address": "string",
  • "einvoice_operator": "string",
  • "contact_person": "string",
  • "email": "string",
  • "street_address1": "string",
  • "zip_code": "string",
  • "city": "string",
  • "country": "FI",
  • "phone": "+3581234567",
  • "delivery_method": "EMAIL",
  • "display_vat_rate_id": 0,
  • "vat_rate": "VAT_REGULAR",
  • "notify_overdue_and_automatic_debt_collection": true,
  • "language": "FI",
  • "clients_reference": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Document Analysis

Document Analysis

Perform Receipt Expense Document analysis for attachment

path Parameters
attachment_id
required
integer
Example: 123

Attachment Id

Responses

Response samples

Content type
application/json
{
  • "place_of_purchase": "string",
  • "purchase_date": "2020-09-20",
  • "rows": [
    ]
}

Receipt Expenses

Receipt Expenses

Perform Receipt Expense Document analysis for attachment

path Parameters
attachment_id
required
integer
Example: 123

Attachment Id

Responses

Response samples

Content type
application/json
{
  • "place_of_purchase": "string",
  • "purchase_date": "2020-09-20",
  • "rows": [
    ]
}

Discards invoices receiptExpenses

Discard receiptExpenses

path Parameters
invoice_id
required
integer

Invoice id

Responses

Get receipt expenses by invoice

path Parameters
invoice_id
required
string
query Parameters
sort
string
Enum: "purchase_date" "place_of_purchase" "client_name" "total_sum"
Example: sort=purchase_date | place_of_purchase | client_name | total_sum

Sort by ascending order, add -place_of_purchase to get descending order

limit
integer
Example: limit=50

Limit per page. Default 50, max 1000

page
integer

Pagination page id

filter[*field_name*]
string
Example: filter[*field_name*]=filter[place_of_purchase] = 'prisma', other keys: type | purchase_date_start | purchase_end_date | common_search

Sort fields. Array field, so filter[email] = foobar@doobar.com

  •              filter[search_date_between] = 2022-01-01|2022-01-31

  •                  If you omit the start date use |2022-01-31

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Create receipt expense

Request Body schema: application/json
required

Receipt Expense

place_of_purchase
string

Name of the place where the product/service was purchased from

additional_information
string

Additional information text field

purchase_date
string <date>

When product/service was purchased

deduction_type
string
Enum: "MATERIAL" "TRAVEL"

Type of the deduction

invoice_id
integer

Id of receipt expense's invoice

include_to_invoice_row
boolean

Is the expense charged from client as part of the invoice

Array of objects

Responses

Request samples

Content type
application/json
{
  • "place_of_purchase": "string",
  • "additional_information": "string",
  • "purchase_date": "2019-08-24",
  • "deduction_type": "MATERIAL",
  • "invoice_id": 0,
  • "include_to_invoice_row": true,
  • "rows": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get one receipt expense by id

path Parameters
receipt_expense_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Deletes Receipt Expense

path Parameters
receipt_expense_id
required
integer

Responses

Update receipt expense

path Parameters
receipt_expense_id
required
integer
Request Body schema: application/json
required

Receipt Expense

place_of_purchase
string

Name of the place where the product/service was purchased from

additional_information
string

Additional information text field

purchase_date
string <date>

When product/service was purchased

deduction_type
string
Enum: "MATERIAL" "TRAVEL"

Type of the deduction

invoice_id
integer

Id of receipt expense's invoice

include_to_invoice_row
boolean

Is the expense charged from client as part of the invoice

Array of objects

Responses

Request samples

Content type
application/json
{
  • "place_of_purchase": "string",
  • "additional_information": "string",
  • "purchase_date": "2019-08-24",
  • "deduction_type": "MATERIAL",
  • "invoice_id": 0,
  • "include_to_invoice_row": true,
  • "rows": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gets calculated VAT values and totals

path Parameters
receipt_expense_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gets calculated VAT values and totals from receipt expense request

Request Body schema: application/json
required

Receipt Expense

place_of_purchase
string

Name of the place where the product/service was purchased from

additional_information
string

Additional information text field

purchase_date
string <date>

When product/service was purchased

deduction_type
string
Enum: "MATERIAL" "TRAVEL"

Type of the deduction

invoice_id
integer

Id of receipt expense's invoice

include_to_invoice_row
boolean

Is the expense charged from client as part of the invoice

Array of objects

Responses

Request samples

Content type
application/json
{
  • "place_of_purchase": "string",
  • "additional_information": "string",
  • "purchase_date": "2019-08-24",
  • "deduction_type": "MATERIAL",
  • "invoice_id": 0,
  • "include_to_invoice_row": true,
  • "rows": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get all users receipt expense by type

path Parameters
type
required
string
Example: empty/all | draft | in_review * | rejected | discarded | approved * | waiting_for_invoice_sending | user_action_required

Type of Receipt Expense list: all | draft | in_review * | rejected | discarded | approved * | waiting_for_invoice_sending | user_action_required

query Parameters
sort
string
Enum: "purchase_date" "place_of_purchase" "client_name" "total_sum"
Example: sort=purchase_date | place_of_purchase | client_name | total_sum

Sort by ascending order, add -place_of_purchase to get descending order

limit
integer
Example: limit=50

Limit per page. Default 50, max 1000

page
integer

Pagination page id

filter[*field_name*]
string
Example: filter[*field_name*]=filter[place_of_purchase] = 'prisma', other keys: type | purchase_date_start | purchase_end_date | common_search

Sort fields. Array field, so filter[email] = foobar@doobar.com

  •              filter[search_date_between] = 2022-01-01|2022-01-31

  •                  If you omit the start date use |2022-01-31

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Users

Users

Gets service agreement PDF

Responses

Gets proof of assignment PDF

Request Body schema: application/json
required

ProofOfAssignmentRequest

start_date
string <date>
end_date
string <date>
options
Array of strings
Items Enum: "NUMBER_OF_ASSIGNMENTS" "SUM_OF_ASSIGNMENTS" "WORK_HOURS" "PAID_GROSS_SALARY" "PAID_NET_SALARY" "UNPAID_GROSS_SALARY"

Responses

Request samples

Content type
application/json
{
  • "start_date": "2020-12-12",
  • "end_date": "2020-12-12",
  • "options": [
    ]
}

Gets travel expense report PDF

path Parameters
year
required
integer
Example: 2024

Report year

Responses

Gets expense report PDF

path Parameters
year
required
integer
Example: 2024

Report year

Responses

Registers user and send verification email

query Parameters
source
string
Example: source=spa

Set this to SPA

Request Body schema: application/json
required

RegisterRequest

email
required
string (email)

User's registration email

first_name
required
string

User's first name

last_name
required
string

User's last name

phone
string

User's phone number

language
string
Enum: "fi" "en" "sv" "et" "ru"

User's locale

utmcsr
integer

Referring user id for referer bonus

utmccn
string
Enum: "" "inviteFriend" "nordea"

User referral parameter, should be inviteFriend when utmcsr is filled

utmcmd
string
Enum: "" "inviteFriend"

User referral code, should be inviteFriend when utmcsr is filled

Responses

Request samples

Content type
application/json
{
  • "email": "matti.meikalainen@example.com",
  • "first_name": "Matti",
  • "last_name": "Meikäläinen",
  • "phone": "+358401234567",
  • "language": "fi",
  • "utmcsr": "1234",
  • "utmccn": "inviteFriend",
  • "utmcmd": "inviteFriend"
}

Verifies user's email activation token and logs in with it

Request Body schema: application/json
required

Registration Email Verification Request

new_password
required
string

New Password. Rules: Must have 8 characters, with small and big letters and numbers

new_password_confirmation
required
string

Must match with the new_password field

Responses

Request samples

Content type
application/json
{
  • "new_password": "string",
  • "new_password_confirmation": "string"
}

Response samples

Content type
application/json
{ }

Logs current token session out

Responses

Logs all user's token sessions out

Responses

Creates password reset token and sends it to user's email

Request Body schema: application/json
required

Password Reset Request

email
required
string

User's email address

Responses

Request samples

Content type
application/json
{
  • "email": "foobar@example.org"
}

Reset user's password with emailed hash

path Parameters
hash
required
string
Example: qkl3jrl2jrlj4rl24j24lkj2lk4j1ewflkj

Password change token hash sent in the email

Request Body schema: application/json
required

Password Change Request

new_password
required
string

New Password. Rules: Must have 8 characters, with small and big letters and numbers

new_password_confirmation
required
string

Must match with the new_password field

Responses

Request samples

Content type
application/json
{
  • "new_password": "string",
  • "new_password_confirmation": "string"
}

Accept agreement of type

path Parameters
type
required
string
Example: terms-of-service / industry-restrictions / has-confirmed-no-business-id

Type of service agreement: terms-of-service / industry-restrictions / has-confirmed-no-business-id

Responses

Approve loyalty membership terms

Responses

Returns currently logged in user's id

Responses

Response samples

Content type
application/json
{
  • "id": 0
}

Returns currently logged in user's basic data

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update user

Request Body schema: application/json
first_name
string

User's first name. Currently can be changed until the strong identification has been done.

last_name
string

User's last name. Currently can be changed until the strong identification has been done.

marketing_name
string
profession
string
show_primary_phone_number_on_invoice
boolean

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "marketing_name": "string",
  • "profession": "string",
  • "show_primary_phone_number_on_invoice": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Sets logged in user's email

Request Body schema: application/json
email
string (Email)

User's new email

password
string (Password)

User's password

Responses

Request samples

Content type
application/json
{
  • "email": "matti.meikalainen@example.com",
  • "password": "Salasana123"
}

Sets logged in user's primary or secondary phone number

The phone number must be in international format (starts with '+') and only contain numeric * characters (other than the '+' sign of course) e.g. '+358501234567'

path Parameters
type
required
string
Example: primary

Type of phone number. Must be either 'primary' or 'secondary'

Request Body schema: application/json
phone
string (Phone number)

User's new phone number

Responses

Request samples

Content type
application/json
{
  • "phone": "+358501234567"
}

Adds logged in user's primary phone number for the first time, cannot be done after INTRO_DONE

The phone number must be in international format (starts with '+') and only contain numeric * characters (other than the '+' sign of course) e.g. '+358501234567'

Request Body schema: application/json
phone
string (Phone number)

User's phone number

Responses

Request samples

Content type
application/json
{
  • "phone": "+358501234567"
}

Sets logged in user's home address, zip code, city and country

Request Body schema: application/json
street_address1
string (Street Address 1)

User's home address; number 1 at the end is just for consistency, member table has only 1 street address

zip_code
string (Zip Code)

User's home address zip code

city
string (City)

User's home city

country
string (Country)

User's home country's ISO code (i.e. 'FI', 'RU') or 'OTHER'

Responses

Request samples

Content type
application/json
{
  • "street_address1": "Tunkkaajakuja 1",
  • "zip_code": "69420",
  • "city": "Vantaa",
  • "country": "FI"
}

Deactivate user account

Responses

Sets user's nationality. Can be done only once after INTRO_DONE

Request Body schema: application/json
nationality
string (Nationality)

String ISO code or 'OTHER', examples: FI or RU or OTHER

Responses

Request samples

Content type
application/json
{
  • "nationality": "FI"
}

Sets logged in user's iban and reference number

Request Body schema: application/json
password
string (Password)

User's password

iban
string (Iban)

User's bank account's iban number

is_fast_payment_enabled
boolean (Fast payment enabled)

Should users salary always be paid as fast payment

salary_payment_setting
string (Salary payment setting)
Enum: "PAY_MYSELF" "IMMEDIATE" "TWICE_PER_MONTH" "LAST_OF_MONTH" "IN_MID_MONTH" "BEGINNING_OF_MONTH"

When users salary should be paid

Responses

Request samples

Content type
application/json
{
  • "password": "kissa123",
  • "iban": "FI58 4702 8173 0000 15",
  • "is_fast_payment_enabled": true,
  • "salary_payment_setting": "PAY_MYSELF"
}

Checks and validates if user's iban is allowed

Request Body schema: application/json
iban
string (Iban)

User's bank account's iban number

Responses

Request samples

Content type
application/json
{
  • "iban": "FI58 4702 8173 0000 15"
}

Changes logged in user's password

Request Body schema: application/json
old_password
string (Old Password)

User's old password

new_password
string (New Password)

User's new password

Responses

Request samples

Content type
application/json
{
  • "old_password": "kissa123",
  • "new_password": "kissa1234"
}

Changes logged in user's language selection. Affects emails etc

Request Body schema: application/json
language
string (language)

New selected language

Responses

Request samples

Content type
application/json
{
  • "language": "FI, EN, SV, RU, ET"
}

Add discount to user

Request Body schema: application/json
code
string

Discount code

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Current User

Current User

Gets service agreement PDF

Responses

Gets proof of assignment PDF

Request Body schema: application/json
required

ProofOfAssignmentRequest

start_date
string <date>
end_date
string <date>
options
Array of strings
Items Enum: "NUMBER_OF_ASSIGNMENTS" "SUM_OF_ASSIGNMENTS" "WORK_HOURS" "PAID_GROSS_SALARY" "PAID_NET_SALARY" "UNPAID_GROSS_SALARY"

Responses

Request samples

Content type
application/json
{
  • "start_date": "2020-12-12",
  • "end_date": "2020-12-12",
  • "options": [
    ]
}

Gets travel expense report PDF

path Parameters
year
required
integer
Example: 2024

Report year

Responses

Gets expense report PDF

path Parameters
year
required
integer
Example: 2024

Report year

Responses

Get users unanswered questionnaire

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update questionnaire answer

path Parameters
questionnaire
required
integer
Example: 123

Questionnaire id

Request Body schema: application/json
required

QuestionnaireRequest

health_insurance_obligated
required
string
Enum: "YES" "NO" "OLD_AGE_PENSION" "INSURANCE_ELSEWHERE"

Is user health insurance obligated?

Responses

Request samples

Content type
application/json
{
  • "health_insurance_obligated": "YES"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Logs current token session out

Responses

Logs all user's token sessions out

Responses

Creates password reset token and sends it to user's email

Request Body schema: application/json
required

Password Reset Request

email
required
string

User's email address

Responses

Request samples

Content type
application/json
{
  • "email": "foobar@example.org"
}

Reset user's password with emailed hash

path Parameters
hash
required
string
Example: qkl3jrl2jrlj4rl24j24lkj2lk4j1ewflkj

Password change token hash sent in the email

Request Body schema: application/json
required

Password Change Request

new_password
required
string

New Password. Rules: Must have 8 characters, with small and big letters and numbers

new_password_confirmation
required
string

Must match with the new_password field

Responses

Request samples

Content type
application/json
{
  • "new_password": "string",
  • "new_password_confirmation": "string"
}

Get active invitation bonus campaign

Responses

Response samples

Content type
application/json
{
  • "from": "2020-09-20",
  • "to": "2020-09-20",
  • "bonus_invoice_sum": 0,
  • "invoicing_limit": 0
}

Override tax withholding percent

Request Body schema: application/json
required

DebtRequest

tax_percent
number <float>

Responses

Request samples

Content type
application/json
{
  • "tax_percent": "15.5"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete override tax withholding percent, fetches new tax card from VeroAPi

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Returns if the user can send invoices

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Returns items that require users actions

Responses

Response samples

Content type
application/json
{
  • "overdue": [
    ],
  • "rejected": [
    ],
  • "drafts": [
    ]
}

Returns overview of user's sent invoices

Responses

Response samples

Content type
application/json
{
  • "invoices_customer_paid_recently": [
    ],
  • "invoices_soon_to_overdue": [
    ],
  • "invoices_sent": [
    ],
  • "invoices_in_review": [
    ]
}

Returns user customer loyalty program related basic data

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Approve loyalty membership terms

Responses

Creates new MFA secret for user and sends SMS for verification

Responses

Verifies MFA secret with MFA code

Responses

Deactivates MFA for user

Responses

Sends SMS with deactivation code

Responses

Lists unread notifications

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Marks unread notification as read

path Parameters
notification_id
required
string <uuid>

Id of the notification which needs to be marked as read

Responses

Gives the current user an overview of their invoicing statistics

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gives the current user an overview of their invoicing statistics monthly

query Parameters
year
int
Example: year=2024

Year to get the statistics from

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gives the current user an overview of their invoicing statistics weekly

query Parameters
year
int
Example: year=2024

Year to get the statistics from

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gives the current user an overview of their invoicing statistics

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gives the current user an overview of their invoicing statistics for use in donut graph

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gives the current user an overview of their travel and receipt expense statistics for use in donut graph

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Returns currently logged in user's id

Responses

Response samples

Content type
application/json
{
  • "id": 0
}

Returns currently logged in user's basic data

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update user

Request Body schema: application/json
first_name
string

User's first name. Currently can be changed until the strong identification has been done.

last_name
string

User's last name. Currently can be changed until the strong identification has been done.

marketing_name
string
profession
string
show_primary_phone_number_on_invoice
boolean

Responses

Request samples

Content type
application/json
{
  • "first_name": "string",
  • "last_name": "string",
  • "marketing_name": "string",
  • "profession": "string",
  • "show_primary_phone_number_on_invoice": true
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Updates the UserMetaData values by key

path Parameters
key
required
string
Example: INTRO_DONE

Key for the UserMetaData that we want to change

Responses

Update user's notification settings

Request Body schema: application/json
required

NotificationRequest

salary_paid
required
Array of strings
Items Enum: "sms" "email"

Notify about paid salary through sms and/or email or not. Empty array disables all.

invoice_paid
required
Array of strings
Items Enum: "sms" "email"

Notify about paid invoice through sms and/or email or not. Empty array disables all.

invoice_overdue
required
Array of strings
Items Enum: "sms" "email"

Notify about overdue invoice through sms and/or email or not. Empty array disables all.

is_missing_tax_card_notifications_enabled
boolean

Whether we need to notify the user about missing tax card or not

allow_marketing_email
boolean

Changes whether the user wants to receive marketing emails or not

Responses

Request samples

Content type
application/json
{
  • "salary_paid": [
    ],
  • "invoice_paid": [
    ],
  • "invoice_overdue": [
    ],
  • "is_missing_tax_card_notifications_enabled": true,
  • "allow_marketing_email": true
}

Sets logged in user's email

Request Body schema: application/json
email
string (Email)

User's new email

password
string (Password)

User's password

Responses

Request samples

Content type
application/json
{
  • "email": "matti.meikalainen@example.com",
  • "password": "Salasana123"
}

Sets logged in user's primary or secondary phone number

The phone number must be in international format (starts with '+') and only contain numeric * characters (other than the '+' sign of course) e.g. '+358501234567'

path Parameters
type
required
string
Example: primary

Type of phone number. Must be either 'primary' or 'secondary'

Request Body schema: application/json
phone
string (Phone number)

User's new phone number

Responses

Request samples

Content type
application/json
{
  • "phone": "+358501234567"
}

Adds logged in user's primary phone number for the first time, cannot be done after INTRO_DONE

The phone number must be in international format (starts with '+') and only contain numeric * characters (other than the '+' sign of course) e.g. '+358501234567'

Request Body schema: application/json
phone
string (Phone number)

User's phone number

Responses

Request samples

Content type
application/json
{
  • "phone": "+358501234567"
}

Sets logged in user's home address, zip code, city and country

Request Body schema: application/json
street_address1
string (Street Address 1)

User's home address; number 1 at the end is just for consistency, member table has only 1 street address

zip_code
string (Zip Code)

User's home address zip code

city
string (City)

User's home city

country
string (Country)

User's home country's ISO code (i.e. 'FI', 'RU') or 'OTHER'

Responses

Request samples

Content type
application/json
{
  • "street_address1": "Tunkkaajakuja 1",
  • "zip_code": "69420",
  • "city": "Vantaa",
  • "country": "FI"
}

Deactivate user account

Responses

Sets user's nationality. Can be done only once after INTRO_DONE

Request Body schema: application/json
nationality
string (Nationality)

String ISO code or 'OTHER', examples: FI or RU or OTHER

Responses

Request samples

Content type
application/json
{
  • "nationality": "FI"
}

Sets logged in user's iban and reference number

Request Body schema: application/json
password
string (Password)

User's password

iban
string (Iban)

User's bank account's iban number

is_fast_payment_enabled
boolean (Fast payment enabled)

Should users salary always be paid as fast payment

salary_payment_setting
string (Salary payment setting)
Enum: "PAY_MYSELF" "IMMEDIATE" "TWICE_PER_MONTH" "LAST_OF_MONTH" "IN_MID_MONTH" "BEGINNING_OF_MONTH"

When users salary should be paid

Responses

Request samples

Content type
application/json
{
  • "password": "kissa123",
  • "iban": "FI58 4702 8173 0000 15",
  • "is_fast_payment_enabled": true,
  • "salary_payment_setting": "PAY_MYSELF"
}

Checks and validates if user's iban is allowed

Request Body schema: application/json
iban
string (Iban)

User's bank account's iban number

Responses

Request samples

Content type
application/json
{
  • "iban": "FI58 4702 8173 0000 15"
}

Changes logged in user's password

Request Body schema: application/json
old_password
string (Old Password)

User's old password

new_password
string (New Password)

User's new password

Responses

Request samples

Content type
application/json
{
  • "old_password": "kissa123",
  • "new_password": "kissa1234"
}

Changes logged in user's language selection. Affects emails etc

Request Body schema: application/json
language
string (language)

New selected language

Responses

Request samples

Content type
application/json
{
  • "language": "FI, EN, SV, RU, ET"
}

Return user's pension

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Return user's foreclosure

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Return user's default occupation from last sent invoice

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add discount to user

Request Body schema: application/json
code
string

Discount code

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Make Strong Identity Verification / Strong Authentication with Telia

Request Body schema: application/json
code
string

Exchange Code from Telias authentication system

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gets current user's Pending Name Change data

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Selects and verifies the IDP provided name

Request Body schema: application/json
selected_first_name
string

Teppo

Responses

Request samples

Content type
application/json
{
  • "selected_first_name": "string"
}

Documents

Documents

Gets service agreement PDF

Responses

Gets proof of assignment PDF

Request Body schema: application/json
required

ProofOfAssignmentRequest

start_date
string <date>
end_date
string <date>
options
Array of strings
Items Enum: "NUMBER_OF_ASSIGNMENTS" "SUM_OF_ASSIGNMENTS" "WORK_HOURS" "PAID_GROSS_SALARY" "PAID_NET_SALARY" "UNPAID_GROSS_SALARY"

Responses

Request samples

Content type
application/json
{
  • "start_date": "2020-12-12",
  • "end_date": "2020-12-12",
  • "options": [
    ]
}

Gets travel expense report PDF

path Parameters
year
required
integer
Example: 2024

Report year

Responses

Gets expense report PDF

path Parameters
year
required
integer
Example: 2024

Report year

Responses

Health insurance questionnaire

Health insurance questionnaire

Get users unanswered questionnaire

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update questionnaire answer

path Parameters
questionnaire
required
integer
Example: 123

Questionnaire id

Request Body schema: application/json
required

QuestionnaireRequest

health_insurance_obligated
required
string
Enum: "YES" "NO" "OLD_AGE_PENSION" "INSURANCE_ELSEWHERE"

Is user health insurance obligated?

Responses

Request samples

Content type
application/json
{
  • "health_insurance_obligated": "YES"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

OAuth

OAuth

Logs current token session out

Responses

Logs all user's token sessions out

Responses

Utilities

Utilities

Return basic company information for Ukko.fi

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Invoices

Invoices

Returns industry categories and subcategories or searched industries with search parameter

Display a listing of the resource.

query Parameters
search
string

(Optional) search industries by name e.g. /invoices/industries?search=tarkastaja

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Returns a top level category's subcategories, a subcategory or industries

Display the specified resource.

path Parameters
category
required
integer
Example: 100

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gets all user's non- team invoices by category_type and type

path Parameters
category_type
required
string
Example: empty / own / team / partof

Type of Invoices list: empty / own / team / partof

type
required
string
Example: empty/all | paid | unpaid | open | user_action_required

Type of Invoices list: empty/all | paid | unpaid | open | user_action_required

query Parameters
page
integer

Pagination page id

limit
integer
Example: limit=50

Limit per page. Default 50, max 1000

sort
string
Example: sort=created_at | updated_at | invoice_number * | due_date | company_name | contact_person * | total_sum_with_vat | delivery_method | status * | company_name, contact_person

Sort by ascending order, add '-' prefix to get * descending order, ie. -total. To sort by * client_name, use company_name, contact_person

filter[*field_name*]
string
Example: filter[*field_name*]=filter[common_search] = 'foobar', other keys: * common_search * | created_at | updated_at | invoice_number * | due_date | contact_person | company_name * | client_name | delivery_method * | due_date_start (format: YYYY-m-d) * | due_date_end (format: YYYY-m-d) * | search_date_between (format: YYYY-m-d|YYYY-m-d) * either one can be omitted

Sort fields. Array of filtered fields, so * filter[email] = foobar@doobar.com * filter[due_date_start] = 2022-01-01 * filter[due_date_end] = 2022-01-31 * NOTE: This is an AND search

Responses

Response samples

Content type
application/json
{
  • "data": [