API Docs
Voxbi Cockpit APIs
All endpoints

Confirm and start an import (user)

Confirms an incomplete import and queues it for background processing. The import must have a saved mapping (can_confirm: true) or a 422 is returned. On success the import moves to pending and is processed asynchronously; poll the get-import endpoint for the final status and counts. Only an incomplete import can be confirmed (otherwise 409).

Imports created in the Cockpit admin are not drivable here, and an import started via this API cannot be completed from the Cockpit admin: the two flows are kept separate.

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

Responses

OK. The import resource (unwrapped), now `pending`.
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.
post https://cockpit.voxbi.com/api/v1/contacts/imports/{id}/confirm
Base URL
Request sample 
curl -X POST 'https://cockpit.voxbi.com/api/v1/contacts/imports/{id}/confirm' \
  -H 'Authorization: Bearer YOUR_TOKEN'
const response = await fetch('https://cockpit.voxbi.com/api/v1/contacts/imports/{id}/confirm', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
});

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

response = requests.post('https://cockpit.voxbi.com/api/v1/contacts/imports/{id}/confirm',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'}
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/contacts/imports/{id}/confirm', false, $context);
$data = json_decode($response, true);
print_r($data);
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"
}