API Docs
Voxbi Cockpit APIs
All endpoints

Update parsing settings for an import (user)

Updates the parsing settings for an incomplete import. Send only the keys you want to change. Only an incomplete import can be updated (otherwise 409).

HTTP: bearerAuth

User bearer token. Default authentication for customer-facing endpoints. Obtain a token by calling POST /login with your credentials, then send it on every subsequent request as Authorization: Bearer <token>. The token inherits the permissions and PBX scope of the authenticated user.

HTTP Authorization Scheme
bearer
Bearer format
Bearer <token>
id path · string · uuid *
Import identifier
accept header · string
example: application/json

Request body · required

Request schema
header_row_positioninteger | null
1-based row that holds the column headers.
≥ 1
sheet_indexinteger | null
0-based sheet to read (Excel files).
≥ 0
delimiterstring | null
CSV field delimiter.
length: 0–5
enclosurestring | null
CSV field enclosure character.
length: 0–5
input_encodingstring | null
Character encoding of the file; must be a supported encoding.
length: 0–50
skip_on_errorboolean
When true, invalid rows are skipped instead of failing the import.
notify_owner_by_emailboolean
Email you once the import finishes (completed or failed).
webhook_urlstring | null · uri
Public https URL. Import lifecycle events are POSTed here as JSON, signed with an X-Voxbi-Signature (HMAC-SHA256) header. Typically used to drive live in-app notifications: relay each event to the signed-in user over your realtime channel (no polling); query params in the URL are echoed back so you can route it. Private, loopback and non-https URLs are rejected. Send null to clear.

Responses

OK. The updated import resource (unwrapped). It carries the setting values just set (header_row_position, notify_owner_by_email, ...).
Response schema
id*string · uuid
Import identifier
read-only
example: 550e8400-e29b-41d4-a716-446655440000
status*string
Current stage of the import lifecycle
enum: incomplete pending processing completed completed_with_errors failed
example: incomplete
file_typestring | null
Detected type of the uploaded file
enum: csv xls xlsx null
example: csv
records_countinteger
Number of contacts imported (populated once processed)
example: 42
errors_countinteger
Number of rows that failed to import
example: 3
can_confirmboolean
True when the import is still incomplete and has a saved mapping, so it may be confirmed
example: 1
header_row_positioninteger | null
1-based row holding the column headers.
example: 1
sheet_indexinteger | null
0-based sheet to read (Excel files).
delimiterstring | null
CSV field delimiter (auto-detected when null).
enclosurestring | null
CSV field enclosure character.
example: "
input_encodingstring | null
Character encoding of the file.
example: UTF-8
skip_on_errorboolean
When true, invalid rows are skipped instead of failing the import.
example: 1
notify_owner_by_emailboolean
Whether the owner is emailed once the import finishes.
example:
webhook_urlstring | null · uri
Client webhook that receives lifecycle events.
mappingsarray<object>
The saved column mapping, in the same shape it was submitted (empty until one is saved).
fieldstring
example: name1
columninteger
example: 0
subfieldsarray<object>
namestring
example: type
valuestring
example: mobile
created_atstring | null · date-time
read-only
example: 2026-01-15T09:30:00Z
started_atstring | null · date-time
When background processing began
read-only
example: 2026-01-15T09:31:00Z
completed_atstring | null · date-time
When background processing finished
read-only
example: 2026-01-15T09:31:45Z
recordsarray<object>
Imported contacts. Only present when requested via `?include=records`.
model_idstring · uuid
Id of the created / updated contact
example: 550e8400-e29b-41d4-a716-446655440010
is_newboolean
True when a new contact was created, false when an existing one was updated
example: 1
was_trashedboolean
True when a soft-deleted contact was restored by the import
example:
errorsarray<object>
Row-level failures. Only present when requested via `?include=errors`.
rowinteger
1-based row number in the uploaded file
example: 7
attributestring | null
The field that failed validation, when applicable
example: email
messagesarray<string>
[]string
row_dataobject
The offending row as read from the file
Free-form object
Authorization Token Missing. This error is returned when the authorization token is missing.
Response schema
errorstring
Error message
example: Authorization Token is missing
Data Not Found. This error is returned when the requested data is not found.
Response schema
messagearray<string>
[]string
Conflict. The import is no longer in a state that allows this action (for example, it has already been submitted for processing). Only an `incomplete` import can be configured or confirmed.
Response schema
messagestring
Unprocessable Parameters. This error is returned when a parameter is not valid.
Response schema
messagestring
example: The given data was invalid.
errorsobject
filterarray<string>
[]string
sortarray<string>
[]string
pagearray<string>
[]string
per_pagearray<string>
[]string
Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue.
Response schema
messagestring
exceptionstring
Only present in non-production environments.
filestring
Only present in non-production environments.
lineinteger
Only present in non-production environments.
put https://cockpit.voxbi.com/api/v1/contacts/imports/{id}/settings
Base URL
Request sample 
curl -X PUT 'https://cockpit.voxbi.com/api/v1/contacts/imports/{id}/settings' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"header_row_position":1,"delimiter":",","input_encoding":"UTF-8","skip_on_error":true,"notify_owner_by_email":true,"webhook_url":"https://hooks.example.com/imports"}'
const response = await fetch('https://cockpit.voxbi.com/api/v1/contacts/imports/{id}/settings', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "header_row_position": 1,
    "delimiter": ",",
    "input_encoding": "UTF-8",
    "skip_on_error": true,
    "notify_owner_by_email": true,
    "webhook_url": "https://hooks.example.com/imports"
}),
});

const data = await response.json();
console.log(data);
import requests

response = requests.put('https://cockpit.voxbi.com/api/v1/contacts/imports/{id}/settings',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "header_row_position": 1,
    "delimiter": ",",
    "input_encoding": "UTF-8",
    "skip_on_error": true,
    "notify_owner_by_email": true,
    "webhook_url": "https://hooks.example.com/imports"
}
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'PUT',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
        'content' => '{
    \"header_row_position\": 1,
    \"delimiter\": \",\",
    \"input_encoding\": \"UTF-8\",
    \"skip_on_error\": true,
    \"notify_owner_by_email\": true,
    \"webhook_url\": \"https://hooks.example.com/imports\"
}',
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/contacts/imports/{id}/settings', false, $context);
$data = json_decode($response, true);
print_r($data);
Sample request
{ … }
"header_row_position": 1,
"delimiter": ",",
"input_encoding": "UTF-8",
"skip_on_error": true,
"notify_owner_by_email": true,
"webhook_url": "https://hooks.example.com/imports"
}
No example for this status.
{ … }
"error": "Authorization Token is missing"
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57
{ … }
"message": [ … ]
"Data not found"
]
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57
{ … }
"message": "This import has already been submitted."
}
Content-Type string
example: application/json
{ … }
"errors": { … }
"filter": [ … ],
"The filter field must be an array."
],
"sort": [ … ],
"The sort field must be a string."
],
"page": [ … ],
"The page field must be an integer."
],
"per_page": [ … ]
"The per page field must be an integer."
]
}
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57
{ … }
"message": "Server Error"
}