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=1Retrieving 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 |
|
| 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=3534674Retrieving 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=1055074Retrieving 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 |
|
| 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
projectDatais 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, andprojectData– 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
projectDatais set totrue, all project-related configuration values are removed from the company. - Only the
projectDatasection is affected – other company data remains unchanged. - Partial deletion is not supported – the entire
projectDatablock is deleted.
Validation rules
-
companyIdmust be a valid numeric company ID. -
projectDatamust betrue. - If
projectDatais missing or set tofalse, 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.