In this article, you can read about how to create a new company and attach nested data such as addresses, files, attributes, eInvoice details, project data, and company contacts via the API.
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 Retrieving Attribute IDs).
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 | |
| 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 Retrieving Attribute IDs).
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 |
What's next
Continue with Companies: Retrieving Company, Company File, and Company Contact Data via the API for lookup and search options, or Companies: Updating and Deleting Companies, Contacts, and Project Data via the API to modify or remove existing data.