Account Configuration API Methods

register_with_password

This method is only for partners and requires a partner software API key.

It can be used to register new companies through the API with predefined password (if given).

Method returns a RegistrationParamsOutD struct which includes the new user’s API key, the company’s UUID and e-invoice address for receiving. This information can then be automatically updated to the software’s settings so the users do not need to input API key information by themselves.

Important Note

If given user (e-mail) exists, API key will not be returned for security reasons. The user will then get access to the newly created company with the same user account. In this case the password will not be updated.

Read more about companies and settings

Before created account can be used for sending, receiving and activating services, customer authentication must be completed and account has to be verified.

Partner must make sure the user can read and understand the FIX_LINK_PENDING

Input

registration_params - RegistrationParamsIn

Key	Type	Description
vendor_api_key	string	Identifies partner/ERP, mandatory
license_agreement	boolean	Registering company must accept Maventa user agreement, mandatory
company_name	string	Company name, mandatory. Name has to be at least 3 characters long
company_bid	string	Company Business ID/Organization number/VAT number, mandatory
company_email	string	Contact email address for company, mandatory
no_vat	boolean	Deprecated, no need to provide it anymore
receive_invoices	boolean	Select if company wants to receive e-invoices on their account
user_first_name	string	First name, mandatory
user_last_name	string	Last name, mandatory
user_email	string	Email is used as login to portal and needs to be unique, mandatory
user_phone	string	Depending on invoice format, phone number might be visible on invoices
email_activation	boolean	Possibility to skip email activation by link (partner has verified email)
address1	string	Street address, mandatory
address2	string	Additional address
post_code	string	Postal number/code, mandatory
post_office	string	Post office, mandatory
city	string	Registered city, mandatory
state	string	State of address
country	string	Country code for company, mandatory. Allowed countries FI, SE, NO, DK, NL
bank_accounts	BankAccountParamsInArray	Array of BankAccountParamsIn

company_bid

Supported business identifiers types per country are

Country	Type(s)	Description and example
FI	ORGNR, VAT	Finnish organisation number: 1111112-8 or VAT number: FI11111128
SE	ORGNR, SSN	Swedish organisation number: 212000-0142 or social security number: 810101-3608 / 19810101-3608
NO	ORGNR	Norwegian organisation number: 111111111
DK	CVR	Danish unique identifier for a business in Denmark’s Central Business Register: 11111114
NL	KVK	Netherlands Chamber of Commerce number: 00006662
EE	CC, VAT	Estonian Company Code (CC): 11111116 or VAT number: EE100591422
BE	EN	Belgian organisation number: 0111111124
DE	VAT	German VAT number: DE100000008
IT	CFI, IVA	Italian Fiscal Code (CFI): SCRDVD85B24H355B / 12345670017 or VAT number (IVA): IT12345670017
PL	VAT	Polish VAT number: PL1132848704

bank_accounts - BankAccountParamsInArray

Bank accounts are not required for registration and needed only if invoicing format does not include bank account details

Key	Type	Description
account	string	Bank account number
default	boolean	Default bank account flag
iban	string	International Bank Account Number
swift	string	SWIFT code for bank
bank	string	Bank name
user_password	string	If not given, random password will be generated. Minimum length 8 characters.

Return values

Status
OK
ERROR: LICENSE AGREEMENT NEEDS TO BE ACCEPTED
ERROR: COUNTRY CODE INVALID
ERROR: REGISTRATION FAILED, BID ALREADY TAKEN
ERROR: VAT CHECK FAILED
ERROR: POSTAL ADDRESS MISSING REQUIRED INFORMATION
ERROR: USER PASSWORD INVALID
ERROR: USER DETAILS MISSING REQUIRED INFORMATION
ERROR: REGISTRATION FAILED

authorize_companies

Taking a new account into use requires that customer authentication process has been completed. Integrator can use their own customer authentication process or Maventa process provided by Visma Sign.

To complete customer authentication process use this method.
For Finnish companies the mehtod also initiates bank network opening.

Read more about company authentication from company account management.

/v1.1/api/authorize_companies

Input

