This article explains how to use the API to list and search companies, download company files, retrieve company contacts and field references, create companies with nested data (addresses, files, attributes, eInvoice details, projects, and contacts), update company data, and delete companies, contacts, or project data.

Get Company

GET

https://api.recman.io/v2/get/?key={{api_key}}
&scope=company&fields=name,visitAddress,tags&userId=13236&page=1

Retrieving data about companies is done through the GET method.

Search parameters

There are multiple ways you can fetch data about companies. You can use one of the search parameters below, and combine different parameters to adjust your fetch requests more precisely:

  • page – page number, 500 companies per page
  • companyId – search for a specific company ID
  • companyIds – search for several company IDs
  • departmentId – retrieve companies that are only connected to a specific department
  • userId – retrieve companies that are only connected to a specific co-worker (user) ID
  • updated – retrieve companies updated later than or equal to a specified date/time 
    (e.g. 2024-01-01 00:00:00)

Company Fields

Fields Description
companyId
integer
Company ID. Required on operations: update, delete
parentCompanyId
integer
Parent company ID
name
string
Name. Required on operation: insert
number
string
Company number (if not defined, the system automatically generates one)
dunsId
integer
D-U-N-S Number – a unique nine-digit business identifier
vatNumber
integer
VAT number
email
string
Email
web
string
Web
officePhone
string
Office phone
invoiceEmail
string
Invoice email
newsletter
boolean
No = 0, Yes = 1. Valid values: 0, 1
linkedin / facebook / twitter
string
Social profile links
employeeCount
integer
Employee count
branchCategoryId
integer
Branch category ID
description
string
Description
notes
string
Notes
invoiceNotes
string
Invoice notes
creditTime
integer
Credit time
created
date-time
Created. Format: Y-m-d H:i:s
updated
date-time
Updated. Format: Y-m-d H:i:s
departmentIds
array of integer
Array of department IDs
userIds
array of integer
Array of user (co-worker) IDs
directions
string
Directions
invoiceSendMethod
string
Valid values: emailWithTrackingLink, emailWithAttachment, print, ehf
invoiceInterval
string
Invoice interval
invoiceFactor
integer
The invoice factor from a company, if added. GET only
creditRating
string
Credit rating
approvedCreditLimit
string
Approved credit limit
recommendedCreditLimit
string
Recommended credit limit
type
string
Valid values: customer, collaborator, supplier, prospect, suspect, competitor, freelance, terminated, ownCompany, notApplicable, formerCustomer, others, lostCustomer, subcontractor
projectData
array of strings
Info of the project data on a company card. GET only. See Insert/Delete Company - projectData
salaryMatrixCategory
array of objects
Info of the company salary matrix categories. GET only
addresses (visitAddress, postAddress, invoiceAddress, deliveryAddress)
object(s)
Nested address objects – see the section below
attributes
object
Nested object – see the section below
file
object
Nested object – see the section below
eInvoice
object
Nested object – see the section below

PARAMS

key {{api_key}} 
required
scope company
required
fields name, visitAddress, tags
required, at least 1 field, comma-separated
userId 13236
required
page 1
optional

Note

You can also look up a company directly by adding companyId as a parameter, for example, fetching fields such as name, number, email, officePhone, invoiceAddress, attributes, file, eInvoice, salaryMatrixCategory and tags.

Get Company File

GET

https://api.recman.io/v2/get/?key={{api_key}}
&scope=companyFile&companyId=2355&fileId=3534674

Retrieving data about a company file is done through the GET method. The response returns the file's fileId, base64 content, extension, and name.

Company File Fields

Fields Description
companyId
integer
Company ID. Required
fileId
integer
File ID. Required

PARAMS

key {{api_key}} 
required
scope companyFile
required
companyId 2355
required
fileId 3534674
required

Get Company Contact

GET

https://api.recman.io/v2/get/?key={{api_key}}&scope=
companyContact&fields=name,email,attributes&companyId=1055074

Retrieving data about company contacts is done through the GET method.

Company Contact Fields

Fields Description
companyContactId
string
Company Contact ID. Required on operation: update, delete
companyId
integer
Company ID. Required on operation: insert
name
string
Name
email
string
Email
departmentId
integer
Department ID
mobilePhone / officePhone / homePhone
string
Phone numbers
notes
string
Notes
newsletter
boolean
No = 0, Yes = 1. Valid values: 0, 1
active
boolean
No = 0, Yes = 1. Valid values: 0, 1
twitter / linkedin / facebook
string
Social profile links
updated / created
date-time
Format: Y-m-d H:i:s
profilePicture
string
Profile picture
attributes
object
Nested attributes object – see Insert Company
userIds
array of integer
List of responsible users

