Skip to main content
POST
/
v2
/
organizations
/
{organizationId}
/
directories
/
{directoryId}
/
sources
/
csv-upload
curl -X POST "https://api.orbitsearch.com/v2/organizations/$ORGANIZATION_ID/directories/$DIRECTORY_ID/sources/csv-upload" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -F "file=@/path/to/contacts.csv" \
  -F "idempotency_key=upload-2024-q4-v1"

{
  "source_id": "<string>",
  "directory_id": "<string>",
  "source_status": "<string>",
  "accepted": 123,
  "failed": 123,
  "warnings": 123,
  "is_idempotent": true
}
Uploads a CSV file as a new source into the specified directory. The request uses multipart/form-data. The API synchronously parses, validates, and materializes accepted rows, then returns processing metadata. Large uploads or rows requiring profile resolution may continue processing asynchronously — poll the source status endpoint to track completion.
Uploads are scoped to the directory’s organization. Attempting to upload data to a directory that belongs to a different organization than the authenticated user’s context will be rejected.

​
Path parameters

​
organizationId
string
required
The UUID of the owning organization.
​
directoryId
string
required
The UUID of the target directory. The directory must not be archived.

​
Request body (multipart/form-data)

​
file
file
required
The CSV file to upload.
​
idempotency_key
string
An optional client-generated key. Reusing the same key with the same file makes the request idempotent — the API returns the original response without creating a duplicate source. If you reuse a key with a different file, the request is rejected.

​
Response fields

​
source_id
string
UUID of the newly created (or reused, if idempotent) source.
​
directory_id
string
UUID of the directory this source belongs to.
​
source_status
string
Current processing status of the source. See source status values below.
​
accepted
number
Number of rows accepted and materialized into the directory.
​
failed
number
Number of rows that failed validation and were not imported.
​
warnings
number
Number of rows accepted with non-fatal warnings.
​
is_idempotent
boolean
true if this response was served from a previously completed upload with the same idempotency_key.

​
Source status values

Uploads process in two phases: the synchronous phase materializes as many rows as possible immediately, and any remaining work continues asynchronously under the source record. Poll the status endpoint until source_status reaches a terminal state.
StatusMeaning
pendingUpload received; processing has not started.
processingRows are being validated and materialized.
completedAll rows have been processed. Check accepted, failed, and warnings for results.
failedProcessing encountered an unrecoverable error.
curl -X POST "https://api.orbitsearch.com/v2/organizations/$ORGANIZATION_ID/directories/$DIRECTORY_ID/sources/csv-upload" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -F "file=@/path/to/contacts.csv" \
  -F "idempotency_key=upload-2024-q4-v1"