api_keys - ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Key	Type	Description
auth_email	string	Email to send the Visma Sign request to. The person signing will be strongly authenticated and should have signing rights or power of attorney to represent the company.
company_ids	stringarray	Array of company UUIDs to authorize. Admin user needs to have access to all of the companies given.
locale	string	Locale to use on the sign invitation email, Visma Sign portal, and agreement PDF. Currently supports FI, NO, SE, EN
options	string	Used to provide proof of customer authentication process. Mandatory when partner has own customer authentication process. Expects `authorization_method` key. `authorization_method` - free text for explaining how customer authentication was done as well as giving an identifier(s) that links to event on partners side. E.g. `'{"authorization_method":"We have documents"}'`

Output

Key	Type
return	string

Return values

Key	Type	Message	Description
return	string	OK: Visma Sign document sent	Invitation to sign has been sent to email given in the call. After signing is completed in Visma Sign service company status will change to verified.
return	string	OK: @x companies authorized	Company account has been set to verfied. Account can be used to sending, reseiving and activating services. Happens only when partner has own customer authentication process in use.
return	string	ERROR: COMPANY AUTHORIZATION STATUS MISMATCH	Given company / any of the given companies is already authorized.
return	string	ERROR: VENDOR API KEY CANNOT BE BLANK
return	string	ERROR: VENDOR API KEY INVALID OR DISABLED
return	string	ERROR: EMAIL ADDRESS INVALID
return	string	ERROR: LOCALE NOT SUPPORTED	Given locale (country) is not supported
return	string	ERROR: AMOUNT OF COMPANIES TO SIGN NEEDS TO BE BETWEEN 1 to 50
return	string	ERROR: UNKNOWN ERROR

company_auth_status

To check the company authorization status which tells if company has completed customer authentication process.

Important: In order to start sending, receiving and activating services the company_state needs to be verified.

Read more about company authorization from FIX_LINK_PENDING.

/v1.1/api/company_auth_status

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Output

return (AuthParamsOut)

Key	Type	Description
auth_state	string	Visma Sign request state: `SENT` - Auth request sent to signer but not signed yet, `SIGNED` - Auth request signed, `CANCELLED` - Auth request has been cancelled, e.g. because time has expired, `PENDING` - Auth request created but not sent to signer yet, `ERROR` - Something unexpected has happened
auth_email	string	Email address used to sent the Visma Sign request to
company_state	string	`unverified` / `verified` / `unknown`, unverified companies cannot send, receive or activate services.

Return values

Key	Type	Message	Description
return	string	OK: Visma Sign document sent	Invitation to sign has been sent to email given in the call. After signing is completed in Visma Sign service company status will change to verified.
	string	OK: Company authorized	Company account has been set to verified. Account can be used to sending, receiving and activating services. Happens only when partner has own customer authentication process in use.
	string	OK: No authorization requests	No signing requests have been sent for the company
	string	ERROR: USER NOT FOUND
	string	ERROR: VENDOR API KEY CANNOT BE BLANK
	string	ERROR: VENDOR API KEY INVALID OR DISABLED
	string	ERROR: Visma Sign status check failed
	string	ERROR: UNKNOWN ERROR

configure_company

Used for updating company settings.

Read more about companies and settings

/v1.1/api/configure_company

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

settings (SettingValueArray)