Company Contact Attribute Fields

attributes – object

Sub Fields

Sub Fields Description
attributeId
integer
The ID of the attribute. Required on operation: insert
companyContactAttributeId
integer
The ID of the inserted attribute. Required on operations: update, delete
rating
integer
Valid values: 1, 2, 3, 4, 5
bool
string
0 = False, 1 = True. Valid values: 0, 1
text
string
Text, limited to 255 characters
dropdownId
integer
The ID of the dropdown value
checkboxIds
array of integer
Array of checked checkbox IDs

PARAMS

key {{api_key}} 
required
scope companyContact
required
fields name, email, attributes
required, at least 1 field, comma-separated
companyId 1055074
required

Insert Company

POST

https://api.recman.io/v2/post/

For inserting companies, you will need to use the POST method. The operation must be set to insert and scope to company. It is required to specify the name field for inserting a company.

Note

To get the list of available company attributes, use the Get Company Attributes request (see API: Attributes).

Company Fields

Fields Description
companyId
integer
Company ID. Required on operations: update, delete
departmentId
integer
Company main department ID. Also added to connected departments.
Optional
responsibleUserId
integer
Company responsible co-worker. Also added to connected co-workers.
Optional
countryId
integer
Company country ID.
Optional
parentCompanyId
integer
Parent company ID
name
string
Name. Required on operation: insert
number
string
Company number (auto-generated if not defined)
vatNumber
integer
VAT number
email / web / officePhone / invoiceEmail
string
Contact info
newsletter
boolean
No = 0, Yes = 1. Valid values: 0, 1
linkedin / facebook / twitter
string
Social profile links
employeeCount
integer
Employee count
branchCategoryId
integer
Branch category ID
description / notes / invoiceNotes
string
Free-text fields
creditTime
integer
Credit time
created / updated
date-time
Format: Y-m-d H:i:s
departmentIds
array of integer
Array of department IDs
userIds
array of integer
Array of user IDs
directions
string
Directions
invoiceSendMethod
string
Valid values: emailWithTrackingLink, emailWithAttachment, print, ehf
invoiceInterval
string
Invoice interval
creditRating / approvedCreditLimit / recommendedCreditLimit
string
Credit information
type
string
Valid values: customer, collaborator, supplier, prospect, suspect, competitor, freelance, terminated, ownCompany, notApplicable, formerCustomer, others, lostCustomer, subcontractor
projectData
object
Nested object – see the Insert Company - projectData section below
addresses (visitAddress, postAddress, invoiceAddress, deliveryAddress)
object(s)
Nested address objects – see the section below
attribute
object
Nested object – see the section below
file
object
Nested object – see the section below
eInvoice
object
Nested object – see the section below

Insert Company - Addresses

POST

Address objects contain the following fields:

Fields

visitAddress object
postAddress object
invoiceAddress object
deliveryAddress object

Sub Fields (apply to each of the four address objects above)

Sub Fields Description
address1
string
Address 1
address2
string
Address 2
postalCode
string
Postal code
city
string
City
country
string
Country

Insert Company - File

POST

It's required to specify the companyId or name field for inserting a company file.

Field

file – object

Sub Fields

Sub Fields Description
fileId
integer
Required on operation: delete
name
string
File name, must include extension. Required on operation: insert
extension
string
File extension. Required on operation: insert
created
date-time
Format: "yyyy-mm-dd hh:mm:ss"
base64
string
Base64-encoded file. Required on operation: insert

Insert Company - Attribute

POST

It's required to specify the companyId or name field for inserting a company attribute.

Note

To get the list of available company attributes, use the Get Company Attributes request (see Retrieving Attribute IDs).

Field

attribute – object

Sub Fields

Sub Fields Description
attributeId
string
The ID of the attribute. Required on operation: insert
companyAttributeId
string
The ID of the attribute on the company. Required on operations: update, delete
rating
integer
Valid values: 1, 2, 3, 4, 5
checkboxIds
array of integer
Checkbox IDs, or an array of objects with keys "id" and "rating" to include a rating per checkbox
dropdownId
integer
Dropdown ID
text
string
Text
bool
boolean
Valid values: 0, 1
date
date
Date value. Example format: "2024-10-23"

Insert Company - eInvoice

POST

It's required to specify the name field for inserting a company. eInvoice objects contain the following fields:

