Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.orbitsearch.com/llms.txt

Use this file to discover all available pages before exploring further.

Sources are the feeds that populate a directory’s searchable corpus. You upload a CSV file, the API validates and processes each row, and the accepted records become searchable people inside that directory. Uploads are incremental: each new upload creates an additional source rather than replacing the existing data, so multiple CSV uploads and imported connection sources all contribute to the same searchable corpus. Once you have uploaded data, use the readiness endpoint to confirm the directory is ready before running searches.
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.

​
Upload a CSV source

POST /v2/organizations/:organizationId/directories/:directoryId/sources/csv-upload 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.

​
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.
curl -X POST "$API_BASE/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 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.

​
List sources

GET /v2/organizations/:organizationId/directories/:directoryId/sources Returns all sources that have been uploaded to a directory.

​
Path parameters

​
organizationId
string
required
The UUID of the owning organization.
​
directoryId
string
required
The UUID of the directory whose sources you want to list.

​
Get a source

GET /v2/organizations/:organizationId/directories/:directoryId/sources/:sourceId Returns full metadata for a single source, including row counts and validation details.

​
Path parameters

​
organizationId
string
required
The UUID of the owning organization.
​
directoryId
string
required
The UUID of the directory.
​
sourceId
string
required
The UUID of the source to retrieve.

​
Get source status

GET /v2/organizations/:organizationId/directories/:directoryId/sources/:sourceId/status Returns the current processing status for a source. Use this endpoint to poll after a CSV upload until the source reaches a terminal state.

​
Path parameters

​
organizationId
string
required
The UUID of the owning organization.
​
directoryId
string
required
The UUID of the directory.
​
sourceId
string
required
The UUID of the source to check.

​
Update source status

PATCH /v2/organizations/:organizationId/directories/:directoryId/sources/:sourceId/status Updates the status of a source, for example to retry a failed upload.

​
Path parameters

​
organizationId
string
required
The UUID of the owning organization.
​
directoryId
string
required
The UUID of the directory.
​
sourceId
string
required
The UUID of the source to update.

​
Check directory readiness

GET /v2/organizations/:organizationId/directories/:directoryId/readiness Returns whether the directory is ready to receive search queries. A directory is ready when at least one source has completed processing and its people are indexed. Check readiness before running your first search after an upload.

​
Path parameters

​
organizationId
string
required
The UUID of the owning organization.
​
directoryId
string
required
The UUID of the directory to check.

​
Personal connection imports

Personal connections are stored in the user’s Personal Connections directory, which is a special connections-type directory auto-created for every user. You can import connections and then treat them as a searchable source like any other directory.

​
Start an import

POST /v2/social/connections/import Starts an asynchronous import job that processes connection data and materializes records into your Personal Connections directory. Returns a jobId you use to track progress.

​
Check import status

GET /v2/social/connections/imports/:jobId Returns the current status and progress of a connection import job.
​
jobId
string
required
The ID of the import job returned by the start-import endpoint.

​
Resume a paused import

POST /v2/social/connections/imports/:jobId/resume Resumes a connection import job that is in a paused state.
​
jobId
string
required
The ID of the paused import job.

​
List personal connections

GET /v2/social/connections Returns the list of personal connections that have been imported.

​
Upload and search workflow

1

Upload a CSV

Send a POST to the csv-upload endpoint with your file. Note the source_id in the response.
curl
curl -X POST "$API_BASE/v2/organizations/$ORGANIZATION_ID/directories/$DIRECTORY_ID/sources/csv-upload" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -F "file=@contacts.csv"
2

Poll source status

Repeat GET requests to the source status endpoint until source_status is completed or failed.
curl
curl "$API_BASE/v2/organizations/$ORGANIZATION_ID/directories/$DIRECTORY_ID/sources/$SOURCE_ID/status" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
3

Check directory readiness

Confirm the directory is ready to search before issuing your first query.
curl
curl "$API_BASE/v2/organizations/$ORGANIZATION_ID/directories/$DIRECTORY_ID/readiness" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
4

Run a directory-scoped search

Use your organization API key to run a smart search scoped to the directory.
curl
curl -X POST "$API_BASE/v2/social/profiles/searches/smart" \
  -H "Authorization: Bearer $ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "founders in sf",
    "numUsers": 10,
    "searchScope": { "type": "directory", "directoryId": "DIRECTORY_UUID" }
  }'