Key	Type	Description
website	string	Website of company, displayed on invoice (depending on sending format)
print_and_send_request	int	Print&Send enabled request (1 = enabled, 0 = disabled)
print_and_send_letter_class	int	Print&Send mail class (1 = priority, 0 = economy). Economy available for FI, SE, NO and NL companies. Others use Priority.
print_and_send_own_pdf	boolean	Use own PDF images in Print&Send.
print_and_send_color	boolean	Print with colors in Print&Send. Color available for FI, SE, NO and NL companies. Others use black & white.
print_attachments	boolean	Enable printing of attachments (true = enabled, false = disabled). The inverse setting, print_attachments_disabled, is also still supported for legacy reason (only one of these parameters should be used).
email_remind_freq	int	Frequency of email reminder’s for open invoices in days (e.g. 2)
email	string	Company email
invoice_email	string	Company invoice email (inbound invoice notifications)
errors_to_user	int	Send invoice relay errors to the user who was used to send the invoice (1 = enabled, 0 = disabled)
error_emails	string	List of comma separated error emails to notify of invoice relay errors. Even if `errors_to_user` is disabled errors are sent to these addresses.
reports	int	E-mail reports activated (0 = disabled, 1 = weekly, 2 = monthly, 3 = daily)
reports_emails	string	List of comma separated email addresses to send reports to
name	string	Name of company, name can’t be empty and minimum length three(3) characters
stop_duplicates	boolean	Prevent (re)sending invoices with the same number
notify_incoming	boolean	Enable/disable email notification of incoming invoice. Will be sent to invoice email if defined, else company email
disable_email	boolean	Enable/disable sending of invoices by email notification. If this is set to true, invoices will only go out as e-invoices or by print. If the only available route for an invoice is email, the invoice will go to error state
notifications_disabled	int	Enable/disable all e-mail notifications to the company email address, (1 = disable, 0 = enable)
internal_receive_via_peppol	boolean	Enable/disable internal receive via Peppol. When enabled, all invoices received from companies inside the home network will be converted to EHF/ PEPPOL BIS, routed through the PEPPOL network and validated towards PEPPOL validation rules. If the invoice fails PEPPOL validation, sender will receive an error message and the invoice will not be delivered.
send_email_attachments	int	With this option we add the invoice image (as PDF) and other attachments on your invoices which get sent by email (total size max 5 megabytes, if larger, recipient is asked to download the attachments from our service using a link provided).
send_invoice_email	int	With this option you can decide how the email invoice is sent out. 0 = Do not send invoice via email. 1 = send all invoice e-mails with attachments (max size 5MB). 2 = Send all invoice e-mail with invoice objections. 3 = Send all invoice e-mails with a link to download PDF. 4 = Send all invoice e-mails with attachments (max size 5MB), all PDF attachments and the invoice image merged together in a single PDF file.
invoice_receiving	int	Enable/disable invoice receiving, (1 = enabled, 0 = disabled).
invoicing_eia	string	Invoicing EIA (Billing information: The delivery method priority is following 1 = eInvoice, 2 = email, 3 = print, if all below values are given. If company prefers invoicing via normal post, invoicing_eia, invoicing_operator and invoicing_email should be left blank).
invoicing_operator	string	Invoicing operator
invoicing_email	string	Invoicing email address
invoicing_street_address1	string	Invoicing postal address
invoicing_street_address2	string	Invoicing additional postal address
invoicing_post_code	string	Invoicing post code
invoicing_post_office	string	Invoicing post office
billing_company_id	string	Company to be set as a billing company
message_from_sender	string	Only for Norway. Write a message to the invoice receivers that is visible in the recipients e-mail.
b2c_fallback	string	Only for B2C NO, can be print or email
b2c_reminder	boolean	Enable/disable B2C NO reminders
contact_person	string	Contact person, email and phone are shown in the email message when invoice is sent by email
contact_email	string	Contact person, email and phone are shown in the email message when invoice is sent by email
contact_phone	string	Contact person, email and phone are shown in the email message when invoice is sent by email
scan_notification_interval	string	Supplier Activation e-mail interval (Use one of the following to activate the service: ”monthly”, ”weekly”, ”daily”, or to disable the service use something else for example ”disabled”)
scan_notification_email	string	E-mail address for Supplier Activation e-mail delivery

print_attachments setting scope: This setting only applies for FI, NO and NL companies. Printing of attachments is by default enabled for NO and NL companies, and disabled for FI companies.

send_email_attachments notes: You will not get an acknowledgement of receiving when sending attachments like for normal email invoices. Also, when sending attachments the recipient’s email box might get full and then emails are not delivered.

send_invoice_email override: The send_invoice_email setting will override send_email_attachments and disable_email settings.

message_from_sender ERP behavior: If your ERP supports their own message to receiver, the message in the ERP will overwrite this message.

Output

Key	Type	Description
return	string

Return values

Key	Type	Message	Description
return	string	OK	Settings saved successfully
		ERROR: NO RIGHTS TO CHANGE SETTINGS	Only admin user can change settings
		ERROR: COULD NOT SAVE COMPANY SETTINGS	Could not save settings for unknown reason
		ERROR: BILLING E-INVOICING DETAILS INCOMPLETE	E-invoicing address is incomplete: e-invoicing address (invoicing_eia) or operator (invoicing_operator) missing
		ERROR: BILLING EMAIL ADDRESS INVALID	Email address is not valid
		ERROR: BILLING INFORMATION INCOMPLETE	Invoicing postal address is incomplete; address, postcode or postoffice is missing
		ERROR: Cannot update billing company for partner accounts	Partner account can’t have billing company
		ERROR: Company cannot be set as its own billing company
		ERROR: Company is set as a billing company for another company
		ERROR: Company is linked to an accounting office, billing company cannot be changed
		ERROR: Invalid billing_company_id
		ERROR: VAT NUMBER CANNOT BE SET TO BLANK
		ERROR: INVOICE RECEIVING VALUE IS INVALID
		ERROR: INVOICE RECEIVING CANNOT BE DISABLED WHEN SCAN ACCOUNT IS OPEN
		ERROR: B2C REMINDER INVALID

