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.

A search directory is a private corpus of people that your organization owns and controls. Instead of searching all public Orbit profiles, you upload your own contact data — CSV files, imported connection lists — and search within that corpus. The same natural language query engine that powers global search runs against your directory, so the developer experience is identical.

​
Data model

Directories follow a four-level hierarchy: 
organization → directory → sources → searchable people
  • Organization — owns all directories, sources, people, and access grants. See Organizations for how organizations work.
  • Directory — an isolated searchable corpus inside one organization. Each directory has a standard or connections type.
  • Source — a feed into a directory. Sources materialize into directory people when processed.
  • Directory person — the resolved, searchable record produced from one source row.
Multiple sources can contribute to the same directory. When you add more data to a directory, you create an additional source rather than replacing the directory. Search reads the aggregate corpus across all completed sources.

​
Directory types

There are two directory types:
  • standard — a general-purpose directory you create and populate with uploaded sources.
  • connections — a special directory used for personal connections. Every Orbit user gets one automatically (see Personal connections below).

​
Source types

Sources are the feeds that populate a directory with searchable people.
Upload a CSV file to create a csv_upload source in a directory. The API parses the file, validates rows, materializes accepted rows into directory people, and returns row counts, validation failures, and warnings synchronously. You can upload additional CSVs into the same directory at any time — each upload becomes its own source, and all sources contribute to the searchable corpus.Uploads are idempotent when you provide an idempotency_key. Reusing the same key for the same upload skips duplicate processing.
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-2024-01"
Check source status and readiness through the source endpoints:
GET /v2/organizations/:organizationId/directories/:directoryId/sources/:sourceId/status
GET /v2/organizations/:organizationId/directories/:directoryId/readiness
A connection_import source is created when a user imports their professional connections. Connection imports write to the user’s Personal Connections directory through a stable source that is refreshed when new connections are uploaded.Start an import:
POST /v2/social/connections/import
Check import status:
GET /v2/social/connections/imports/:jobId

​
Personal connections

Every Orbit user automatically gets a personal organization with a connections-type directory named Personal Connections. When a user imports their professional connections, those connections materialize into this directory through a stable connection_import source. You can search a user’s Personal Connections directory using the directory scope with the directory’s ID, provided you have an organization API key with the appropriate grant.

​
Directory lifecycle

Create and manage directories using your normal user access token: 
POST   /v2/organizations/:organizationId/directories
GET    /v2/organizations/:organizationId/directories
GET    /v2/organizations/:organizationId/directories/:directoryId
PATCH  /v2/organizations/:organizationId/directories/:directoryId
POST   /v2/organizations/:organizationId/directories/:directoryId/archive
DELETE /v2/organizations/:organizationId/directories/:directoryId
Archived directories are rejected from search. You cannot search a directory until at least one source has finished processing.

​
Access permissions

Directory access is controlled by grants. Each grant assigns a permission to a principal.

​
Permissions

PermissionWhat it allows
searchRun directory-scoped searches against this directory
uploadUpload source data (CSV files) into this directory
manageManage directory metadata, sources, grants, and search

​
Grant principals

PrincipalWho gets access
organizationAll members and API keys in the organization
userOne specific organization member
api_keyOne specific organization API key
Manage grants with these endpoints: 
GET    /v2/organizations/:organizationId/directories/:directoryId/grants
POST   /v2/organizations/:organizationId/directories/:directoryId/grants
DELETE /v2/organizations/:organizationId/directories/:directoryId/grants/:grantId
Only organization API keys can search directories. Personal API keys are rejected for all directory-scoped search — even if the directory belongs to your personal organization. The key must also belong to the same organization as the directory and must have a matching grant with search or manage permission.

​
Searching a directory

Use the directory or directories scope on the smart search endpoint. Directory access is validated before credits are charged. Single directory: 
{
  "query": "festival programmers",
  "numUsers": 10,
  "searchScope": { "type": "directory", "directoryId": "DIRECTORY_UUID" }
}
Multiple directories from the same organization: 
{
  "query": "festival programmers",
  "numUsers": 10,
  "searchScope": {
    "type": "directories",
    "directoryIds": ["DIRECTORY_UUID_A", "DIRECTORY_UUID_B"]
  }
}
A multi-directory search must stay within a single organization. Cross-organization directory search is not supported and returns search_directory_cross_org_scope_unsupported. For a full walkthrough of setting up a directory and running your first search, see the Directory setup guide.