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.

Search Directories let you build a private, searchable corpus of people data inside your organization. Instead of querying the global Orbit index, you query a corpus you control — populated from CSV uploads, connection imports, or other sources. This guide walks you through creating a directory, uploading your first CSV, checking that the data is indexed, and running a scoped search against it.
Directory search requires an organization API key — personal API keys are rejected. Your key must belong to the directory’s organization and have an organization-level or direct API-key grant with search or manage permission. Use your user session token ($USER_ACCESS_TOKEN) for directory management calls (create, upload, check status), and your organization API key ($ORG_API_KEY) for search calls.

​
Steps

1

Create a directory

Create a new directory inside your organization. Replace $ORGANIZATION_ID with your organization’s UUID.
curl -X POST "$API_BASE/v2/organizations/$ORGANIZATION_ID/directories" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Contacts"}'
Store the directoryId from the response — you need it for uploads, readiness checks, grants, and search.
2

Find existing directory IDs

If the directory already exists, list the organization’s directories and use each returned id as a DIRECTORY_ID.
curl
curl "$API_BASE/v2/organizations/$ORGANIZATION_ID/directories" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
The response includes id, name, type, and org_id for each directory. Use id in searchScope.directoryId, or collect multiple id values for searchScope.directoryIds.
3

Upload a CSV

Upload a CSV file to create a new source inside the directory. Send the file as a multipart form with the field name file. You can optionally include an idempotency_key to make the upload safe to retry.
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" \
  -F "idempotency_key=upload-contacts-2026-05-05"
The response includes a source_id, row counts, and an initial source_status. Store the sourceId — you need it to poll for readiness.
Uploads are incremental. Each CSV you upload creates a new source inside the directory rather than replacing existing data. If you upload three CSVs, all three contribute to the same searchable corpus. To safely re-upload the same file without creating a duplicate source, pass the same idempotency_key — the server will return the existing source instead of creating a new one.
4

Check source status and wait for readiness

Large uploads are processed asynchronously. Poll the source status endpoint until source_status indicates the source is ready before running a search.
curl "$API_BASE/v2/organizations/$ORGANIZATION_ID/directories/$DIRECTORY_ID/sources/$SOURCE_ID/status" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
Example status response:
{
  "status": "success",
  "payload": {
    "source_id": "source-uuid",
    "directory_id": "directory-uuid",
    "source_status": "completed"
  }
}
You can also check overall directory readiness — useful when you have multiple sources and want to know whether the full corpus is ready to search:
curl "$API_BASE/v2/organizations/$ORGANIZATION_ID/directories/$DIRECTORY_ID/readiness" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
Wait until the directory is ready before proceeding to the search step. Searching a directory with unfinished sources may return incomplete results.
5

Search your directory

Run a scoped smart search against your directory by setting searchScope.type to "directory" and providing the directoryId. Use your organization API key for this request.
curl -X POST "$API_BASE/v2/social/profiles/searches/smart" \
  -H "Authorization: Bearer $ORG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "engineers",
    "numUsers": 10,
    "searchScope": {
      "type": "directory",
      "directoryId": "DIRECTORY_UUID"
    }
  }'
The response shape is identical to a global search. Results are limited to the people in your directory. Profiles that resolve to an Orbit account return full profile data; CSV rows that do not resolve return a directory fallback card with the fields from your upload.
Multi-directory search is supported — you can pass "type": "directories" with a directoryIds array — but all directories must belong to the same organization. Cross-organization multi-directory search is not supported and returns a search_directory_cross_org_scope_unsupported error.

​
Next steps

  • Learn how to manage access to directories using grants by calling POST /v2/organizations/:organizationId/directories/:directoryId/grants.
  • See all directory-related error codes in Error Handling.
  • Rotate the organization API key you’re using for directory search by following Key Rotation.