show_company_configuration

Shows current company configuration and available key/value pairs.

Read more about companies and settings

/v1.1/api/show_company_configuration

Input

api_keys — ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Output

return — SettingValuesOutArray (array of SettingValuesOut)

Key	Type	Description
status	string
settings	SettingValueArray	Array of SettingValue

Key	Type	Description
website	string	Website of the company
print_and_send_request	int	Print&Send request sent (1=yes,0=no)
print_and_send_letter_class	integer	Print&Send mail class (1 = Priority, 0 = Economy)
print_and_send_own_pdf	boolean	Use own PDF images in Print&Send (true/false)
print_and_send_color	boolean	Print with colors in Print&Send (true/false)
print_attachments	boolean	Shows if printing of attachments is disabled (false) or enabled (true)
print_attachments_disabled	boolean	Shows if printing of attachments is disabled (true) or enabled (false)
email_remind_freq	int	Frequency of email reminder’s for open invoices in days (e.g. 2)
email	string	Company email
invoice_email	string	Company invoice email (inbound invoice notifications)
errors_to_user	int	Send invoice relay errors to users or just error email? (1=yes,0=no)
error_emails	string	E-mail address for invoice errors
reports	int	E-mail reports activated (0 = no, 1 = weekly, 2 = monthly, 3 = daily)
reports_emails	string	E-mail for send reports
name	string	Name of the company
bid	string	Business ID, VAT, organization number etc.
country	string	Country of the company
stop_duplicates	boolean	Prevent (re)sending invoices with the same number (true/false)
notify_incoming	boolean	E-mail notification of incoming invoice (true/false)
disable_email	boolean	Sending of invoices by email notification. (true/false)
notifications_disabled	int	Enable/disable all e-mail notifications to the company email address, (1=disable, 0=enable)
internal_receive_via_peppol	boolean	Internal receiving via Peppol (true/false)
send_email_attachments	int	Send the invoice image as attachment (true/false)
send_invoice_email	int	Shows which email invoice sending method is in use. 0 = Do not send invoice via email. 1 = send all invoice e-mails with attachments (max size 5MB). 2 = Send all invoice e-mail with invoice objections. 3 = Send all invoice e-mails with a link to download PDF. 4 = Send all invoice e-mails with attachments (max size 5MB), all PDF attachments and the invoice image merged together in a single PDF file. Note! This setting will override send_email_attachments and disable_email settings
invoice_receiving	int	Invoice receiving status, (1=enabled, 0=disabled)
invoicing_eia	string	invoicing EIA
invoicing_operator	string	invoicing operator.
invoicing_email	string	invoicing email address.
invoicing_street_address1	string	invoicing postal address.
invoicing_street_address2	string	invoicing additional postal address.
invoicing_post_code	string	invoicing post code.
invoicing_post_office	string	invoicing post office.
billing_company_id	string	Billing company id that handles the invoicing of the company
print_and_send_enabled	string	Print&Send enabled (true/false)
vat_number	string	Is the Norwegian company VAT registered, returns the VAT number
default_receive_vendor_api_key	string	Default vendor API key for receiving
default_send_vendor_api_key	string	Default vendor API key for sending
peppol_id	string	Peppol ID for the company
bank_send	string	Is the bank network connection open or not (true/false)
marketing_on_invoice	string	Electronic invoicing instruction page/marketing page enabled (true/false)
message_from_sender	string	Message from sender that is visible in the e-mail invoices
scan_return_email	string	Email address for returned scan material if scan account exists (active or disabled)
scan_return_postal	string	Postal address for returned scan material if scan account exists (active or disabled)
b2c_fallback	string	Shows B2C NO fallback route . (print/email)
b2c_reminder	boolean	Shows if B2C NO reminders are enabled or disabled. (true/false)
contact_person	string	Shows contact person that is shown in the email message when invoice is sent by email
contact_email	string	Shows contact email that is shown in the email message when invoice is sent by email
contact_phone	string	Shows contact phone that is shown in the email message when invoice is sent by email
scan_notification_interval	string	Supplier Activation e-mail interval (Service is enabled if one of the following is returned: ”monthly”, ”weekly”, ”daily” or disabled if ”disabled”
scan_notification_email	string	E-mail address for Supplier Activation e-mail delivery

Return values

Key	Type	Message	Description
status	string	OK

company_show

Used for showing current company information.

Read more about companies and settings

/v1.1/api/company_show

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Output

return (CompanyParamsOut)

Key	Type	Description
email	string
status	string
name	string
maventa_id	string
bid	string
id	string
country	string

Return values

Key	Type	Message	Description
status	string	OK
		ERROR: COMPANY ACCOUNT IS LOCKED	Company’s account is locked and can’t be used
		ERROR: USER NOT FOUND
		ERROR: UNKNOWN ERROR

company_invoice_receiving

Enable/disable receiving of invoices. Read more about invoice receiving

/v1.1/api/company_invoice_receiving

Input

api_keys - ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Key	Type	Description
receive	boolean

FIX_IMAGE_PENDING

Output

Key	Type	Description
return	string

FIX_IMAGE_PENDING

Return values

Key	Type	Message
return	string	OK
		ERROR: USER NOT FOUND
		ERROR: INVOICE RECEIVING CANNOT BE DISABLED WHEN SCAN ACCOUNT IS OPEN
		ERROR: UNKNOWN ERROR

enable_operator

Enables operator connections that require it done separately. Currently needed for PEPPOL receiving.

/v1.1/api/enable_operator

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

operator_struct (OperatorStruct)

Key	Type	Description
operator_id	string	Operator name/code. For peppol network use PEPPOL
enabled	boolean	Enable or disable. When set to false, will remove both invoice and credit note receiving
sender_id	string	Sender ID if needed (not needed for PEPPOL)
recipient_id	string	Recipient ID if needed (not needed for PEPPOL)

Output

Key	Type	Description
status	string

Return values

Key	Type	Message
return	string	OK
		ERROR: USER NOT FOUND
		ERROR: [OPERATOR] CANNOT BE ENABLED WHILE RECEIVING INVOICES IS DISABLED

company_list

Used for listing all the companies user has access to.

/v1.1/api/company_list

Input

api_keys — ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Output

return — CompanyParamsOutArray (Array of CompanyParamsOut)

Key	Type	Description
email	string
status	string
user_api_key	string
name	string
maventa_uuid	string
maventa_id	string
bid	string
id	string
country	string

Return values

Key	Type	Message
status	string	OK
		ERROR: USER NOT FOUND
		ERROR: UNKNOWN ERROR

update_logo

Used for uploading company logo to Maventa for PDF template output when PDF template is not generated in ERP.

Supported formats: Most image formats are supported, but not PDF. JPEG or PNG is preferred.

Note: PNG with transparency is not supported.

Read more about logo usage from the printing guide

/v1.1/api/update_logo

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

company_logo_params (CompanyLogoParams)

Key	Type	Description
logo	base64	Company logofile
logo_h	int	deprecated, not used anymore
logo_w	int	deprecated, not used anymore
logo_x	int	deprecated, not used anymore
logo_y	int	deprecated, not used anymore

FIX_IMAGE_PENDING

Output

Key	Type	Description
return	string

FIX_IMAGE_PENDING

Return values

Key	Type	Message	Description
return	string	OK
		ERROR: COULD NOT UPDATE LOGO	File format not supported
		ERROR: COULD NOT SAVE SETTINGS

remove_logo

Removes uploaded logo for company.

Read more about logo usage from the printing guide

/v1.1/api/remove_logo

Input

api_keys ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Output

Key	Type	Description
return	string

Return values

Key	Type	Message	Description
status	string	OK
		ERROR: COULD NOT SAVE SETTINGS	Logo could not be removed

token_login

Returns a URL to access the web UI without needing to login.

Currently supports service parameter: FI_BANK_NETWORK_OPEN for opening Finnish bank network and COMPANY_SETTINGS for accessing setting page for given company.

Read more about companies and settings

/v1.1/api/token_login

Input

api_keys - ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key
service	string

Output

Key	Type	Description
return	string

Return values

Key	Type	Message	Description
return	string	https://…	Successfull request, URL can be accessed
		ERROR: No rights to sign bank agreements	User API key is for normal user
		ERROR: Only available for Finnish companies	Company uuid is for none Finnish company
		ERROR: Bank agreement already active	Company has already bank network connection
		ERROR: Bank agreement already pending	Company has already order the bank network opening

link_vendor_api_key

Link company account to a vendor_api_key like company was registered using API with that vendor_api_key.

Input

api_keys ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Output

Key	Type	Description
return	string	“OK” or “ERROR: …”

Return values

Key	Type	Message
return	string	OK
		ERROR: NO VENDOR API KEY GIVEN
		ERROR: COULD NOT SAVE CHANGES

unlink_vendor_api_key

Unlinks company from vendor_api_key if company stops using ERP.

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Output

Key	Type	Description
return	string	“OK” or “ERROR: …”

Return values

Key	Type	Message
return	string	OK
		ERROR: COMPANY NOT ASSIGNED TO GIVEN VENDOR API KEY

list_vendor_inbound_invoices

Allows vendor to list inbound invoices of companies linked to their vendor_api_key.

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Output

items (InboundInvoiceList)

Key	Type	Description
status	string	Status
items	InboundInvoiceListItemArray	Array of InboundInvoiceListItem

items (InboundInvoiceListItemArray)

Key	Type	Description
invoice_id	string	Unique ID of invoice, to be used in method inbound_invoice_show
recipient_id	string	company_uuid of recipient company
timestamp	string	Timestamp when invoice was received on account, is what is checked against with the list methods timestamps

Return values

Key	Type	Message
status	string	OK
		ERROR: TIMESTAMP START FORMAT ERROR
		ERROR: TIMESTAMP END FORMAT ERROR
		ERROR: NO RIGHTS TO VENDOR API KEY

user_create_e

Used for creating a new or adding an existing user to a company.

After a new user creation an activation message will be sent to the given email address. This message will also include a randomly generated password for the user.

If on the user_create_e call either of the parameters notifications_disabled or emails_disabled is set as false, the account will not be usable until the user account is activated via accessing a link in the email.

If on the user_create_e call both parameters notifications_disabled and emails_disabled are set to true, the account will be activated immediately and no email activation is required. This is the recommended process for API only integrations.

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

user_params (UserParamsIn)

Key	Type	Description
email	string	Email address, needs to be unique
user_role	string	Role can be ADMIN or USER. ADMIN has access to company settings etc.
first_name	string	First name for user, mandatory
last_name	string	Last name of user, mandatory
phone	string	Phone number
notifications_disabled	boolean	If set to true, user will not receive e-mail notifications for their invoices e.g. when receiver accepts invoice etc. (only applies inside Maventa network)
emails_disabled	boolean	If set to true, user will not receive any e-mail notifications e.g. invoice send errors and such.

Output

Key	Type
return	string

Return values

Key	Type	Message	Description
return	string	OK: USER ADDED	When an existing user added to the company. The API key is not returned here for security reasons
		36 char uuid	API key for a new user
		ERROR: NO RIGHTS TO ADD USERS	Only admin user can add new users
		ERROR: @errormessage	Error message with validation errors for the user

user_list

Used for listing your company’s users.

/v1.1/api/user_list

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

FIX_XML_REQUEST_PENDING

Output

return (UserParamsOutArray - Array of UserParamsOut)

Key	Type
status	string
email	string
user_role	string
first_name	string
last_name	string
phone	string
id	string

FIX_XML_RESPONSE_PENDING

Return values

Key	Type	Message
status	string	OK
		ERROR: UNKNOWN ERROR

user_show

Used for showing information about a specific user.

/v1.1/api/user_show

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Key	Type	Description
id	string	Optional. Id of the user whuich information to return. If parameter is not given, information of the authenticating user will be returned

Output

return (UserParamsOut)

Key	Type
status	string
email	string
user_role	string
first_name	string
last_name	string
phone	string
id	string

Return values

Status	Type	Message
OK	string	Success
ERROR: NO RIGHTS TO USER	string	User has no rights
ERROR: UNKNOWN ERROR	string	An unexpected error occurred

user_update_e

Used for updating users details on your company account. You cannot update a user’s email address through the API.

/v1.1/api/user_update_e

Input

api_keys ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Key	Type
id	string

user_params UserParamsIn

Key	Type	Description
email	string
user_role	string
first_name	string
last_name	string
phone	string
notifications_disabled	boolean	If set to true, user will not receive e-mail notifications for their invoices e.g. when receiver accepts invoice etc. (only applies inside Maventa network)
emails_disabled	boolean	If set to false, user will not receive any e-mail notifications e.g. invoice send errors and such.

Output

Key	Type	Description
return	string

Return values

Key	Type	Message	Description
return	string	OK: USER SAVED	User updated successfully
		ERROR: USER COULD NOT BE SAVEDS	User could not be saved for some reason
		ERROR: NO RIGHTS TO USER	Only the user in question or an admin can update user information
		ERROR: USER NOT FOUND	User with given user_id was not found

user_delete

Used for deleting user from your company account. You cannot delete your own account.

/v1.1/api/user_delete

Input

api_keys ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Key	Type	Description
id	string

FIX_INCLUDE_PENDING

Output

Key	Type	Description
return	string

FIX_INCLUDE_PENDING

Return values

Key	Type	Message	Description
status	string	OK: USER DELETED FROM COMPANY	User deleted successfully
		ERROR: NO RIGHTS TO USER	Only an admin can delete users
		ERROR: USER NOT FOUND	User with given user_id was not found
		ERROR: CANNOT DELETE YOURSELF	User cannot delete himself
		ERROR: COULD NOT DELETE USER	User could not be deleted for somea reason

postal_address_create

Used for adding a postal address for the company.

/v1.1/api/postal_address_create

Input

api_keys ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

company_postal PostalAddressParamsIn

Key	Type
default	boolean
company_name	string
lang	string
state	string
post_code	string
post_office	string
phone	string
address1	string
gsm	string
address2	string
country	string
city	string
fax	string

Output

Key	Type
return	string

Return values

Key	Type	Message	Description
status	string	OK: POSTAL ADDRESS SAVED	Postal address created successfully
		ERROR: @errormessage	Error message with validation errors for the postal address
		ERROR: COMPANY ALREADY HAS ADDRESS INFORMATION FOR @country / @lang	Company can only have one postal address for each country/language
		ERROR: COUNTRY CODE INVALID	Given country code does not exist or is not supported

postal_address_list

Used for listing all the company’s postal addresses.

/v1.1/api/postal_address_list

Input

api_keys ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

FIX_EXAMPLE_PENDING

Output

return PostalAddressParamsOutArray (Array of PostalAddressParamsOut)

Key	Type
status	string
default	boolean
lang	string
state	string
post_code	string
phone	string
post_office	string
address1	string
gsm	string
city	string
country	string
id	string
address2	string
fax	string

FIX_EXAMPLE_PENDING

Return values

Key	Type	Message
status	string	OK
		ERROR: UNKNOWN ERROR

postal_address_show

Used displaying information for a specific postal address.

/v1.1/api/postal_address_show

Input

api_keys ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Key	Type	Description
id	string	ID of the postal address to show. Postal address IDs can be fetched with the postal_address_list method.

Output

return PostalAddressParamsOut

Key	Type
status	string
default	boolean
lang	string
state	string
post_code	string
phone	string
post_office	string
address1	string
gsm	string
city	string
country	string
id	string
address2	string
fax	string

Return values

Key	Type	Message
status	string	OK
		ERROR: POSTAL ADDRESS NOT FOUND OR NO RIGHTS
		ERROR: UNKNOWN ERROR

postal_address_update

Used for updating an existing postal address.

/v1.1/api/postal_address_update

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Key	Type	Description
id	string	ID of the postal address to update. If set to nil, will default to the default address. Postal address IDs can be fetched with the postal_address_list method.

company_postal (PostalAddressParamsIn)

Key	Type	≤≤
default	boolean
company_name	string
lang	string
state	string
post_code	string
post_office	string
phone	string
address1	string
gsm	string
address2	string
country	string
city	string
fax	string

Output

Key	Type
return	string

Return values

Key	Type	Message	Description
status	string	OK: POSTAL ADDRESS SAVED	Postal address updated successfully
		ERROR: POSTAL ADDRESS NOT FOUND OR NO RIGHTS	Given postal_address_id not found for current company
		ERROR: COUNTRY CODE INVALID	Given country code does not exist or is not supported
		ERROR: COMPANY ALREADY HAS ADDRESS INFORMATION FOR @country / @lang	Company can only have one postal address for each country and language pair
		ERROR: @errormessage	Error message with validation errors for the postal address

postal_address_delete

Used for deleting postal address.

/v1.1/api/postal_address_delete

Input

api_keys ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Key	Type	Description
id	string

Output

Key	Type	Description
return	string

Return values

Key	Type	Message	Description
status	string	OK: POSTAL ADDRESS DELETED	Postal address deleted successfully
		ERROR: COULD NOT DELETE POSTAL ADDRESS	Postal address could not be deleted
		ERROR: POSTAL ADDRESS NOT FOUND OR NO RIGHTS	Given postal_address_id not found for current company

scan_account_order

Open a new scan account for your company or for updating already existing one when called again. If first time ordering is successful, returns the scan address where suppliers send their invoices (paper or email).

It is very important to give suppliers the full returned scanning address. Also note that you cannot open a scan account if your account has receiving e-invoices turned off.

When called again for already existing scan account, will return OK: RETURN ADDRESS UPDATED

User accepts the pricing including scan minimum fee when opening the account.

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

return_address (ScanAddress)

Your company’s postal address. Given to scan provider so they can return mail which is not proper invoices that have been sent to scanning address (like contracts etc.)

Key	Type	Description
name	string
address1	string	either address1 or address2 mandatory
address2	string
post_code	string	mandatory
post_office	string	mandatory
state	string
country	string	mandatory
email	string	for sending notifications in error situations, mandatory

Output

return (ScanAccountParamsOut)

Key	Type	Description
status	string	Status
address	ScanAddress	Company’s scanning address (i.e the address suppliers should use when sending invoices)

address (ScanAddress)

Key	Type	Description
name	string
address1	string	For sending non-invoice material that has been sent to your scanning address and cannot be sent to your return email address (e.g. packages)
address2	string
post_code	string
post_office	string
state	string
country	string
email	string	For sending non-invoice material that has been sent to your scanning address

Return values

Key	Type	Message	Description
status	string	OK	Scan account opened, return value includes address information of the new scan account
		OK: RETURN ADDRESS UPDATED
		ERROR: REGISTRATION FAILED	Unexpected error, contact support
		ERROR: SCAN ACCOUNT EXISTS	Company already has a scan account, you can have only one
		ERROR: SCAN ACCOUNT CURRENTLY AVAILABLE FOR FINNISH, NORWEGIAN, SWEDISH, DANISH AND DUTCH COMPANIES ONLY
		ERROR: RETURN ADDRESS EMPTY OR INVALID
		ERROR: RECEIVING INVOICES NOT ENABLED ON ACCOUNT
		ERROR: INVALID SCAN RETURN EMAIL DOMAIN
		ERROR: SCAN ACCOUNT ACTIVATION FAILED MAVENTA SUPPORT WILL CONTACT YOU TO RESOLVE THE ISSUE	The scan account activation has failed and you will be contacted to help resolve the issue an activate the account.
		ERROR: SCAN ACCOUNT ACTIVATION IS PENDING	The scan account is pending activation before it will be available to use.
		ERROR: COMPANY DATA MISSING	In order to activate the scan account please make sure your company address information is complete (address, postal code, city, email) and you have filled in the return addresses.
		ERROR: UNKNOWN ERROR

scan_account_show

Show company’s scanning address (i.e the address suppliers should use when sending invoices).

Important! It is very important to give suppliers the full returned scanning address.

Input

api_keys - ApiKeys

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Output

return - ScanAddress

Key	Type	Description
status	string	Status
name	string
address1	string
address2	string
post_code	string
post_office	string
state	string
country	string
email	string	For sending PDFs per email for interpretation

Return values

Key	Type	Message
status	string	OK
		ERROR: SCAN ACCOUNT DISABLED
		ERROR: SCAN ACCOUNT NOT FOUND
		ERROR: USER NOT FOUND

scan_account_disable

Close scan account.

Input

api_keys (ApiKeys)

Key	Type	Description
company_uuid	string	UUID of current company
user_api_key	string	User API key
vendor_api_key	string	Partner software API key

Output

Key	Type	Description
return	string

Return values

Key	Type	Message
status	string	OK
		ERROR: Scan account not found
		ERROR: Multiple scan accounts found, please contact support
		ERROR: Unexpected error, contact customer support