Skip to main content
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.
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 "https://api.orbitsearch.com/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 "https://api.orbitsearch.com/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 "https://api.orbitsearch.com/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 search scoped to the directory.
curl
curl -X POST "https://api.orbitsearch.com/v2/developer/search" \
  -H "Authorization: Bearer $ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "founders in sf",
    "numUsers": 10,
    "searchScope": { "type": "directory", "directoryId": "DIRECTORY_UUID" }
  }'