1. Symptom or Need

The client is experiencing errors when trying to automate the creation of records in the CRM from external systems. The main symptoms are:

• Receiving an error message when inserting cases: Case insertion API error .
• Cases that are not displayed in the CRM even though the external system reports the shipment.
• Failures in contact assignment or in communication between external systems (via Webhooks/APIs, etc.) and CRM.

2. Context / Scenarios

This incident occurs during the integration of third-party tools (websites, forms, management systems) with Wolkvox CRM. It typically happens when setting up new integrations or renewing security tokens.

3. Answer / Solution

To correct the error, the following four pillars of the API request must be validated and adjusted:

A. Previous validations

• Preliminary Tests: Before scheduling the final integration, perform successful tests using the Postman tool - Insert CRM cases (authenticate with an email account as required) .
• Always compare your request structure with the official Wolkvox API documentation.
• Verify that the token is valid and correctly copied.
• Required Fields: Verify that all fields marked as required in the CRM are present in the API request.
• Confirm that there are no typographical errors in the field names.
• Domain: Ensure that the {{crm_server}} does not include the https:// prefix twice when concatenating the URL.

B. Endpoint Configuration

• Method: The service must be consumed strictly using the POST method.
• URL: Must be correctly constructed using the CRM server: https://{{crm_server}}/server/API/v2/cases/insert.php

( Example : In the variable {{crm_server}}, it should be replaced by the actual CRM domain crm0000.wolkvox.com) .

C. Authentication Configuration (Token)

The access token must be correctly included in the headers:

Required header:

• Key: Wolkvox-Token
• Value: [Token generated from the CRM].

To obtain the token

• Log in to CRM.
• Go to Settings.
• Access the Integrations and Tokens section.
• Copy an existing token or generate a new one depending on the use (internal or external).

D. API Body Structure

To avoid errors when inserting records, the following parameters must be taken into account:

• Format: The API body must be sent in form-data format.
• Field definition: It must be validated that all required fields are correctly defined.

E. Data Validation in Fields

• Operation Field: The exact name of the operation must be included in the API body, as its absence or an error in the name may cause immediate failures in the creation of the case.
• System Default Fields: Values (such as native states or priorities) must be sent in English .
• Custom Fields: These must exactly match the name configured in the CRM cases module (respecting uppercase letters, lowercase letters, spaces and formatting).

4. Possible Causes

• Incorrect or Expired Token: Use of an invalid or incorrectly copied authentication key.
• Incorrect Submission Format: Attempting to send information in JSON or x-www-form-urlencoded instead of form-data .
• Typographical Errors: Discrepancy between the field names in the API and the names configured in the cases module.
• Incorrect Method: Using GET or PUT instead of POST .

5. Recommendations

• Security: Do not share the Wolkvox-Token in public channels or unencrypted chats.