Field

eInvoice – object

Sub Fields

Sub Fields Description
companyNumber
string
Company number
invoiceName
string
Invoice name
reference
string
Reference

Insert Company - projectData

POST

The projectData object contains configuration values related to project financial and agreement settings. It is sent as part of the data payload when performing a company insert or update operation.

Field

projectData – object

Sub Fields

Sub Fields Description
holidayPercent
number (float)
Holiday percentage used for project calculations.
Optional
collectiveAgreementId
integer
Collective agreement ID associated with the project.
Optional
defaultInvoice
number (float)
Default invoice value used in project calculations.
Optional
socialCostPercent
number (float)
Social cost percentage applied to the project.
Optional
vatPercent
number (float)
VAT percentage applied to the project.
Optional
invoiceAddition
number (float)
Additional invoice value or percentage.
Optional
factor
number (float)
Calculation factor applied to project values.
Optional
additionFactor
number (float)
Additional calculation factor applied to project values.
Optional

Validation rules

  • Each field in projectData is optional.
  • If a field is present, its value must be numeric – values are cast internally to either float or int.
  • If a non-numeric value is provided, validation fails and an error is returned.

Insert Company Contact

POST

For inserting company contacts, the operation must be set to insert and scope to companyContact. It's required to specify the companyId field.

Company Contact Fields

Fields Description
companyContactId
string
Required on operations: update, delete
companyId
integer
Required on operation: insert
name / email
string
Name or email
departmentId
integer
Department ID
mobilePhone / officePhone / homePhone
string
Phone numbers
notes
string
Notes
newsletter
boolean
No = 0, Yes = 1. Valid values: 0, 1
active
boolean
No = 0, Yes = 1. Valid values: 0, 1
twitter / linkedin / facebook
string
Social profile links
updated / created
date-time
Format: Y-m-d H:i:s
profilePicture
string
Profile picture
userIds
array of integer
List of responsible users

Insert Company Contact - Attribute

POST

It's required to specify companyContactId for inserting a company contact attribute.

Note

To get the list of available company contact attributes, use the Get Company Contact Attributes request (see API: Attributes).

Field

attribute – object

Sub Fields

Sub Fields Description
attributeId
string
The ID of the attribute. Required on operation: insert
companyContactAttributeId
string
The ID of the attribute on the company contact. Required on operations: update, delete
rating
integer
Valid values: 1, 2, 3, 4, 5
checkboxIds
array of integer
Checkbox IDs, or an array of objects with keys "id" and "rating" to include a rating per checkbox
dropdownId
integer
Dropdown ID
text
string
Text
bool
boolean
Valid values: 0, 1

Update Company

POST

https://api.recman.io/v2/post/

For updating companies, the operation must be set to update and scope to company. It's required to specify the companyId field.

Update follows the same field set as Insert Company, with these notes:

  • departmentId – optional; to delete the main department, set to 0.
  • responsibleUserId – optional; to delete the responsible co-worker, set to 0.
  • countryId – optional; to delete the country, set to 0.
  • Nested objects – addresses, attributes, file, eInvoice, and
    projectData – can all be included in an update request the same way they're used on insert.

Delete Company

POST

To delete an existing company, use the POST method with the operation set to delete and scope to company. To delete a company and all of its data, you only need to provide a companyId.

Delete Company - projectData

POST

This endpoint removes the projectData block from a company by company ID.

Fields

Fields Description
companyId
integer
Company ID. 
Required on operation: delete
projectData
boolean
Deletes all project data linked to the company. Valid value: true. 
Required on operation: delete

Behavior

  • When projectData is set to true, all project-related configuration values are removed from the company.
  • Only the projectData section is affected – other company data remains unchanged.
  • Partial deletion is not supported – the entire projectData block is deleted.

Validation rules

  • companyId must be a valid numeric company ID.
  • projectData must be true.
  • If projectData is missing or set to false, no deletion is performed.

Update Company Contact

POST

For updating company contacts, the operation must be set to update and scope to companyContact. It's required to specify the companyContactId field.

Update follows the same field set as Insert Company Contact, with one difference: companyId is required on insert but optional on update.

Note

The attributes field only works for the GET method – attributes cannot be updated through this endpoint. Use the Insert Company Contact - Attribute request instead.

Delete Company Contact

POST

For deleting company contacts, the operation must be set to delete and scope to 
companyContact. It's required to specify the companyContactId field.

Was this article helpful?
0 out of 0 found this helpful